This post walks through configuring your existing Cypress tests to execute in a multi-threaded parallel run using the cypress-parallel package.

For these steps I will be referencing this example Cypress repo which runs tests from 3 files. The build on a normal single threaded run is ~10.5 seconds.

Note for a larger number of threads you will need a much higher spec machine. Refer here for the general Cypress minimum requirements.

Due to the above limitation using this solution is more suitable as a quick win for smaller Cypress frameworks. If you have a larger test suite you should also consider the following options:

• Running tests on multiple machines linked to Cypress Cloud
• Run the tests on multiple machines using cypress-split plugin
• Run the tests in parallel on Browserstack remote machines

TL;DR

See this repo for an example solution using the cypress-parallel package.

Install cypress-parallel Package

Within your existing Cypress project run the following command to install the new package.

npm i -D cypress-parallel

Install cypress-multi-reporters Package

Now install this package which is required for creating a report for each thread.

npm i -D cypress-multi-reporters

Amend your NPM Scripts

Create a new NPM script in package.json called something akin to test:parallel or cy:parallel.

This needs to call the cypress-parallel package with a -s switch containing your existing Cypress NPM script to run which will now be ran in parallel.

Use the -t switch to set the number of threads you desire. Each thread will run a single test file at a time.

Under the -d switch you need to pass a glob pattern to find all your Cypress test files E.G. for standard E2E tests cypress/e2e/**/*.cy.js will work.

  "scripts": {
    "test": "cypress run",
    "test:parallel": "cypress-parallel -s test -t 3 -d cypress/e2e/**/*.cy.js"
  }

Test the Script

Run npm run test:parallel to execute your tests in parallel. Example output below shows my 3 example files running on 3 threads takes about ~3.5 seconds from ~10.5 seconds.

┌──────────────────────────────────────────────────┬────────┬───────┬─────────┬─────────┬─────────┐
│ Spec                                             │ Time   │ Tests │ Passing │ Failing │ Pending │
├──────────────────────────────────────────────────┼────────┼───────┼─────────┼─────────┼─────────┤
│ cypress/e2e/about.cy.js                          │ 2s     │ 1     │ 1       │ 0       │ 0       │
├──────────────────────────────────────────────────┼────────┼───────┼─────────┼─────────┼─────────┤
│ cypress/e2e/homepage.cy.js                       │ 1s     │ 1     │ 1       │ 0       │ 0       │
├──────────────────────────────────────────────────┼────────┼───────┼─────────┼─────────┼─────────┤
│ cypress/e2e/post.cy.js                           │ 2s     │ 1     │ 1       │ 0       │ 0       │
├──────────────────────────────────────────────────┼────────┼───────┼─────────┼─────────┼─────────┤
│ Results                                          │ 4s     │ 3     │ 3       │ 0       │ 0       │
└──────────────────────────────────────────────────┴────────┴───────┴─────────┴─────────┴─────────┘
Total run time: 3.425s, executed in: 10.472, saved -7.047 (~-206%)
Weights file generated.

You'll notice a file called multi-reporter-config.json has been created. Be sure to include this in your commits as this will help the later test builds run in the most efficient way.

A directory called runner_results/ will have also been created to contain the results for each thread. This can be included in your .gitignore file.

For more information on this package see the official readme.

The code used for this post can be found here.