tnicola/cypress-parallel

Reduce up to 40% your Cypress suite execution time parallelizing the test run on the same machine.

Summary

cypress-parallel is a JavaScript CLI that runs a Cypress test suite across multiple threads on a single machine. It discovers spec files, optionally balances them using a weights file, and then runs the user's existing Cypress command in parallel processes before merging the output into a single report. The project is MIT-licensed and targeted at engineers who want faster local Cypress feedback without setting up a remote dashboard.

What it is useful for

The tool is useful when a single cypress run invocation is too slow on a developer laptop or inside a single CI container. It splits spec files across a configurable number of threads (set with -t), each running its own Cypress process, then waits for all of them to finish before exiting. A weights file can be supplied with -w so heavier spec files can be distributed more evenly, and a spec can read its own thread index from the CYPRESS_THREAD environment variable. It also supports custom reporters and reporter options, which fits monorepos already using cypress-multi-reporters.

How engineers can use it

The README documents a straightforward setup. Install as a dev dependency with npm i cypress-parallel -D or yarn add cypress-parallel -D, then add scripts in package.json that wrap an existing Cypress command:

"cy:run": "cypress run",
"cy:parallel": "cypress-parallel -s cy:run -t 2 -d 'cypress/integration' -a '\"--config baseUrl=http://localhost:3000\"'"

Run it with npm run cy:parallel, or invoke without installing using npx cy:parallel -s cy:run -t 2 -d 'cypress/integration' -a '...'. Specific specs can be passed after --spec instead of a directory, and reporter behavior can be tuned with -r, -o, and -n. The wrapper exposes --bail to exit on the first failing thread and --verbose for additional logging.

Documented caveats to be aware of: if your project uses cypress-cucumber-preprocessor, set -m false to disable strict mode, and in monorepos where cypress-multi-reporters lives outside the suite directory, pass -n with its module path so Cypress can resolve it. The README also notes that the project is looking for contributors, and the setup is documented only for npm/yarn scripts and npx — anything beyond what the README covers should be verified against the source.