⚡ cypress-parallel-runner

Run multiple Cypress spec files in parallel locally — no Cypress Cloud needed. Free forever.

Install

npm install cypress-parallel-runner --save-dev

Required Setup in Your Cypress Project

1. cypress/plugins/index.js

Add a null check in before:browser:launch to prevent crashes when running with Electron:

on('before:browser:launch', (browser = {}, options) => {
  if (browser.family === 'chromium' && options.preferences && options.preferences.default) {
    options.preferences.default['download'] = { default_directory: config['downloadsFolder'].replace(/\\/g, "\\\\") }
    return options
  }
});

2. cypress.config.js

Make sure reporterOptions has reporterEnabled inside the object:

reporter: "mocha-multi-reporters",
reporterOptions: {
  reporterEnabled: "spec",
  configFile: "cypress/config.json",
},

3. cypress/config.json

Create this file if it doesn't exist. Run this in PowerShell:

[System.IO.File]::WriteAllText("$PWD\cypress\config.json", '{"reporterEnabled": "spec"}')

Usage

As a CLI command

# Run specific specs in parallel
npx cypress-parallel --spec login,checkout,contacts

# Run an entire folder
npx cypress-parallel --spec cypress/e2e/leases

# Run with Chrome
npx cypress-parallel --spec login,checkout --browser chrome

# Run with Edge
npx cypress-parallel --spec login,checkout --browser edge

# Limit parallel workers
npx cypress-parallel --spec login,checkout,contacts --workers 2

# Pass env variables
npx cypress-parallel --spec login --env ENV=staging

As a package.json script

{
  "scripts": {
    "parallel": "cypress-parallel --spec login,checkout,contacts",
    "parallel:chrome": "cypress-parallel --spec login,checkout --browser chrome",
    "parallel:staging": "cypress-parallel --spec login --env ENV=staging"
  }
}

Then run:

npm run parallel
npm run parallel:chrome

Options

| Option | Description | Default | |---|---|---| | --spec | Comma-separated spec names, paths, or folder names | all specs | | --browser | Browser: electron, chrome, edge, firefox | electron | | --workers | Max parallel specs at once | all at once | | --config-file | Path to Cypress config file | cypress.config.js | | --env | Cypress env variables | none | | --specs-dir | Directory to search for specs | cypress/e2e | | --help | Show help | |

How it works

• Discovers spec files from your cypress/e2e folder
• Launches each spec simultaneously using cypress run --headed --no-exit
• Each spec runs in its own browser window
• Uses your existing cypress.config.js, fixtures, custom commands, and localStorage setup
• --no-exit keeps the browser open after the test so you can inspect results

Requirements

• Node.js >= 14
• Cypress >= 10 installed in your project

License

MIT