Docker execution in Cypress - Framework Patterns

Framework Mode - Docker execution

Folder Structure

  cypress-docker-project/
  ├── cypress/
  │   ├── e2e/                 # Test specs
  │   ├── fixtures/            # Test data files
  │   ├── support/             # Custom commands and support files
  ├── cypress.config.js        # Cypress configuration
  ├── Dockerfile               # Docker image build instructions
  ├── docker-compose.yml       # Optional: orchestrate containers
  ├── package.json             # Project dependencies and scripts
  ├── package-lock.json        # Dependency lock file
  └── README.md                # Project documentation
  

Test Framework Layers

• Test Specs (cypress/e2e): Contains the actual test scripts written in JavaScript using Cypress syntax.
• Support Layer (cypress/support): Holds reusable commands, custom functions, and global configurations for tests.
• Fixtures (cypress/fixtures): Static test data files (JSON, CSV) used to feed tests with consistent data.
• Configuration (cypress.config.js): Defines test settings like base URL, timeouts, browser preferences.
• Docker Layer: Dockerfile defines the environment to run Cypress tests inside a container, ensuring consistency across machines.
• Package Management: package.json manages Cypress and related dependencies, scripts to run tests inside or outside Docker.

Configuration Patterns

• Environment Variables: Use env in cypress.config.js or Docker environment variables to switch URLs, credentials, or modes.
• Dockerfile: Base image cypress/included:12.17.1 (or latest) includes Cypress and browsers pre-installed.
• docker-compose.yml: Optional for multi-container setups, can define environment variables and volumes for test artifacts.
• Credentials: Pass sensitive data via Docker secrets or environment variables, avoid hardcoding in code or config files.
• Browser Selection: Configure browsers in Cypress config or override via Docker run commands.

Test Reporting and CI/CD Integration

• Test Reports: Generate reports using Cypress plugins (e.g., mochawesome) and save them to mounted volumes for persistence outside the container.
• CI/CD Pipelines: Integrate Dockerized Cypress tests in pipelines (GitHub Actions, Jenkins, GitLab CI) by running docker run commands or using docker-compose.
• Artifacts: Store screenshots, videos, and reports by mounting host directories into the container.
• Fail Fast: Configure Cypress to fail tests on first error to save CI time.
• Parallel Execution: Use Cypress Dashboard service or split tests in CI with Docker containers for faster feedback.

Best Practices

1. Use Official Cypress Docker Images: They come pre-installed with browsers and Cypress, reducing setup complexity.
2. Keep Tests Stateless: Avoid dependencies on local machine state to ensure tests run reliably inside containers.
3. Mount Volumes for Artifacts: Save screenshots, videos, and logs outside the container for easy access and debugging.
4. Parameterize Configurations: Use environment variables to switch between test environments without changing code.
5. Automate in CI/CD: Run Dockerized tests automatically on code changes to catch issues early.

Self Check

Where in this folder structure would you add a new custom command to reuse in multiple tests?

Key Result

Use Docker to run Cypress tests in a consistent, isolated environment with official images and environment-based configuration.