cypress-parallel

0.15.0 verified Sat Apr 25 auth: no javascript

A CLI tool that runs Cypress test specs in parallel on the same machine, reducing execution time by up to 40%. It shards spec files across a configurable number of threads, each running a Cypress command. Version 0.15.0 is current; releases are occasional with bug fixes and dependency updates. Differentiators: no external CI service required, supports weight files for balanced sharding, mono-repo support via reporterModulePath, and strict mode for validation. Peer dependency on cypress-multi-reporters (^2.0.5). Active maintenance with recent dependency security bumps.

Common errors

error Error: Cannot find module 'cypress-multi-reporters' ↓

cause cypress-multi-reporters is not installed or not accessible in the working directory.

fix

Install cypress-multi-reporters: npm i cypress-multi-reporters

error cypress-parallel: command not found ↓

cause cypress-parallel is not installed or npx is used incorrectly.

fix

Use npx cypress-parallel or install globally: npm i -g cypress-parallel

error Error: The script name 'cypress run' is not a valid npm script. ↓

cause Passing cypress command directly to -s instead of an npm script name.

fix

Define a script in package.json, e.g., "cy:run": "cypress run" and use -s cy:run

error Error: The number of threads (t) cannot be greater than the number of spec files found. ↓

cause More threads than spec files; v0.12.0+ throws this error.

fix

Reduce -t to at most the number of spec files.

Warnings

deprecated The 'colors' dependency was replaced with '@colors/colors' in v0.13.0 due to a security incident (CVE-2022-24785). ↓

fix Update to v0.13.0 or later.

gotcha Using --strictMode (-m) with cypress-cucumber-preprocessor can cause errors. Disable strict mode if you use that preprocessor. ↓

fix Add -m false to the cypress-parallel command.

gotcha The --script (-s) option must be the name of an npm script (e.g., 'cy:run'), not a raw cypress command. Common mistake leads to 'command not found'. ↓

fix Define the cypress command in package.json scripts and pass that script name.

gotcha If using cypress-multi-reporters from a monorepo, the module may not be found. Use --reporterModulePath (-n) to specify the path. ↓

fix Add -n path/to/node_modules/cypress-multi-reporters

gotcha The number of threads (-t) should not exceed the number of spec files found. v0.12.0 added a check, but earlier versions may spin up unnecessary threads. ↓

fix Update to v0.12.0 or ensure -t <= spec count.

Install

npm install cypress-parallel

yarn add cypress-parallel

pnpm add cypress-parallel

Imports

cli usage
wrong
```
npx cypress-parallel -s cypress run -t 2
```
correct
```
npx cypress-parallel -s cy:run -t 2 -d cypress/e2e
```
The -s flag expects an npm script name, not a cypress command. Define a script in package.json first.
install
wrong
```
npm install cypress-parallel --save-dev
```
correct
```
npm i cypress-parallel
```
Can be devDependency, but --save-dev is optional.

version

wrong

import { version } from 'cypress-parallel'

correct

const version = require('cypress-parallel/package.json').version

Package has no main export; primarily used as a CLI tool. Importing directly may not work.

Quickstart

Install and run cypress-parallel with 2 threads, splitting specs from the cypress/e2e directory.

// In package.json:
// "scripts": {
//   "cy:run": "cypress run",
//   "cy:parallel": "cypress-parallel -s cy:run -t 2 -d cypress/e2e"
// }
// Then run:
// npm run cy:parallel

// Alternative one-liner with npx:
// npx cypress-parallel -s cy:run -t 2 -d cypress/e2e