Awesome
Cypress Docker Images
Cypress Docker images are published to Cypress on Docker Hub.
These images provide all of the required dependencies for running Cypress in Docker.
We build four images: click on the image name to see the available tags and versions. We provide multiple tags for various operating systems and specific browser versions. These allow you to target specific combinations you need.
Image Name | Description | Monthly pulls |
---|---|---|
cypress/factory | A base image template which can be used with ARGs to create a custom docker image. | |
cypress/base | All operating system dependencies, no Cypress, and no browsers. | |
cypress/browsers | All operating system dependencies, no Cypress, and some browsers. | |
cypress/included | All operating system dependencies, Cypress, and some browsers installed globally. |
Platforms
Cypress Docker images are Linux based, using the Docker image debian:12-slim as the default base image. Each of the above listed Cypress Docker images is published with multi-architecture support for Linux/amd64
and Linux/arm64
platforms.
Cypress Docker images can be run as containers on Continuous Integration (CI) systems which support Docker. Cypress Docker images can also be run locally under Docker Desktop for Mac, Linux or Windows environments.
In the case of Windows environments, see Docker Desktop for Windows and Cypress documentation Windows Subsystem for Linux for additional information regarding Microsoft's WSL2
and WSLg
subsystems. The documentation and scripts in this repository assume that Docker Desktop for Windows runs in a virtual Linux environment.
Browsers
Cypress Docker images cypress/browsers include browsers for the Linux/amd64
platform. Availability is pending for the Linux/arm64
platform.
Browser | Linux/amd64 | Linux/arm64 |
---|---|---|
Google Chrome | :white_check_mark: | see #1188 |
Mozilla Firefox | :white_check_mark: | see #1190 and examples/firefox-esr |
Microsoft Edge | :white_check_mark: | see #1189 |
On POSIX-based systems, or with Git for Windows at a Git Bash prompt, execute uname -m
to display your system's architecture. (x86_64 is equivalent to amd64
.)
cypress/included images, which are built on top of cypress/browsers, contain the same set of browsers.
Tags for cypress/browsers and cypress/included images show which versions of the browsers are loaded into the respective image. (Disregard the browser version tags for current Linux/arm64
images however.)
Building a custom image with cypress/factory allows selection of individual browsers from the above list.
<!-- browser links -->Debian packages
Debian provides two Cypress-compatible browsers as packages covering both amd64
and arm64
architectures.
These can be used to complement the browsers that are configurable through the cypress/factory
build process:
-
See the directory examples/chromium to add the current version of Chromium for Debian to Cypress Docker images. The Debian Chromium Wiki describes the Chromium browser distribution details. Chromium is not currently included in the
cypress/factory
build process. See #1191 for progress of this integration. -
See the directory examples/firefox-esr to add Firefox ESR for Debian to Cypress Docker images. The Debian Firefox Wiki describes the Firefox browser distribution details from the Extended Support Release channel. This differs from the
cypress/factory
build process which uses Firefoxamd64
versions from the Rapid Release channel. See #1190 for availability of Firefoxarm64
Rapid Release versions.
Tag Selection
If no tag is specified, for example cypress/included
, then the tag latest
is used by default: cypress/included:latest
. It is however recommended to use a specific image tag to avoid breaking changes when new images are released, especially when they include new major versions of Node.js or Cypress.
Some examples with specific tags including an explanation of the tag meanings are:
- cypress/base:20.14.0
Node.js
20.14.0
- cypress/browsers:node-20.14.0-chrome-125.0.6422.141-1-ff-126.0.1-edge-125.0.2535.85-1
Node.js
20.14.0
Chrome125.0.6422.141-1
Firefox126.0.1
Edge125.0.2535.85-1
- cypress/included:13.11.0
Cypress
13.11.0
Once an image with a specific version tag (except latest
) has been published to Cypress on Docker Hub it is frozen. This prevents accidental changes.
When a new version is published, an image copy with the latest
tag is also published. This means that the Docker image selected using the latest
tag (or selected by default if no tag is specified) will also change over time. Specify an explicit version, for example cypress/base:18.16.0, to access instead a frozen version.
Usage
đź“ŤCypress Docker images are offered as a convenience measure. The goal is to offer Node.js, Browser and Cypress versions to streamline running tests in CI or other non-public, sandboxed environments.
Some preparations and optimizations are not included. For example, given the near infinite permutations, images are not monitored for security vulnerabilities. Additionally, once images are published they are considered immutable and cannot be patched. That means (hypothetically) older images could become more vulnerable over time.
This means they should not be used for production deployment and security scans should be performed as-needed by users of these images.
Docker Hub
All of the images and tags are published to Cypress on Docker Hub under:
- https://hub.docker.com/r/cypress/factory
- https://hub.docker.com/r/cypress/base
- https://hub.docker.com/r/cypress/browsers
- https://hub.docker.com/r/cypress/included
Cypress/Factory
Don't see the exact combination of Cypress, Node.js and browser versions you need for your test environment? Checkout our cypress/factory. You can use it to generate a custom image to fit your needs.
Examples
-
Check out the documentation for each type of Cypress Docker image to read about example usage: cypress/base, cypress/browsers and cypress/included can all be used directly without change. Each of the Docker images can be used to build other images. cypress/factory is the preferred image to generate custom images.
-
Refer to CI Docker examples for links to examples of using Cypress Docker images with different Continuous Integration (CI) providers. See also the example workflow .github/workflows/example-cypress-github-action.yml in this repository for CI usage with cypress‑io/github‑action running under the CI provider GitHub Actions.
User
By default, Docker containers run as root
user. cypress/base, cypress/browsers and cypress/included images provide the additional non-root user node
.
If you run a Cypress Docker image locally as container with a non-root user, refer to the Docker documentation, such as Docker Desktop FAQs, for information on file-sharing between your host system and Docker. File-sharing details differ depending on the host operating system running Docker.
If you specify a Cypress Docker image in a GitHub Actions job container
workflow section, add options: --user 1001
to the workflow to avoid permissions issues.
Debug logs
To enable all Cypress debug logs when running Cypress in a Docker container, set the environment variable DEBUG
to the value cypress:*
. To filter the debug logs read Log sources for alternate values of DEBUG
.
- For
docker run
in a command line, refer to docker run: set environment variables for options to pass environment variables to a Docker container. - In a Continuous Integration (CI) workflow using a Cypress Docker image, refer to your CI documentation for information on setting environment variables.
Known problems
Firefox not found
Problem
When running in GitHub Actions using a cypress/browsers
or cypress/included
image and testing against the Mozilla Firefox browser with the default root
user, Cypress may fail to detect an installed Firefox browser. Instead Cypress shows the following error message:
Browser: firefox was not found on your system or is not supported by Cypress. Can't run because you've entered an invalid browser name.
The GitHub Actions Runner creates the /github/home
directory with non-root ownership 1001
(runner
) and sets the environment variable HOME
to point to this directory. Firefox will not run with these settings. If the command firefox --version
is executed, Firefox explains the restriction:
Running Firefox as root in a regular user's session is not supported. ($HOME is /github/home which is owned by uid 1001.)
See Cypress issue #27121.
Resolution
To allow Firefox to run in GitHub Actions in a Docker container, add options: --user 1001
to the workflow to match GitHub Actions' runner
user.
container:
image: cypress/browsers
options: --user 1001
See Tag Selection above for advice on selecting a non-default image tag.
Contributing
See CONTRIBUTING.md
License
See LICENSE