Your Cypress end-to-end suite started fast. Then it grew. More specs, more coverage, more release confidence, all wins your team celebrated. But as your quality practice matured and the suite kept growing, run times started to creep up, climbing from a few minutes toward an hour or more. Now pull requests wait in a queue, and the feedback loop that used to feel nearly instant is long enough to pull you out of your workflow and stall velocity.
If this is a familiar story for your team, the reassuring part is that you have a scaling problem, not a testing problem. Your tests are fine. They are just running one at a time, on too few machines. Getting your speed back takes two things working together: intelligent orchestration and infrastructure.
This guide covers how to combine Cypress Smart Orchestration (the intelligence layer) and Harness CI (the infrastructure layer) to achieve an optimized CI pipeline.
The Layers: How the Two Tools Divide the Work
The cleanest way to think about this integration is a split of responsibility. Cypress Cloud is the brain. Harness CI is the muscle and the shell.
|
Decides |
|
Provides |
|
Optimizes |
Cypress Smart Orchestration: The Brain
Smart Orchestration is a suite of features within Cypress Cloud that turns long, sequential CI runs into optimized orchestrations that evolve with your test suite. Here is a breakdown of those features and how they contribute to pipeline performance.
Parallelization
Parallelization runs your spec files at the same time across multiple machines instead of one after another. You record the run to Cypress Cloud and pass the --parallel flag, and Cypress Cloud coordinates the machines for you.
What it adds: the most direct cut to wall-clock time. A suite that takes 30 minutes on a single machine can finish in a fraction of that across several, which is the difference between a feedback loop developers wait on and one they barely notice. And because runs stay fast, your team can keep adding coverage without the suite turning back into a bottleneck.
Load Balancing
Load Balancing is what makes parallelization efficient rather than just parallel. As you record runs, Cypress Cloud learns how long each spec takes and uses that history to distribute specs across your machines, starting the longest specs first so every machine finishes at roughly the same time.
What it adds: full use of every machine you pay for. Without balancing, one slow spec can leave a machine running long after the others have gone idle, time you are billed for and gain nothing from. Additionally, there is no manual test splitting to set up, and nothing to re-tune as specs come and go. And because Cypress Cloud keeps learning from each run, the balancing sharpens over time rather than decaying, so your speed holds as the suite grows.
Auto Cancellation
Auto Cancellation, available on Business and Enterprise Cypress Cloud plans, stops a run once failures cross a threshold you set, rather than letting the rest of the suite run to completion.
What it adds: lower cost and recovered capacity. On a run that gates a merge, crossing the failure threshold already means the branch will not ship, so finishing the suite only spends time and money without changing that verdict. Stopping when the threshold is reached trims your recorded-test count, saves on CI minutes, and returns CI machines to the queue sooner. On earlier feature branches, you can raise the failure threshold or leave it off, trading completeness for cost on your terms.
Spec Prioritization
Spec Prioritization runs the specs that failed in your previous run first, ahead of the rest of the suite.
What it adds: faster confirmation that a fix worked. On its own, it changes only the order specs run in, not the total time. Paired with Auto Cancellation, it shortens runs, because a failure that is going to happen tends to happen earlier, which triggers cancellation sooner.
Harness CI: The Muscle
Harness CI provides the shell that Cypress Cloud's orchestration runs within. Here are the three pieces that supply the machines and keep each build fast and cheap as you scale:
- Stage-level Looping Strategy This is what creates the machines. Set parallelism on the stage rather than the step. Stage-level parallelism duplicates the whole stage, so each copy is its own machine with its own workspace, while step-level parallelism would stack the copies onto a single shared machine. Every machine runs the same cypress run command, and Cypress Cloud decides which specs land where.
- Cache Intelligence Each machine clones and installs on its own, so without caching every one of them would pull every dependency from the registry on each build. Caching restores npm's download cache from the previous run instead, so
npm ciinstalls from local tarballs rather than over the network, keeping the install step short on each machine. - Prebuilt Cypress Image Run the Cypress step on cypress/included, which ships with the Cypress binary and the browsers already installed. Each machine skips downloading and installing them, leaving your project dependencies as the only per-machine setup, which the cache already covers.
How to Run Cypress in Parallel in Harness CI
Now let's bring these tools together in a single pipeline that restores your fast feedback loop.
Prerequisites
- A Cypress Cloud project with recording enabled.
- A Cypress Cloud record key stored as a Harness secret (e.g.
cypress_record_key). - A Harness CI pipeline connected to your code repository.
Setting Up a Shared CI Build ID
For Cypress Cloud to treat your parallel machines as one run, every machine must share the same CI build ID. Cypress derives this ID from environment variables that are unique to each CI build. In Harness, pass the build ID explicitly with a pipeline expression so every machine in the same execution share one value:
--ci-build-id <+pipeline.sequenceId>Because every machine belongs to the same pipeline execution, <+pipeline.sequenceId> resolves to the same value across all of them.
Pro-tip: Add a --group flag as well, so the run is labeled clearly in Cypress Cloud.The Cypress Command
This is the command each machine runs. The record key comes from the CYPRESS_RECORD_KEY environment variable, which you set from your Harness secret in the stage below.
npx cypress run \
--record \
--parallel \
--ci-build-id <+pipeline.sequenceId> \
--group harness-e2eThe Harness Stage
The YAML below is illustrative. Connectors, image tags, identifiers, and the instance count are placeholders that should be adapted to your individual project requirements.
# Example Harness CI stage.
- stage:
name: E2E Tests
identifier: e2e_tests
type: CI
# Looping strategy (stage level): five identical machines
strategy:
parallelism: 5
spec:
cloneCodebase: true
# Build infrastructure (Harness-hosted)
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec: {}
# Cache Intelligence: restore npm's download cache on each machine
caching:
enabled: true
key: cache-{{ checksum "package-lock.json" }}
paths:
- .npm
execution:
steps:
# Runs on each machine; the cache keeps it fast
- step:
name: Install
identifier: install
type: Run
spec:
shell: Sh
command: npm ci --cache .npm --prefer-offline
- step:
name: Cypress E2E
identifier: cypress_e2e
type: Run
spec:
shell: Sh
# cypress/included bundles Cypress and the browsers
image: cypress/included:14.0.0
envVariables:
# Cypress reads CYPRESS_RECORD_KEY automatically
CYPRESS_RECORD_KEY:<+secrets.getValue("cypress_record_key")>
command: |
npx cypress run \
--record \
--parallel \
--ci-build-id <+pipeline.sequenceId> \
--group harness-e2eWhat each part is doing:
- runtime.type: Cloud runs the stage on Harness Cloud infrastructure; use your own build infrastructure if you self-host.
- strategy.parallelism: The looping strategy, declared at the stage level. It creates five identical copies of the stage, which is five separate machines, and Cypress Cloud distributes your specs across them.
- caching turns on Cache Intelligence: The key ties the cache to your lockfile, and .npm is npm's download cache, so
npm ciinstalls from local tarballs instead of the network. Cypress and the browsers come from the cypress/included image, so there is nothing else to cache. - The cypress run command is identical on every machine: The shared
--ci-build-idis what tells Cypress Cloud the five machines are one run.
Spec Prioritization and Auto Cancellation do not appear in this YAML. Turn them on in your Cypress Cloud project settings, and they take effect on recorded runs with no pipeline change.
What You Get
When Cypress's orchestration and Harness's infrastructure work together, you reclaim the speed of your feedback loop without stifling growth. Cypress Cloud spreads your specs across the parallel machines, getting smarter with each run, so adding coverage stops creating bottlenecks. Failures surface earlier, you stop paying to finish runs that have already failed, and your dependencies come from cache instead of a fresh download every build.
The suite that had crept toward an hour becomes fast feedback your team can depend on as your test suite grows.
The quickest way to see it is on your own suite. A 30-day Cypress Cloud trial provides access to all Smart Orchestration features. Once your Cloud project is set up, point the cypress run step in your Harness pipeline at a Cypress Cloud project, record a parallel run, and watch the specs balance across your machines in real time. The Cypress Smart Orchestration documentation covers each feature when you are ready to fine tune them.