cypress-concurrently

Run Cypress specs in parallel using multiple worker processes.

Project goals

cypress-concurrently is designed to reduce end-to-end feedback time by running specs concurrently while keeping the CLI simple for local and CI usage with sensible defaults. It also aims to provide clear execution visibility across discovery, thread activity, and final summaries, and to stay compatible with common Cypress project layouts and configurations.

Requirements

• Node.js >=18
• Cypress >=13 <16

Install

npm install cypress cypress-concurrently

Quick start

1. Install dependencies:

npm install cypress cypress-concurrently

2. Run all specs in your Cypress e2e folder with 3 workers:

npx cypress-concurrently threads=3 testPath="./cypress/e2e"

3. Optionally filter specs with a pattern:

npx cypress-concurrently threads=3 testPath="./cypress/e2e" spec="**/smoke*.cy.ts"

4. In CI, tune startup pressure if needed:

npx cypress-concurrently threads=4 delay=3 testPath="./cypress/e2e"

CLI options

• threads=<number>: parallel workers (1-20). If omitted, auto-detected (max 4).
• testPath="<path>": test directory or file.
• spec="<pattern>": spec glob filter.
• config="<path>": Cypress config file path.
• browser="<name>": browser (default: electron).
• headless=<boolean>: run headless (default: true).
• delay=<seconds>: delay between worker starts (default: 2).

Spec pattern priority

1. CLI spec=...
2. Cypress config e2e.specPattern
3. Fallback **/*.{spec,test}.{js,ts,jsx,tsx}

Programmatic usage

import { CypressConcurrently } from "cypress-concurrently"

const results = await CypressConcurrently.run({
  testPath: "./cypress/e2e",
  threads: 3,
})

Example output

🚀 Cypress Concurrently
Starting concurrent test execution...

Test Discovery Phase

Configuration:
   Test Path: ./cypress/e2e
   Threads: 2
   Delay: 2s
   Browser: electron
   Headless: true

Execution Phase

Execution Plan:
   Total specs: 2
   Max threads: 2
   Startup delay: 2s between threads
   Browser: electron
   Headless: true
   Platform: win32

[Thread 1] Starting: cypress/e2e/smoke.cy.js
[Thread 2] Starting: cypress/e2e/smoke-second.cy.js
✅ [Thread 1] Completed: cypress/e2e/smoke.cy.js (28796ms)
Progress [1/2] ✅ 1 ❌ 0
✅ [Thread 2] Completed: cypress/e2e/smoke-second.cy.js (26797ms)
Progress [2/2] ✅ 2 ❌ 0

------------------------------------------------------------------------
Run Finished
------------------------------------------------------------------------

Spec Files:
  Spec                         Result  Passing  Failing  Pending  Duration
  -------------------------------------------------------------------------
  smoke.cy.js                  PASS    6        0        0        0m 28s
  smoke-second.cy.js           PASS    5        0        0        0m 26s

Results:
  ✅ 11 passing
  ❌ 0 failing
  ⏸ 0 pending
  2 spec files
  Finished in 0m 28s
  Threads: 2
  Platform: win32

------------------------------------------------------------------------
✅ All tests passed.

License

MIT