Cypress Parallelization: How to Split Specs Across CI Machines

How Does Cypress Parallelization Work?

Cypress parallelization is file-based. The Cypress documentation on parallelization (as of Nov 2026) says Cypress hands out whole spec files, not individual tests, so a single 300-test spec file can never be split.

If you need a refresher on the Cypress CLI flags such as --record and --parallel, start there. Two consequences follow:

• Your spec layout is what ultimately determines your speed limit. The longer your spec file is, the longer your run time will be (regardless of how many machines you add).
• Order is not guaranteed. Cypress makes it quite clear that spec order is not guaranteed when parallelized, so no spec is going to be guaranteed to run before another.

As of Nov 2026, Cypress's public roadmap has Native Parallel Runs listed as "Evaluating" (it would allow you to run your tests in parallel from the Cypress App even if you're not recording to Cloud). In the meantime, the only options you have are the ones below.

Every option below is of the same format: list the spec files, split them between N workers, run cypress run --spec on each worker, and then collect the results. The options differ in terms of who does the splitting and how evenly you split them.

Which of the Four Cypress Parallelization Options Do You Use?

If you're going to outgrow the 500 recorded results per month and don't want to go with a Cypress Cloud plan, then start with cypress-split. If your bigger issues are actually CI capacity, artifacts and flaky test triage, then you're better off looking at an orchestrator.

Cypress-Split vs Cypress Cloud: both can balance the specs by previous durations. Cypress-Split keeps the timings in a file in your repo and requires no external service at all. Cypress Cloud stores the run history for you and is free up to 500 test results a month (as of Nov 2026).

As of Nov 2026, you may also come across the tgamauf/cypress-parallel GitHub Action. That one builds a per-spec list for a matrix without the need for Cypress Dashboard, though the repo has been archived (read-only since 2nd June 2026) and it doesn't support defineConfig in cypress.config.* files so again cypress-split is the safer option for a new setup.

Skip the runner plumbing entirely

Note: HyperExecute will run your existing Cypress specs in parallel from a single YAML file, with no modification to your tests at all. Run your first job on HyperExecute.

How Do You Split Your Cypress Specs Across GitHub Actions Jobs?

New to Cypress on GitHub Actions? Start off by just running your Cypress tests with GitHub Actions and then come back here to look at splitting the run.

cypress-split is a free plugin that picks this machine's share of specs from two environment variables: SPLIT (total machines) and SPLIT_INDEX (this machine's zero-based index). It needs no external service.

npm i -D cypress-split

const { defineConfig } = require('cypress')
const cypressSplit = require('cypress-split')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      cypressSplit(on, config)
      return config
    },
  },
})

# .github/workflows/e2e.yml
name: e2e
on: [pull_request]
jobs:
  cypress:
    runs-on: ubuntu-24.04
    strategy:
      fail-fast: false          # let every worker finish so you see all failures
      matrix:
        containers: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v7
      - name: Run this worker's share of specs
        uses: cypress-io/github-action@v7
        env:
          SPLIT: ${{ strategy.job-total }}
          SPLIT_INDEX: ${{ strategy.job-index }}
          SPLIT_FILE: timings.json

How Do You Balance the Specs so That No Machine Is Sitting Idle?

Splitting by file name is quick to set up but very uneven (one machine can end up with the three slowest specs).

Cypress-split addresses this with a timings file. The duration of each spec is recorded in timings.json; any spec missing from the file gets the average duration, and the plugin only rewrites the timings file if a spec is new or a duration has changed by more than 10%.

{
  "durations": [
    { "spec": "cypress/e2e/checkout.cy.js", "duration": 61200 },
    { "spec": "cypress/e2e/search.cy.js", "duration": 18400 }
  ]
}

Each parallel job writes its own timings, so you do need to merge them. The plugin comes with cypress-split-merge for that. Author Gleb Bahmutov describes two ways to keep the timings up to date: a single nightly job that just runs and commits fresh timings, or a workflow that merges the timings from the parallel jobs.

In his example, name-based splitting resulted in one machine running two specs for around 70 seconds while the other finished off early. With the timings, the slowest spec was left to run alone, and the rest shared the second machine.

Can You Run Cypress Specs in Parallel on a Single Machine?

You can; it's a trade-off. The cypress-parallel package's README states it can deliver up to a 40% reduction in run time by parallelizing on the same machine.

Cypress's own parallelization documentation actually advises against doing parallel tests on a single machine due to the resources it requires.

In a June 2023 NashTech test of six specs (38 tests), cypress-parallel took 53 seconds with 2 threads and 57 seconds with 4 threads, compared to 42 seconds sequentially (CPU load went up in the process). The same post's GitHub matrix run took about 43 seconds total, limited by an 18-second-long spec.

Whether one machine helps is going to depend on your spare CPU and memory, so you'll need to check it on your own suite. For reliable gains, you'll want to run it on separate machines or containers. For quick local runs, you can often get away with just filtering the specs using --spec.

