How to Parallelize Cypress Tests With Cypress Cloud

Cypress parallelization needs --record and Cypress Cloud, which balances specs across machines by their historical timing.

Start several jobs with the same --ci-build-id, pass --parallel --record, and Cypress Cloud hands each machine the next spec to keep them balanced.

Steps

• Set a CYPRESS_RECORD_KEY secret and enable the project in Cypress Cloud.
• Fan out with a matrix and pass --parallel --record.
• Share a --ci-build-id so all machines join one balanced run.

Workflow

jobs:
  e2e:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        containers: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx cypress run --parallel --record --ci-build-id ${{ github.run_id }}
        env:
          CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}

Gotchas

• Cypress load balancing requires --record; --parallel alone will error.
• The matrix value drives machine count, not which specs run; Cloud assigns specs.

Related guides