How to Use Cypress with Docker for Automated Testing

To use Cypress with Docker, create a Dockerfile that installs Cypress and your app dependencies, then run Cypress tests inside the container using docker run. This approach ensures consistent test environments and simplifies integration with CI pipelines.

Syntax

Here is the basic syntax to run Cypress tests inside a Docker container:

• FROM: Specifies the base Docker image with Cypress pre-installed.
• WORKDIR: Sets the working directory inside the container.
• COPY: Copies your project files into the container.
• RUN: Installs dependencies.
• CMD: Runs Cypress tests.
• docker build: Builds the Docker image.
• docker run: Runs the container and executes tests.

Dockerfile

FROM cypress/included:12.17.1
WORKDIR /e2e
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["npx", "cypress", "run"]

Example

This example Dockerfile sets up Cypress tests for a project. It uses the official Cypress Docker image, installs dependencies, copies test files, and runs tests automatically when the container starts.

Dockerfile

FROM cypress/included:12.17.1
WORKDIR /e2e
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["npx", "cypress", "run"]

Output

====================================================================================================
  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:    12.17.1                                                                           │
  │ Browser:    Electron 112 (headless)                                                          │
  │ Specs:      1 found                                                                          │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘

────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  example_spec.js                                                                    (1 of 1)

  ✓ visits the example page


  1 passing

  (Results)

  Tests:        1
  Passing:      1
  Failing:      0
  Pending:      0
  Skipped:      0

====================================================================================================
  (Run Finished)

Common Pitfalls

Common mistakes when using Cypress with Docker include:

• Not using the official Cypress Docker image, which already includes all dependencies.
• Forgetting to copy all necessary files, causing tests to fail due to missing code.
• Running tests without setting the working directory correctly.
• Not exposing ports or configuring network if your app runs inside another container.

Always use the cypress/included image for simplicity and ensure your package.json and tests are copied properly.

Dockerfile

### Wrong Dockerfile example (missing dependencies and wrong base image)
FROM node:16
WORKDIR /app
COPY . .
CMD ["npx", "cypress", "run"]

### Correct Dockerfile example
FROM cypress/included:12.17.1
WORKDIR /e2e
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["npx", "cypress", "run"]

Quick Reference

Tips for using Cypress with Docker:

• Use the official cypress/included Docker image for easiest setup.
• Copy only necessary files to keep image size small.
• Run npm ci to install exact dependencies.
• Run tests headlessly inside the container with npx cypress run.
• Integrate with CI by running Docker commands in your pipeline.

Key Takeaways

Use the official cypress/included Docker image to simplify setup and avoid missing dependencies.

Copy your project files and install dependencies inside the Docker container before running tests.

Run Cypress tests headlessly inside Docker with the command npx cypress run.

Ensure your Dockerfile sets the correct working directory and copies all needed files.

Dockerizing Cypress tests helps create consistent environments and simplifies CI integration.