included

cypress/included

Docker images with all operating system dependencies, Cypress, and some pre-installed browsers.

Platforms

cypress/included images are available for Linux/amd64 and Linux/arm64 platforms. Linux/arm64 images do not currently contain additional browsers.

Tags

cypress/included images on Cypress on Docker Hub use image tags in the form:

• cypress-<cypress version>-node-<node version>-chrome-<chrome version>-ff-<firefox version>-edge-<edge version>
• <cypress version>
  This is a short-form convenience tag, equivalent to the above full tag.
• latest

for example:

• cypress/included:cypress-13.15.1-node-22.11.0-chrome-130.0.6723.69-1-ff-132.0-edge-130.0.2849.56-1
• cypress/included:13.15.1
• cypress/included:latest

To avoid unplanned breaking changes, specify a fixed <cypress version>, <node version> & <browser version> combination tag or use the short-form <cypress version> tag, not the latest tag. The latest tag is linked to the latest released cypress/included image and is updated without notice.

ENTRYPOINT

cypress/included images have their Docker ENTRYPOINT set to "cypress" "run".

To run a cypress/included image using cypress run, for instance to run all test specs in the default Electron browser, no additional docker run CLI options are needed.

To use cypress run options, such as -b chrome, use the docker run command with --entrypoint cypress to overwrite the default ENTRYPOINT of the cypress/included image.

To run bash commands interactively in the image, for instance to inspect files, directories or to run Cypress interactively, use the docker run command with --entrypoint bash.

See below for examples.

Examples

Tip

Remove cypress from your project's package.json to avoid version mismatch between your project and the cypress/included Docker image.

The directory examples/basic-mini in this repo provides an example project which includes a Cypress E2E test spec and has no Cypress version included in its package.json.

Docker interactive

In this example we first run the image cypress/included as a container, overriding the default command of cypress run using --entrypoint bash to enter the interactive bash shell.

cd examples/basic-mini         # Use a pre-configured simple Cypress E2E project
docker run -it --rm -v .:/app -w /app --entrypoint bash cypress/included  # Run image as container

At the bash prompt :/app#, we can then enter the following commands:

ls -al                    # Check the contents of our working directory
npx cypress run -b chrome # Run Cypress test in Chrome
exit

Docker default

In this example we let the Docker image handle running Cypress automatically through the pre-defined cypress run command. This runs Cypress with the default Electron browser:

cd examples/basic-mini         # Use a pre-configured simple Cypress E2E project
docker run -it --rm -v .:/app -w /app cypress/included  # Run image as container and execute cypress run

Browser

To run cypress/included using one of the installed browsers (Chrome, Edge or Firefox), we change to --entrypoint cypress and add the command run -b chrome, for instance, to test against the Chrome browser:

cd examples/basic-mini
docker run -it --rm -v .:/app -w /app --entrypoint cypress cypress/included run -b chrome

Debug

To see Cypress debug logs during the run, pass the environment variable setting with -e DEBUG=cypress:*:

cd examples/basic-mini
docker run -it --rm -v .:/app -w /app -e DEBUG=cypress:* cypress/included

Single test spec

To run a single test spec using the Chrome browser:

cd examples/basic-mini
docker run -it --rm -v .:/app -w /app --entrypoint cypress cypress/included run --spec cypress/e2e/spec.cy.js -b chrome

Info

To run cypress info which prints information about Cypress and the current environment:

cd examples/basic-mini
docker run -it --rm --entrypoint cypress cypress/included info

DevTools listening on ws://127.0.0.1:36243/devtools/browser/eb85524a-6459-41d6-b855-94c10cd2b242
Displaying Cypress info...

Detected 3 browsers installed:

1. Chrome
  - Name: chrome
  - Channel: stable
  - Version: 130.0.6723.69
  - Executable: google-chrome

2. Edge
  - Name: edge
  - Channel: stable
  - Version: 130.0.2849.56
  - Executable: edge

3. Firefox
  - Name: firefox
  - Channel: stable
  - Version: 132.0
  - Executable: firefox

Note: to run these browsers, pass <name>:<channel> to the '--browser' field

Examples:
- cypress run --browser firefox
- cypress run --browser chrome

Learn More: https://on.cypress.io/launching-browsers

Proxy Settings: none detected
Environment Variables:
CYPRESS_CACHE_FOLDER: /root/.cache/Cypress
CYPRESS_FACTORY_DEFAULT_NODE_VERSION: 22.11.0

Application Data: /root/.config/cypress/cy/development
Browser Profiles: /root/.config/cypress/cy/development/browsers
Binary Caches: /root/.cache/Cypress

Cypress Version: 13.15.1 (stable)
System Platform: linux (Debian - 12.7)
System Memory: 5.16 GB free 4.12 GB

User

By default, cypress/included images run as root user. You can switch to the non-root user node in the image or to a custom user.

• examples/included-as-non-root describes how to run tests as non-root user node using a cypress/included image

Continuous Integration

cypress/included images are a convenient tool to run Cypress tests from the command line with all dependencies pre-installed. With their corresponding fixed version of Cypress, they are not primarily intended for use in Continuous Integration (CI) workflows.

cypress/base and cypress/browsers images, which are independent of the Cypress version used, are generally better suited for CI use. The required version of Cypress is then dynamically installed into the workflow with one of the package managers supported by Cypress.

If you do use cypress/included in CI, note the special handling recommended in the following sections:

GitHub Actions

The example workflow .github/workflows/example-cypress-github-action.yml, job docker-included, demonstrates how to use a cypress/included image in a GitHub Actions workflow.

If you use a cypress/included image in a GitHub Actions workflow that executes the Cypress JavaScript GitHub Action cypress-io/github-action, it is recommended to set the environment variable CYPRESS_INSTALL_BINARY=0 to skip Cypress binary installation. This avoids unnecessary caching attempts for the Cypress binary. cypress/included images already include the cached Cypress binary and additional caching attempts with a non-root user can lead to non-fatal error messages. The example workflow, mentioned above, shows how to set the environment variable CYPRESS_INSTALL_BINARY.

GitLab Pipelines

If you use a cypress/included image in a GitLab CI/CD pipeline you need to override the default entrypoint with an empty value, otherwise the pipeline will fail.

For example:

  image:
    name: cypress/included
    entrypoint: [""]