included

cypress/included

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

Name + Tag	Base image
cypress/included:3.2.0	cypress/base:12.1.0
cypress/included:3.3.0	cypress/base:12.1.0
cypress/included:3.3.1	cypress/base:12.1.0
cypress/included:3.3.2	cypress/base:12.1.0
cypress/included:3.4.0	cypress/browsers:node12.6.0-chrome75
cypress/included:3.4.1	cypress/browsers:node12.6.0-chrome75
cypress/included:3.5.0	cypress/browsers:node12.6.0-chrome77
cypress/included:3.6.0	cypress/browsers:node12.6.0-chrome77
cypress/included:3.6.1	cypress/browsers:node12.6.0-chrome77
cypress/included:3.7.0	cypress/browsers:node12.6.0-chrome77
cypress/included:3.8.0	cypress/browsers:node12.6.0-chrome77
cypress/included:3.8.2	cypress/browsers:node12.6.0-chrome77
cypress/included:3.8.3	cypress/browsers:node12.6.0-chrome77
cypress/included:4.0.0	cypress/browsers:node13.6.0-chrome-80-ff72
cypress/included:4.0.1	cypress/browsers:node13.6.0-chrome-80-ff72
cypress/included:4.0.2	cypress/browsers:node13.6.0-chrome-80-ff72
cypress/included:4.1.0	cypress/browsers:node12.16.1-chrome-80-ff73
cypress/included:4.2.0	cypress/browsers:node12.13.0-chrome80-ff74
cypress/included:4.3.0	cypress/browsers:node12.13.0-chrome80-ff74
cypress/included:4.4.0	cypress/browsers:node12.13.0-chrome80-ff74
cypress/included:4.4.1	cypress/browsers:node12.13.0-chrome80-ff74
cypress/included:4.5.0	cypress/browsers:node12.13.0-chrome80-ff74
cypress/included:4.6.0	cypress/browsers:node12.16.2-chrome81-ff75
cypress/included:4.7.0	cypress/browsers:node12.16.2-chrome81-ff75
cypress/included:4.8.0	cypress/browsers:node12.16.2-chrome81-ff75
cypress/included:4.9.0	cypress/browsers:node12.16.2-chrome81-ff75
cypress/included:4.10.0	cypress/browsers:node12.14.1-chrome83-ff77
cypress/included:4.11.0	cypress/browsers:node12.14.1-chrome83-ff77
cypress/included:4.12.0	cypress/browsers:node12.18.0-chrome83-ff77
cypress/included:4.12.1	cypress/browsers:node12.18.0-chrome83-ff77
cypress/included:5.0.0	cypress/browsers:node12.18.0-chrome83-ff77
cypress/included:5.1.0	cypress/browsers:node12.18.0-chrome83-ff77
cypress/included:5.2.0	cypress/browsers:node12.18.0-chrome83-ff77
cypress/included:5.3.0	cypress/browsers:node12.14.1-chrome85-ff81
cypress/included:5.4.0	cypress/browsers:node12.14.1-chrome85-ff81
cypress/included:5.5.0	cypress/browsers:node12.14.1-chrome85-ff81
cypress/included:5.6.0	cypress/browsers:node12.14.1-chrome85-ff81
cypress/included:6.0.0	cypress/browsers:node12.18.3-chrome83-ff77
cypress/included:6.0.1	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.1.0	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.2.0	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.2.1	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.3.0	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.4.0	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.5.0	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.6.0	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.7.0	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.7.1	cypress/browsers:node12.18.3-chrome87-ff82
cypress/included:6.8.0	cypress/browsers:node12.18.3-chrome89-ff86
cypress/included:7.0.0	cypress/browsers:node12.18.3-chrome89-ff86
cypress/included:7.0.1	cypress/browsers:node14.16.0-chrome89-ff77
cypress/included:7.1.0	cypress/browsers:node14.16.0-chrome89-ff77
cypress/included:7.2.0	cypress/browsers:node14.16.0-chrome89-ff77
cypress/included:7.3.0	cypress/browsers:node14.16.0-chrome89-ff77
cypress/included:7.4.0	cypress/browsers:node14.16.0-chrome89-ff77
cypress/included:7.5.0	cypress/browsers:node14.16.0-chrome89-ff86
cypress/included:7.6.0	cypress/browsers:node14.16.0-chrome89-ff86
cypress/included:7.7.0	cypress/browsers:node14.16.0-chrome89-ff86

This image should be enough to run Cypress tests headlessly or in the interactive mode with a single Docker command like this:

$ docker run -it -v $PWD:/e2e -w /e2e cypress/included:7.3.0

Debug

If you want to see the Cypress debug logs during the run, pass environment variable DEBUG:

$ docker run -it -v $PWD:/e2e -w /e2e -e DEBUG=cypress:* cypress/included:3.8.1
  cypress:cli:cli cli starts with arguments ["/usr/local/bin/node","/usr/local/bin/cypress","run"] +0ms
  cypress:cli NODE_OPTIONS is not set +0ms
  cypress:cli:cli program parsing arguments +3ms
  ...

