Cypress parallelization with the Orchestrator — part 2 — ShowCase

Islam Taha
4 min readMay 25, 2021
Orchestrator orchestrats the cypres specs for you

Hello🤗 Hello, Here is 0xIslamTaha from Relayr Product Design, and today I would like to show you a showcase of using the orchestrator to execute your cypress specs in parallel for free and without going through the cypress dashboard.

First of all, here is the showcase repo 💪, You can clone it and play with it.


In this journey, I will guide you step-by-step to setup your test cases to be ready to go with the orchestrator. We will use the official cypress/integration/examples specs as default test cases. Our target is executing those specs in parallel in chrome and firefox.

The Setup:

  • 1- Install the requirements
  • 2- Edit cypress.config
  • 3- Write a very basic Cypress Dockerfile
  • 4- Create docker-compose.yml file
  • 5- Configure the orchestrator.json
  • 6- Execute the test cases

1- Install the requirements:

By executing the following script, you will clone the showcase repo and you will execute the requirements packages.

here is the list of the installed packages:

"@0xislamtaha/orchestrator": "^2.0.0"
"cypress": "^9.2.0"
"mocha": "^8.4.0"
"mochawesome": "^6.2.2"
"mochawesome-merge": "^4.2.0

2- Edit cypress.json:

Cypress.json is the main configuration file for cypress, what is important for us is the reporting configuration. The orchestrator is depending on the mochawsome json reports to generate the HTML report, so we need to add the following configuration to your cypress.json file.

Here, we are configuring the “mochawsome” as the reporter and we configured the report dir.

3- Write a very basic Cypress Dockerfile:

The orchestrator executes the specs inside docker containers so, we need to setup a very basic Dockerfile to use to establish the containers.

As you can see, I set the WORKDIR and COPY the configuration files to the image and then I RUN npm ci to install the minimum requirements.

4- Create docker-compose.yml file

The orchestrator uses it to run multiple containers. Based on the docker-compose file, The orchestrator can execute the specs against a public URL (localhost, …) or it could execute it against another container (in case of your application is working inside a container. In this showcase, I need to execute the cypress official specs against a public IP so, I will create the docker-compose to meet these needs. It will only have the cypress services with a bridge network.

As you can see, It has one service and it builds from the previous Dockerfile. It uses the bridge network to allow the containers to access the internet from the host machine. It shared the cypressdir and the mochawsome-reportdir between the host and the container. It shared the dev/shm to overwrite the minimum memory configuration.

5- Configure the orchestrator.json

We need to configure the orchestrator to meet our goal.

Let’s describe what’s going on in this configuration:

  • parallelizm: 1 means we need to execute the test cases on 1 container per browser. If u edit it to be 2, then you will split the cypress specs across two containers per browser.
  • browsers: ["chrome", "firefox"] means we will execute the specs in chrome and in firefox in parallel.
  • timeout: 30m We set 30m as the maximum timeout for the whole process.
  • enviornmnet: {} We don't need to export any environment variables to the containers.
  • preCommands: [...] A list of the bash commands to be executed before running the containers.
  • dockerComposePath A relative path to the docker-compose.yml file
  • cypressContainerName: The cypress service name in the docker-compose.yml file.
  • specsHomePath A relative path to the cypress specs files in the host machine.
  • specsDockerPath A relative path to the cypress specs files in the containers. As we already shared ./cypress dir between the host and the containers, then the specsHomePath and the specsDockerPath should be matched.
  • mochawsomeJSONPath A relative path to the mochawseom dir in the host machine. It should be equal to the value of reportOptions.reportDir in the cypress.json file.
  • reportPath: A relative path to save the generated HTML report dir in the host machine. We already shared ./mochawsome-report dir between the host and the containers in the docker-compose.yml file.
  • specs: [..] A list of specific specs to be executed. Leave it empty to execute all the test cases or edit it to be ["files.spec.js"] to execute file test cases only.

If you are still with me, then VOLLA we did it and now let the orchestrator do its magic.

6- Execute the test cases

To run the orchestrator with the previous configuration, execute the following command.

npx orchestrator --config orchestrator.json

Drink your coffee and watch the logs.

At the end of the execution, The orchestrator will log the execution time and you can check the HTML report by browsing the mochawesome-report/mochawesome.html file. You should get something like the following photo.

mochawsome-html report

The last tip😜 I would add for today is, You can overwrite any of the orchestrator configurations on the fly without editing the orchestrator.json file.

That’s it for today, wanna be in touch? You could find me here