# Cypress E2E Testing Stack

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

- Category: Development Tools
- Difficulty: intermediate
- Components: cypress, sorry-cypress-director, sorry-cypress-dashboard, mongodb
- Tags: cypress, testing, e2e, javascript, dashboard
- Source: https://docker.recipes/development/cypress-testing

## 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.

## 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

## Use cases

- Large development teams needing parallel E2E test execution to reduce CI/CD pipeline duration
- Enterprises requiring self-hosted testing infrastructure for compliance or security policies
- Startups avoiding Cypress Dashboard subscription costs while scaling test automation
- Organizations with multiple projects needing centralized test result management
- Development teams implementing comprehensive E2E testing across staging and production environments
- Companies requiring test execution history and analytics for quality metrics reporting
- DevOps 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

## docker-compose.yml

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

  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:
    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:
    image: agoldis/sorry-cypress-dashboard:latest
    environment:
      - GRAPHQL_SCHEMA_URL=http://api:4000
    ports:
      - "8080:8080"
    depends_on:
      - api
    networks:
      - cypress_net

  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

volumes:
  mongo_data:

networks:
  cypress_net:
```

## .env

```bash
# Cypress with Sorry Cypress
# Dashboard at http://localhost:8080
# Director at http://localhost:1234
# Run tests: docker compose --profile test up
```

## Usage notes

- Dashboard at http://localhost:8080
- Director API at localhost:1234
- Free Cypress Dashboard alternative
- Parallel test execution support
- Configure cy2 for cloud recording

## 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