Arguments

These images have its entry point set to cypress run without any additional arguments. You can specify additional Cypress CLI arguments after the image name. For example to print the Help menu for the cypress run command:

$ docker run -it --entrypoint=cypress cypress/included:7.7.0 --help

To run a single spec using Chrome browser:

$ docker run -it --entrypoint=cypress cypress/included:7.7.0 --spec cypress/integration/spec-a.js --browser chrome

Entry

These images have its entry point set to cypress run. If you want to run a different command, you need to set --entrypoint=cypress and specify arguments AFTER the image name. For example, to print the Cypress information using cypress info command

$ docker run -it --entrypoint=cypress cypress/included:4.2.0 info
Displaying Cypress info...

Detected 2 browsers installed:

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

2. Firefox
  - Name: firefox
  - Channel: stable
  - Version: 74.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

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

Cypress Version: 4.2.0
System Platform: linux (Debian - 10.1)
System Memory: 2.09 GB free 285 MB

Entry with arguments

If you want to provide Cypress command line arguments, specify the entry point and the arguments. For example to run tests with recording and parallel mode using custom build ID "abc123" we can use:

$ docker run -it --entrypoint=cypress cypress/included:7.5.0 \
  run --record --parallel --ci-build-id abc123

Keep the container

Every time you run docker run you spawn a new container. That container then stops after the tests finish, but there is nothing Cypress can do about it - it is the Docker command docker run ... that controls this behavior.

If you are running a lot of tests again and again, you might start the container once using Bash as the entrypoint, instead of the default cypress command. Then you can execute the cypress run or any other commands, while still in the same container:

$ docker run -it -v $PWD:/e2e -w /e2e \
  --entrypoint=/bin/bash cypress/included:7.3.0
# we are inside the container
# let's run the tests
root@814ed01841fe:/e2e# cypress run
....
# run the tests again
root@814ed01841fe:/e2e# cypress run

Browser

If you want to use a different browser (assuming it is installed in the container) use:

$ docker run -it -v $PWD:/e2e -w /e2e --entrypoint=cypress cypress/included:3.8.1 run --browser chrome

============================================================

  (Run Starting)

  ┌─────────────────────────────────
  │ Cypress:    3.8.1
  │ Browser:    Chrome 77
  │ Specs:      1 found (spec.js)
  └─────────────────────────────────
...

For more information, read Run Cypress with a single Docker command and End-to-End Testing Web Apps: The Painless Way

Default user

By default, the included images run as root user. You can switch the user to the second user in the image node or custom-mapped user, see examples section. Starting with cypress/included:3.8.1 we set permissions on the globally installed Cypress and set binary cache variable to allow other users read and execute access. Thus you will be able to run Cypress as non-root user by using -u node

$ docker run -it -v $PWD/src:/test -w /test -u node cypress/included:3.8.1

Building and testing

To build a new image use command from the root of the repo

$ npm run add:included -- <Cypress version> <cypress/base:image>
# example
$ npm run add:included -- 4.0.2 cypress/browsers:node13.6.0-chrome80-ff72

You should also update the circle.yml file after creating the new image with

$ npm run build

You can test the new image by creating a new project and running headless tests. For example:

cd /tmp
mkdir test
cd test
npm init --yes
npm i -D cypress
npx @bahmutov/cly init
rm -rf package-lock.json package.json node_modules
docker run -it -v $PWD:/e2e -w /e2e cypress/included:3.3.2

Tip: the above commands are in the file test.sh

The tests should finish successfully using local image. Now push the image to the Docker hub

docker push cypress/included:3.3.2

GitHub Action

You can quickly run your tests in GitHub Actions using these images, see cypress-gh-action-included repository.

GitLab CI

You can use the included images to run Cypress tests on GitLab CI, see how in cypress-example-included repository.

Wait-on

If you want to run Cypress after a server has started, we suggest using wait-on utility. To use it from the cypress/included image, you need to disable the default entrypoint and set a new command like this:

# execute the Cypress container once
docker run --rm \ # remove container after finish
  -v ./e2e:/e2e \ # map current folder to "e2e" folder
  --workdir=/e2e \
  --entrypoint="" \ # remove default entrypoint command
  cypress/included:4.11.0 \
  # wait for the local site to respond
  # then run Cypress tests
  /bin/bash -c 'npx wait-on http://127.0.0.1:3000 && cypress run'

Restrict CPU

If you want to simulate slow container, run the Docker container with --cpus parameter, for example, let's debug the browser detection problems when the CPU is (very) slow:

docker run -it -v $PWD:/e2e -w /e2e --cpus=0.02 \
  -e DEBUG=cypress:launcher --entrypoint=cypress \
  cypress/included:7.2.0 info