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.

Practice

1. What is the main benefit of running Cypress tests inside a Docker container?

easy

A. It provides a clean and consistent environment for tests.

B. It makes tests run faster on all machines.

C. It automatically fixes test failures.

D. It removes the need for writing test code.

Solution

1. Step 1: Understand Docker's role in testing

   Docker creates isolated environments that are the same everywhere.

2. Step 2: Connect Docker benefits to Cypress tests

   Running Cypress in Docker ensures tests run in a clean, consistent setup, avoiding environment differences.

3. Final Answer:

   It provides a clean and consistent environment for tests. -> Option A

4. Quick Check:

   Docker = consistent test environment [OK]

Hint: Docker ensures same environment everywhere for tests [OK]

Common Mistakes:

• Thinking Docker speeds up tests automatically
• Believing Docker fixes test code errors
• Assuming Docker removes need for tests

2. Which Docker command correctly runs Cypress tests mounting the current folder as a volume?

easy

A. docker run -v $(pwd):/e2e -w /e2e cypress/included:12.0.0

B. docker run -p 8080:80 cypress/included:12.0.0

C. docker build -t cypress-test .

D. docker run cypress/included:12.0.0 --no-volume

Solution

1. Step 1: Identify volume mounting syntax

   The -v option mounts a folder; $(pwd):/e2e mounts current folder to /e2e in container.

2. Step 2: Check command correctness

   docker run -v $(pwd):/e2e -w /e2e cypress/included:12.0.0 uses -v and -w to set working directory, which is correct for running Cypress tests.

3. Final Answer:

   docker run -v $(pwd):/e2e -w /e2e cypress/included:12.0.0 -> Option A

4. Quick Check:

   Volume mount = -v [OK]

Hint: Use -v to mount volumes in Docker run command [OK]

Common Mistakes:

• Using -p instead of -v for volume mounting
• Forgetting to set working directory with -w
• Confusing docker build with docker run

3. Given this Docker command:

docker run -v $(pwd):/e2e -w /e2e cypress/included:12.0.0

What will happen if your current folder has no Cypress tests?

medium

A. Docker will throw a syntax error and stop.

B. The container will fail to start due to missing tests.

C. Cypress will automatically create sample tests.

D. The container will run but no tests will execute.

Solution

1. Step 1: Understand volume mounting effect

   The current folder is mounted inside the container at /e2e, so container sees the files you have.

2. Step 2: Consider what happens with no tests

   If no test files exist, Cypress runs but finds nothing to execute, so no tests run but container runs fine.

3. Final Answer:

   The container will run but no tests will execute. -> Option D

4. Quick Check:

   No tests = no execution, container still runs [OK]

Hint: No tests means no runs, but container still starts [OK]

Common Mistakes:

• Expecting Docker syntax error for missing files
• Thinking Cypress auto-generates tests
• Assuming container fails to start without tests

4. You run Cypress tests in Docker but see this error:
ERROR: Cannot find module 'cypress'
What is the most likely cause?

medium

A. You forgot to mount your test folder with node_modules.

B. You used the wrong Docker image without Cypress installed.

C. Your Dockerfile syntax is incorrect.

D. Your tests have syntax errors.

Solution

1. Step 1: Analyze the error message

   The error says Cypress module is missing, meaning Cypress is not installed in the container.

2. Step 2: Check Docker image used

   If you use a Docker image without Cypress pre-installed, this error occurs. Using cypress/included images avoids this.

3. Final Answer:

   You used the wrong Docker image without Cypress installed. -> Option B

4. Quick Check:

   Missing module = wrong image [OK]

Hint: Use official cypress/included image to avoid missing Cypress [OK]

Common Mistakes:

• Blaming test syntax errors for missing module
• Assuming volume mount fixes missing Cypress
• Confusing Dockerfile syntax with missing module

5. You want to run Cypress tests in Docker and save screenshots and videos outside the container. Which command correctly achieves this?

hard

A. docker run -p 8080:80 -v $(pwd):/e2e cypress/included:12.0.0

B. docker run -v $(pwd):/e2e -w /e2e cypress/included:12.0.0 --save-artifacts

C. docker run -v $(pwd):/e2e -v $(pwd)/cypress/screenshots:/e2e/cypress/screenshots -v $(pwd)/cypress/videos:/e2e/cypress/videos -w /e2e cypress/included:12.0.0

D. docker run --rm cypress/included:12.0.0

Solution

1. Step 1: Understand volume mounting for artifacts

   To save screenshots and videos outside Docker, mount their folders as volumes from host to container.

2. Step 2: Check command for multiple volume mounts

   docker run -v $(pwd):/e2e -v $(pwd)/cypress/screenshots:/e2e/cypress/screenshots -v $(pwd)/cypress/videos:/e2e/cypress/videos -w /e2e cypress/included:12.0.0 mounts the whole project plus screenshots and videos folders separately, ensuring artifacts persist on host.

3. Final Answer:

   docker run -v $(pwd):/e2e -v $(pwd)/cypress/screenshots:/e2e/cypress/screenshots -v $(pwd)/cypress/videos:/e2e/cypress/videos -w /e2e cypress/included:12.0.0 -> Option C

4. Quick Check:

   Mount artifact folders to save outside container [OK]

Hint: Mount screenshots and videos folders as volumes [OK]

Common Mistakes:

• Not mounting screenshots/videos folders separately
• Using -p port mapping instead of volume mounts
• Assuming --save-artifacts flag exists