Cypress E2E Testing Stack

intermediate

End-to-end testing with Cypress Dashboard and parallel execution.

Overview

Cypress is a next-generation front-end testing tool built for modern web applications. Originally created by Brian Mann in 2015, Cypress revolutionized end-to-end testing by running directly in the browser, providing real-time reloads, time travel debugging, and automatic waiting. Unlike traditional testing frameworks like Selenium that operate outside the browser, Cypress executes commands directly in the same run loop as your application, enabling more reliable and faster test execution. Sorry-cypress is an open-source alternative to Cypress Dashboard that enables parallel test execution, test recording, and result management without vendor lock-in. This stack combines Cypress with sorry-cypress-director for orchestrating parallel test runs, sorry-cypress-api for GraphQL data access, and sorry-cypress-dashboard for visualizing test results, all backed by MongoDB for persistent test data storage. The director service acts as a load balancer, distributing test specs across multiple Cypress runners to dramatically reduce execution time. Development teams struggling with slow sequential test suites, expensive Cypress Dashboard subscriptions, or enterprise requirements for self-hosted testing infrastructure will find this stack invaluable. The combination provides enterprise-grade parallel testing capabilities while maintaining complete control over test data and infrastructure, making it ideal for organizations with compliance requirements or cost optimization goals.

Key Features

Sorry-cypress director orchestrates parallel test execution across multiple Cypress runners
GraphQL API provides flexible querying of test results, runs, and project statistics
Real-time dashboard displays test progress, failure screenshots, and video recordings
MongoDB stores complete test execution history with indexing for fast result retrieval
Cypress runner containers can be scaled horizontally for faster test completion
Test artifact management with automatic screenshot and video capture on failures
Project-based organization with support for multiple testing environments
Alternative to Cypress Dashboard with no monthly usage limits or runner restrictions

Common Use Cases

1Large development teams needing parallel E2E test execution to reduce CI/CD pipeline duration
2Enterprises requiring self-hosted testing infrastructure for compliance or security policies
3Startups avoiding Cypress Dashboard subscription costs while scaling test automation
4Organizations with multiple projects needing centralized test result management
5Development teams implementing comprehensive E2E testing across staging and production environments
6Companies requiring test execution history and analytics for quality metrics reporting
7DevOps teams building custom testing workflows integrated with existing monitoring systems

Prerequisites

Docker Engine 20.10+ and Docker Compose V2 for container orchestration
Minimum 4GB RAM available (2GB for MongoDB, 1GB per Cypress runner instance)
Ports 1234, 4000, and 8080 available for director, API, and dashboard services
Cypress test project structure with cypress.config.js configured for sorry-cypress
Node.js knowledge for writing and maintaining Cypress test specifications
Understanding of GraphQL for custom dashboard queries and integrations

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  mongodb: 
3    image: mongo:6
4    volumes: 
5      - mongo_data:/data/db
6    networks: 
7      - cypress_net
8
9  director: 
10    image: agoldis/sorry-cypress-director:latest
11    environment: 
12      - DASHBOARD_URL=http://localhost:8080
13      - MONGODB_URI=mongodb://mongodb:27017
14      - MONGODB_DATABASE=sorry-cypress
15    ports: 
16      - "1234:1234"
17    depends_on: 
18      - mongodb
19    networks: 
20      - cypress_net
21
22  api: 
23    image: agoldis/sorry-cypress-api:latest
24    environment: 
25      - MONGODB_URI=mongodb://mongodb:27017
26      - MONGODB_DATABASE=sorry-cypress
27    ports: 
28      - "4000:4000"
29    depends_on: 
30      - mongodb
31    networks: 
32      - cypress_net
33
34  dashboard: 
35    image: agoldis/sorry-cypress-dashboard:latest
36    environment: 
37      - GRAPHQL_SCHEMA_URL=http://api:4000
38    ports: 
39      - "8080:8080"
40    depends_on: 
41      - api
42    networks: 
43      - cypress_net
44
45  cypress-runner: 
46    image: cypress/included:latest
47    working_dir: /e2e
48    volumes: 
49      - ./cypress:/e2e
50    environment: 
51      - CYPRESS_API_URL=http://director:1234
52    depends_on: 
53      - director
54    networks: 
55      - cypress_net
56    profiles: 
57      - test
58
59volumes: 
60  mongo_data: 
61
62networks: 
63  cypress_net:

.env Template

.env

