top of page
  • Writer's pictureMarie Cruz

Using Docker to run your Cypress tests

Containers in, Virtual Machines out.

As a Test Automation Engineer, nowadays you are also expected to contribute in integrating your tests into a build pipeline. As we fully embrace DevOps, Docker has been one of the most popular and most used tool for so many years. When you integrate your tests to a build pipeline, most likely you would have encountered using Docker images or creating a Dockerfile. In this blog post, we’ll look at how we can use Docker to run our Cypress tests. This tutorial assumes that you have a fair understanding of Docker already. But if not, I'll go over some basics. 🙂

Docker Basics

I am not a Docker expert by any chance! I only know a fair amount to help me with my automated tests. Let's go over some of the basic terminologies to get started.

Dockerfile - a file that creates a Docker image. Basically, think of it as a set of instructions that you devise to create a Docker image. It contains a set of commands that Docker runs. Like with any instructions, a Dockerfile is executed in order.

Docker Image - a thing that gets built from your Dockerfile. Basically, it's the end product of your Dockerfile. A docker image can be an existing image (made by other people) or a new image (one that you create). For this tutorial, we will be using the Cypress Docker image.

Docker Container - a running instance of your Docker Image. In Object Oriented terms, think of Docker image as a class and a Docker container as an instance of that class.


This tutorial assumes you have Docker installed already. If not, please install it from here.

Cypress Docker Image

The first step is to determine which Cypress Docker image you need to use. Cypress has three categories of images such as:

  • cypress/base - image including all Operating System dependencies.

  • cypress/browsers - image including all Operating System dependencies and a pre-installed browser (Chrome or Firefox).

  • cypress/included - image including all Operating System dependencies as well as the Cypress package.

For this tutorial, I'll be using cypress/included but feel free to use the other images.

Creating our Dockerfile

On the root of your project, create a file called `Dockerfile`. You can also rename this to whatever you want as long as it has the `.dockerfile` extension.

Let's walk through the different commands here. First, we are getting the Cypress Docker image from `cypress/included:4.1.0`. We are then specifying that the work directory of our Docker container is called app and then copying the files and folder that we need such as the cypress folder and cypress.json file from our source to the Docker container. Finally, we run the command to run our Cypress tests.

To build the container, simply run with the following command:

docker build -t cypress-test-image:1.0.0 .

The parameter `-t` specifies the name of your Docker image. In this example, my image name is cypress-test-image and has the tag version 1.0.0. If you specified a different filename for your Dockerfile, you would also need to pass the name of your file using the parameter `-f`.

docker build -t cypress-test-image:1.0.0 -f cypress-test.dockerfile .

The dot at the end specifies the PATH where Docker should copy the files from. Since I am on the root directory of my project, it will copy the files it need from this location.

When you build the image, you should see an output similar to the following with your Cypress tests running as well.

To re-run your tests without building the Docker image, simply run:

docker run -t cypress-test-image:1.0.0 .

If you want to use the other Cypress Docker images (base or browsers), you would need to update your Dockerfile to also copy package.json and install the project dependencies so Cypress can be installed.

Real work scenarios where Docker can help

I've noticed that in our builds, we are seeing this issue frequently which could be related to an issue with the Electron browser. One of the suggested comments is to run the tests headlessly on Chrome instead of Electron. To try it, I updated the Cypress Docker image that we are using to this one here depending on which browser version, node version, OS etc we want. The setup is still pretty much similar, the only changes that I've done is to change the Cypress image on our Dockerfile and also updated the test command that we used to run it headlessly on Chrome.

To run your Cypress tests headlessly, you just need to pass the following parameters. For example:

npx cypress run --headless --browser chrome

Another scenario where Docker has helped us is with visual testing. As we are currently doing visual tests to support one team that we are working with, we are experiencing an issue where the baseline and test images always have a lot of mismatch. This is because we generate the baseline images on our local machine whereas the test images are generated on our CircleCI pipeline which is running on a different machine. By using the Cypress Docker image to generate the baseline images, we have seen less mismatch errors on our visual tests since the tests are run on the same Operating System, node version etc.

Additional Resources

25,161 views10 comments

10 comentários

Membro desconhecido
19 de fev. de 2022

How to run custom commands in my package.json file via "docker run ..." ???


Robert Caldecott
Robert Caldecott
14 de dez. de 2021

Today I am getting started with Cypress and have already made use of two of youre blog posts Marie! This one and the coverage article. Thank you so much!

Marie Cruz
Marie Cruz
14 de dez. de 2021
Respondendo a

Thank you so much! I’m glad it’s been helping 😊


Павло Щирба
Павло Щирба
22 de set. de 2021

Very cool article. Thank you very much. It was really helpful.




Berneau van der Merwe
Berneau van der Merwe
23 de ago. de 2021

Hi, Great tutorial, I have been very adventurous with docker and cypress where I am trying to automate a full stack application running e2e test with cypress. It runs locally and the cypress UI shows me everything runs well using the same data in a docker-like setup using docker compose I get errors in cypress I don't get when running it locally especially with the local storage of the browser when trying to check session info. Not sure if this is headless vs headed issue but regardless the data is null. Any thoughts?


08 de jun. de 2021

Hi Marie, can you speak more about how you used the docker image locally to record baseline images and what plugin you were using for the images? I have found it a bit of a pain to develop tests using the docker image and specifying individual tests for base images.

Marie Cruz
Marie Cruz
15 de jun. de 2021
Respondendo a

Hi Gareth,

This was on a previous project but essentially, what I did was I created a dockerfile similar to above and then I use docker-compose to run the service.

Here is a quick code walk through:

visual-e2e-desktop: image: visual-e2e-desktop ipc: host build: context: . dockerfile: e2e-visual-tests.dockerfile working_dir: / command: npm run cy:visual:dev:snapshots volumes: - ./cypress/snapshots:/cypress/snapshots

Essentially, from this service, I am using the dockerfile that I created to build cypress and its dependencies. I was using the plugin cypress-image-snapshot for this. The volume folder need to be specified as this is where the images will be generated. Then to generate the images, we ran the command `docker-compose up visual-e2e-desktop`

bottom of page