To try it with cypress-split, open two terminals and give each one its share using the plugin's environment variables:

# terminal 1
SPLIT=2 SPLIT_INDEX=0 npx cypress run

# terminal 2
SPLIT=2 SPLIT_INDEX=1 npx cypress run

Watch the CPU and memory while both are running, and only keep the setup if the total time goes down.

How Do You Run Your Cypress Specs in Parallel on HyperExecute?

HyperExecute is TestMu AI's test orchestration platform. It takes your existing Cypress suite and runs it on fresh cloud VMs via a single YAML file. The HyperExecute Cypress guide covers two modes: Auto-Split (which will take the specs it discovers and split them across the number of parallel sessions you've specified) and Matrix (which will run the combinations that you explicitly list).

The YAML below is a copy of the documented Auto-Split sample (using a Windows runner), with your spec folder in place of the one in the sample. testDiscovery will list the spec files, and HyperExecute will pass each result into testRunnerCommand as $test:

# hyperexecute.yaml
version: 0.1
runson: win
cypress: true
autosplit: true
concurrency: 4            # parallel sessions
retryOnFailure: true
maxRetries: 1

runtime:
  - language: node
    version: "22"

pre:
  - npm install
  - npm install cypress --save-dev

cacheKey: '{{ checksum "package.json" }}'
cacheDirectories:
  - node_modules
  - cypressCache

env:
  CYPRESS_CACHE_FOLDER: cypressCache

testDiscovery:
  type: raw
  mode: static
  command: ls cypress/e2e/2-advanced-examples

testRunnerCommand: npx cypress run --spec ./cypress/e2e/2-advanced-examples/$test --browser=chrome --headed --config video=false

jobLabel: [cypress, autosplit]

The doc sample is pinned to Chrome 95. Set --browser to whichever version of Chrome your HyperExecute runner supports.

Run it via the HyperExecute CLI. The CLI will read your credentials from the LT_USERNAME and LT_ACCESS_KEY environment variables (just copy both of those from your TestMu AI profile into your shell or your CI secrets) so they don't appear on the command line or in a URL:

./hyperexecute --config hyperexecute.yaml --force-clean-artifacts --download-artifacts

Run against the 17 specs in the doc's sample repo, this YAML split them across four sessions. The job took 5m23s against 17m17s of cumulative session time, and the two specs written for an older Cypress version failed again on retry.

Three things change compared with DIY splitting:

• No timings file to maintain. Auto-Split will distribute the specs across the sessions for you, and TestMu AI's AutoSplit video describes "an automatic reordering mechanism that prioritizes flaky tests that failed in previous runs".
• Retries are explicit. retryOnFailure and maxRetries are in the YAML, so a retried spec is visible in the run (not hidden away in a shell loop). A retry never alters what constitutes a pass: the spec still has to pass its assertions.
• One place for results. The HyperExecute page has per-test artifacts (video, screenshots, logs), AI root cause analysis, and flaky test detection via a sliding window (defaults to the last 10 runs). Transavia reports 70% faster test execution and Boomi 78% faster per the same page.

If you just need more parallel browsers for an existing Cypress run, then you can run your Cypress tests in parallel on the TestMu AI cloud by setting parallels as per the Cypress grid guide.

What Breaks When the Cypress Specs Run in Parallel?

The vast majority of new failures you see once you've parallelized are not flaky tests at all. They are tests that were reliant on running in isolation. Look for those first.

The SPLIT Checklist for Cypress Parallelization

Use this before you add machines:

• S - Spec-sized files. No spec file will run longer than your target run time.
• P - Per-spec data. Each spec creates or resets the data that it uses.
• L - Load balanced. Specs are split by recorded duration, not by name.
• I - Index from CI. The worker count and index come from the CI or the orchestrator; they are not hard-coded.
• T - Tied together results. Reports, videos and screenshots from every worker all end up in one place.

Watch: Splitting Tests in HyperExecute

For a quick visual walkthrough of this concept, watch the videos below from TestMu AI.

Subscribe to the TestMu AI YouTube channel for more tutorials on testing and automation.

Conclusion

Start with the SPLIT checklist, then pick the splitter that fits your suite: Cypress Cloud's free Starter plan for small suites, cypress-split for free balancing on your own CI, or HyperExecute when you also want retries, artifacts, and failure analysis handled for you.

Before you add machines, break up any spec file that runs longer than your target time, because no splitter can divide a single file. Then compare the run's wall-clock time with the total time your workers consume, and keep an extra machine only while it still shortens the run.

Once the split works, fix the specs that only fail in parallel: seed each spec's own data, give it a unique user or order, and drop any reliance on spec order.

Running a growing Cypress suite in CI? HyperExecute by TestMu AI splits your spec files across parallel cloud VMs from one YAML file, with retries and per-test artifacts in the same job.

To run your first test, start free, or

book a demo

for a full walkthrough of the product.