skip to content

Under `cypress run --parallel`, how does Cypress Cloud decide what each machine runs?

level: middleimportance: must knowfreq 68%

answer

  1. Nothing is assigned in advance
  2. Whole files, never split
  3. One shared, ordered queue
  4. Longest predicted spec goes first
  5. Estimates come from recent recorded runs

basics

~20 s

Cypress Cloud keeps one queue of whole spec files ordered by predicted duration, longest first, and hands the next spec to whichever machine is free. Nothing is assigned in advance, so spec order is not guaranteed.

solid answer

~50 s

Parallelisation in Cypress is **file-based and pull-based**. Every machine runs the same `cypress run --record --parallel` command, reports the same spec list to Cypress Cloud, and then asks for work; the Cloud replies with **one spec at a time**. It orders that queue from duration estimates built out of the project's recent recorded runs — estimated separately per browser — and hands out the slowest specs first, so the long poles start early and quick specs fill the gaps at the end. Because a free machine simply pulls the next spec, capacity flows where it is needed and no machine sits idle holding a pre-assigned backlog. Two consequences follow: spec **run order is not guaranteed**, and a spec is never split, so one enormous `checkout-flow.cy.ts` sets a floor on the run however many machines you add.

code

bash · 4 lines
bash
# every machine in the CI job runs this identical command
npx cypress run --record --parallel \
  --browser chrome \
  --group storefront-e2e

go deeper

for a junior

Know that parallel Cypress runs need --record, that the unit of work is a whole spec file, and that you cannot rely on specs running in any particular order.

for a middle

Explain the pull model: machines ask, the Cloud answers with one duration-ranked spec each time, and estimates come from the project's own recent runs, per browser.

for a senior

Diagnose an unbalanced run from the Machines View — one long spec pinning the wall clock, specs too small to be worth splitting, or a machine count past the point of balance.

for a principal

Own the spec-file granularity your suite is written at, since that is the only lever that changes what parallelism can buy, and decide when adding machines has stopped paying.

## The unit of work is a whole spec file Cypress's parallelisation strategy is **file-based**. Cypress Cloud never splits a spec: whatever `checkout-flow.cy.ts` contains, one machine runs all of it, start to finish. That single fact explains most of what follows, including why adding machines eventually stops helping. For a suite to parallelise at all, then, the work has to already be spread across separate spec files. A storefront monorepo with three enormous specs — one per package — parallelises across exactly three machines and no further. ## A queue, not a dealt hand Nothing is assigned up front. Every machine runs the same `cypress run --record --parallel` command and then negotiates with the Cloud: 1. Each machine contacts Cypress Cloud and reports the list of spec files it can see for the project. 2. A machine opts in to work by asking for a spec. 3. The Cloud estimates how long each outstanding spec will take. 4. It hands that machine **one** spec, chosen to minimise the total run time. 5. When the machine finishes that spec it comes back for another, and this repeats until the list is exhausted. Because work is handed out one spec at a time to whichever machine is free next, capacity flows to wherever it exists. A machine that draws a fast spec simply comes back sooner. Nothing can leave one machine idle while another still has a backlog — there is no backlog to hold, only a queue. The direct consequence is that **spec run order is not guaranteed** under `--parallel`. Any test that depends on another spec having run first is already broken; parallelising is what makes it fail. ## Where the ordering comes from The Cloud predicts each spec's duration from the project's own recent recorded runs, and hands out the **longest specs first**, so the long poles start at the beginning of the run and the short specs fill the gaps at the end rather than being the last thing anyone waits for. Two details matter in practice: - Estimates are kept **per browser**, because the same spec can behave quite differently in Chrome and Firefox, and a run that mixes them stays balanced. - Old history is deliberately not used, so the estimates track a suite that is actively changing instead of a suite that existed six months ago. That is also why balancing is self-correcting: add a spec, delete one, or let one get slower, and the next runs re-balance with no list to maintain anywhere. ## What load balancing cannot fix - **One spec that dominates the run.** The run cannot finish before its slowest single spec, no matter how many machines are available. If the Machines View shows one machine running for twelve minutes while the rest finish in three, that is the symptom. - **Specs that are too small.** Below roughly ten seconds, per-spec overhead — launching the browser, encoding and uploading video, asking for the next spec — costs more than the split saves. - **Machines beyond the point of balance.** Once every machine finishes at about the same time, another machine has nothing left to absorb. - **The very first recorded run**, which has no duration history to order by. It balances on later runs, not that one. ## Reading the balance in the Cloud The run's Specs tab is where you check whether any of this is working, and its three views answer different questions: - **Machines View** charts specs by the machine that ran them. When balancing is healthy every machine finishes at about the same time; a machine still running long after its neighbours stopped is the imbalance, and adding machines will not touch it. - **Bar Chart View** ranks specs by duration relative to each other, which is how you find the one spec worth splitting. - **Timeline View** charts the machines against wall-clock time, so idle stretches at the end of a run show up as gaps rather than having to be inferred. ## Two things can change the order on top | what | what it decides | where it is configured | |---|---|---| | load balancing | the default order, longest predicted spec first | always on with `--record --parallel` | | Spec Prioritization | moves specs that failed in the previous run to the front | a Cypress Cloud project setting | | Auto Cancellation | not order at all — when to stop handing out specs | a project setting, or `--auto-cancel-after-failures` | Spec Prioritization only lifts previously failed specs to the front; everything behind them is still distributed in load-balanced order across every machine. When it fires, the run is labelled in the Cloud with the run whose failures drove the order, so you can see exactly what it reacted to.

  • Your Cypress run uses eight machines but finishes no faster than with five. What do you look at?
    The Machines View for the run. If every machine finishes at roughly the same time, the suite is already balanced and more machines have nothing to absorb. If one machine runs far longer than the rest, a single spec is setting the floor — Cypress balances whole files and cannot split one, so the fix is to break that spec into smaller files of comparable duration, not to add capacity.
  • What does Spec Prioritization change about the order, and what does it leave alone?
    It moves the specs that failed in the previous run to the front of the queue, so a still-broken change fails in the first minutes instead of the last. Everything else is untouched: the remaining specs are still distributed in normal load-balanced order across every machine, and prioritisation changes only order, never which specs run or how they are assigned.

It is a deli counter, not a dealt hand of cards. No machine is given its whole workload up front; each one takes the next ticket the moment it is free, so the queue drains as fast as the servers can work.

saying these in an interview costs you the question

  • Thinks each machine is assigned a fixed slice of specs upfront
  • Believes Cypress splits an individual spec across machines
  • Expects specs to run in alphabetical or specPattern order
  • Says balancing is by spec count rather than duration
  • Assumes more machines always shortens the run