A 200-test Cypress suite takes 15-20 minutes to run sequentially on a single CI machine. With Cypress Cloud parallelisation, you split those tests across 4 machines and finish in 4-5 minutes. Cypress Cloud’s load balancing is intelligent — it distributes tests based on historical execution time, not just count, so fast and slow tests are spread evenly. This lesson covers how parallelisation works, how to configure it, and the cost-benefit analysis.
Cypress Cloud Parallelisation — How It Works
Cypress Cloud acts as a coordinator: multiple CI containers connect to it, and it distributes individual spec files to available machines, collecting results centrally.
// ── How Cypress Cloud parallelisation works ──
/*
WITHOUT parallelisation (1 machine):
Machine 1: spec1.cy.ts → spec2.cy.ts → ... → spec50.cy.ts
Total: 20 minutes
WITH parallelisation (4 machines):
Machine 1: spec1, spec5, spec9, ... → 5 min
Machine 2: spec2, spec6, spec10, ... → 5 min
Machine 3: spec3, spec7, spec11, ... → 5 min
Machine 4: spec4, spec8, spec12, ... → 5 min
Total: 5 minutes (4x speedup)
Cypress Cloud's load balancer considers HISTORICAL spec duration:
- A 3-minute spec and a 30-second spec are not treated equally
- Longer specs are assigned first to prevent one machine finishing late
- Result: more even distribution than simple round-robin
*/
// ── Setting up parallelisation ──
// Step 1: Create a Cypress Cloud project at https://cloud.cypress.io
// You receive a projectId and a record key
// Step 2: Add projectId to cypress.config.ts
/*
export default defineConfig({
projectId: 'abc123', // Your Cypress Cloud project ID
e2e: { ... },
});
*/
// Step 3: Run with --record and --parallel flags
// npx cypress run --record --key YOUR_RECORD_KEY --parallel
// Step 4: In CI, spin up multiple containers running the same command
const GITHUB_ACTIONS_PARALLEL = `
# .github/workflows/cypress-parallel.yml
name: Cypress Parallel
on: [push, pull_request]
jobs:
cypress-run:
runs-on: ubuntu-22.04
strategy:
fail-fast: false
matrix:
containers: [1, 2, 3, 4] # 4 parallel containers
steps:
- uses: actions/checkout@v4
- name: Cypress run
uses: cypress-io/github-action@v6
with:
record: true
parallel: true
group: 'e2e-tests'
browser: chrome
env:
CYPRESS_RECORD_KEY: \${{ secrets.CYPRESS_RECORD_KEY }}
`;
// ── Cost-benefit analysis ──
const COST_BENEFIT = {
'1 container (no parallel)': {
time: '20 minutes',
ci_cost: '20 compute-minutes',
cypress_cloud: 'Not needed',
},
'4 containers (parallel)': {
time: '5 minutes',
ci_cost: '20 compute-minutes (same total, split across 4)',
cypress_cloud: 'Required (free tier: 500 recordings/month)',
},
'8 containers (parallel)': {
time: '~3 minutes',
ci_cost: '24 compute-minutes (slight overhead)',
cypress_cloud: 'Required (may need paid tier for high-volume teams)',
},
};
// ── Alternatives to Cypress Cloud for parallelisation ──
const ALTERNATIVES = [
{
tool: 'Manual spec splitting (free)',
how: 'Split spec files across CI jobs manually: job1 runs specs A-M, job2 runs N-Z',
pros: 'Free; no external service dependency',
cons: 'No intelligent load balancing; manual maintenance; uneven distribution',
},
{
tool: 'sorry-cypress (open-source)',
how: 'Self-hosted alternative to Cypress Cloud with parallelisation and dashboard',
pros: 'Free; self-hosted; API compatible with Cypress Cloud',
cons: 'Requires hosting infrastructure; community-maintained',
},
{
tool: 'currents.dev (third-party)',
how: 'Drop-in Cypress Cloud alternative with additional features',
pros: 'Lower cost; additional analytics; API compatible',
cons: 'Third-party dependency; separate billing',
},
];
console.log('Parallelisation Options:');
ALTERNATIVES.forEach(a => {
console.log(`\n ${a.tool}`);
console.log(` How: ${a.how}`);
console.log(` Pros: ${a.pros}`);
console.log(` Cons: ${a.cons}`);
});
Note: Cypress Cloud parallelisation requires the
--record flag, which sends test results and metadata to Cypress Cloud servers. This means your test results, screenshots, and videos are stored on Cypress Cloud’s infrastructure. For organisations with strict data privacy requirements, self-hosted alternatives like sorry-cypress provide the same parallelisation and dashboard features without sending data to a third-party service. Evaluate your organisation’s data policies before choosing between Cypress Cloud and self-hosted alternatives.Tip: Start with 4 parallel containers and measure the improvement. If your 20-minute suite drops to 5 minutes, the ROI is clear. Increase to 8 containers only if the 5-minute runtime is still too slow for your feedback requirements. Beyond 8 containers, diminishing returns set in because the overhead of starting containers, downloading the Cypress binary, and coordinating test distribution reduces the effective speedup. Most teams find their optimal parallelisation factor between 4 and 8.
Warning: Parallel tests must be independent — no shared database state, no shared user accounts, no test ordering dependencies. If Test A creates a user and Test B expects that user to exist, they cannot run on different machines. This is the same independence requirement as Selenium parallel execution (Chapter 41). Fix test dependencies before enabling parallelisation, or you will see random failures that only occur in parallel runs.
Common Mistakes
Mistake 1 — Not setting fail-fast: false in the CI matrix
❌ Wrong: fail-fast: true — if container 1 fails, containers 2-4 are cancelled before they finish, losing results for 75% of the test suite.
✅ Correct: fail-fast: false — all containers run to completion regardless of individual failures, providing a complete picture.
Mistake 2 — Using too many parallel containers for a small test suite
❌ Wrong: 20 parallel containers for a 30-test suite — each container gets 1-2 tests, and the overhead of starting/stopping 20 containers exceeds the test execution time.
✅ Correct: Match container count to suite size. Rule of thumb: 1 container per 50 tests, up to a maximum of 8-12 containers.