Running Cypress with Docker

Docker removes "works on my machine, not in CI" environment inconsistencies by packaging an exact, reproducible environment. This lesson covers the official Cypress Docker images and how to use them.

Official Cypress Docker Images

Cypress publishes several official Docker images with different levels of pre-installed tooling: cypress/base (Node and browser dependencies, no Cypress itself), and cypress/included (a specific Cypress version and browsers, ready to run immediately).

# Run tests directly with cypress/included, no local install needed
docker run -it -v $PWD:/e2e -w /e2e cypress/included:13.6.0

This mounts your project into the container and runs Cypress using a pinned, known-good version and browser set.

Common Cypress Docker Images

cypress/base:20         // Node + browser dependencies, no Cypress
cypress/browsers:...    // base + specific extra browsers pre-installed
cypress/included:13.6.0 // Cypress + browsers pre-installed, ready to run
cypress/factory         // build a custom combination via build args

cypress/included is the fastest way to get a fully ready Cypress environment with zero extra setup.
cypress/base is useful when you want full control over which exact Cypress version gets installed via npm.
Pinning a specific image tag (not latest) keeps CI runs reproducible across time.
Volume-mounting your project directory lets the container run against your actual codebase.

Docker Images Cheat Sheet

Choosing the right official Cypress Docker image for a given need.

Image	Contains	Best For
`cypress/base`	Node + OS/browser dependencies	Custom setups installing Cypress via npm
`cypress/browsers`	Base + specific browser versions	Multi-browser testing needs
`cypress/included`	A specific Cypress version + browsers	Fastest, zero-setup CI runs
Custom `Dockerfile`	Your own combination	Highly specific dependency requirements

A Custom Dockerfile Example

For projects needing extra system dependencies alongside Cypress, extending cypress/base with a custom Dockerfile gives full control while still starting from a maintained, known-compatible foundation.

FROM cypress/base:20

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npx cypress verify

CMD ["npx", "cypress", "run"]

cypress verify confirms the installed Cypress binary can actually execute correctly inside this specific image.

Using Docker Images Inside CI Pipelines

Most CI providers, including GitHub Actions and Jenkins, support specifying a container image for a job directly, letting you combine Docker's environment consistency with your existing CI platform's orchestration.

# GitHub Actions example
jobs:
  cypress-run:
    runs-on: ubuntu-latest
    container: cypress/included:13.6.0
    steps:
      - uses: actions/checkout@v4
      - run: cypress run

Common Mistakes

Using the latest tag for a Cypress Docker image, causing unpredictable version drift over time.
Not running cypress verify after a custom image build, missing a broken installation until tests actually run.
Rebuilding a custom image from scratch when an official image already covers the exact need.
Forgetting to volume-mount the project directory, running Cypress against an empty or stale container filesystem.

Key Takeaways

Official Cypress Docker images range from bare dependencies (cypress/base) to fully ready (cypress/included).
Pinning specific image tags keeps CI environments reproducible over time.
Custom Dockerfiles can extend cypress/base for project-specific dependency needs.
Most CI platforms support running jobs directly inside a specified container image.

Pro Tip

Pin your Cypress Docker image tag to match your project's exact cypress npm package version, mismatches between the two are a subtle, occasionally hard-to-diagnose source of "works differently in CI" issues that are easy to avoid entirely with careful version alignment.