1# Cypress with Sorry Cypress
2# Dashboard at http://localhost:8080
3# Director at http://localhost:1234
4# Run tests: docker compose --profile test up

Usage Notes

1Dashboard at http://localhost:8080
2Director API at localhost:1234
3Free Cypress Dashboard alternative
4Parallel test execution support
5Configure cy2 for cloud recording

Individual Services(5 services)

Copy individual services to mix and match with your existing compose files.

mongodb

mongodb:
  image: mongo:6
  volumes:
    - mongo_data:/data/db
  networks:
    - cypress_net

director

director:
  image: agoldis/sorry-cypress-director:latest
  environment:
    - DASHBOARD_URL=http://localhost:8080
    - MONGODB_URI=mongodb://mongodb:27017
    - MONGODB_DATABASE=sorry-cypress
  ports:
    - "1234:1234"
  depends_on:
    - mongodb
  networks:
    - cypress_net

api

api:
  image: agoldis/sorry-cypress-api:latest
  environment:
    - MONGODB_URI=mongodb://mongodb:27017
    - MONGODB_DATABASE=sorry-cypress
  ports:
    - "4000:4000"
  depends_on:
    - mongodb
  networks:
    - cypress_net

dashboard

dashboard:
  image: agoldis/sorry-cypress-dashboard:latest
  environment:
    - GRAPHQL_SCHEMA_URL=http://api:4000
  ports:
    - "8080:8080"
  depends_on:
    - api
  networks:
    - cypress_net

cypress-runner

cypress-runner:
  image: cypress/included:latest
  working_dir: /e2e
  volumes:
    - ./cypress:/e2e
  environment:
    - CYPRESS_API_URL=http://director:1234
  depends_on:
    - director
  networks:
    - cypress_net
  profiles:
    - test

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  mongodb:
5    image: mongo:6
6    volumes:
7      - mongo_data:/data/db
8    networks:
9      - cypress_net
10
11  director:
12    image: agoldis/sorry-cypress-director:latest
13    environment:
14      - DASHBOARD_URL=http://localhost:8080
15      - MONGODB_URI=mongodb://mongodb:27017
16      - MONGODB_DATABASE=sorry-cypress
17    ports:
18      - "1234:1234"
19    depends_on:
20      - mongodb
21    networks:
22      - cypress_net
23
24  api:
25    image: agoldis/sorry-cypress-api:latest
26    environment:
27      - MONGODB_URI=mongodb://mongodb:27017
28      - MONGODB_DATABASE=sorry-cypress
29    ports:
30      - "4000:4000"
31    depends_on:
32      - mongodb
33    networks:
34      - cypress_net
35
36  dashboard:
37    image: agoldis/sorry-cypress-dashboard:latest
38    environment:
39      - GRAPHQL_SCHEMA_URL=http://api:4000
40    ports:
41      - "8080:8080"
42    depends_on:
43      - api
44    networks:
45      - cypress_net
46
47  cypress-runner:
48    image: cypress/included:latest
49    working_dir: /e2e
50    volumes:
51      - ./cypress:/e2e
52    environment:
53      - CYPRESS_API_URL=http://director:1234
54    depends_on:
55      - director
56    networks:
57      - cypress_net
58    profiles:
59      - test
60
61volumes:
62  mongo_data:
63
64networks:
65  cypress_net:
66EOF
67
68# 2. Create the .env file
69cat > .env << 'EOF'
70# Cypress with Sorry Cypress
71# Dashboard at http://localhost:8080
72# Director at http://localhost:1234
73# Run tests: docker compose --profile test up
74EOF
75
76# 3. Start the services
77docker compose up -d
78
79# 4. View logs
80docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/cypress-testing/run | bash

Troubleshooting

Cypress tests not appearing in dashboard: Verify CYPRESS_API_URL environment variable points to director service on port 1234
MongoDB connection failures in director logs: Check MONGODB_URI format and ensure mongodb service is healthy before director starts
Dashboard showing 'GraphQL endpoint unreachable': Confirm GRAPHQL_SCHEMA_URL in dashboard service matches api service internal network address
Cypress runner exits immediately without tests: Ensure cypress project directory is properly mounted and contains valid cypress.config.js
Parallel execution not working: Verify cy2 binary configuration and director service accessibility from runner containers
Test artifacts not displaying: Check volume mounts for screenshots/videos and verify api service can access MongoDB collections

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

cypresssorry-cypress-directorsorry-cypress-dashboardmongodb

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download