Skip to main content
Cypress CloudBusiness Plan

Re-run optimization Experimental

info
What you'll learn​
  • How to get to a passing build faster by re-running only failed specs
  • How to cut CI compute cost and billed test results on every rerun
  • How to enable Re-run optimization at the organization and project level
  • How Cypress Cloud decides which specs to skip on a rerun

When a CI run fails, it's common to rerun the job to confirm a fix or clear a flaky failure. Normally that rerun executes your entire test suite again, including the specs that already passed. Re-run optimization re-runs only the specs that contained failures and skips the specs that already passed, so you spend CI time re-testing what actually failed instead of re-validating work that was already green.

For example, a 40-spec suite where only 2 specs fail normally re-runs all 40 specs on a retry. With Re-run optimization, the rerun executes just those 2 specs, turning a full rerun that might take 30 minutes into a couple of minutes, and billing you for 2 specs instead of 40. The more reliable your suite, the bigger the win on each retry.

Enabling Re-run optimization gives you:

  • A faster path to green: reruns finish in a fraction of the time because passing specs are skipped entirely.
  • Lower CI compute cost: skipped specs never spin up machines or consume CI minutes.
  • Fewer billed test results: you aren't charged for re-validating work that already passed, since skipped specs are never executed.

Re-run optimization operates at the spec level. If a spec contains at least one failing test, the entire spec is re-run (including any tests within it that passed). Specs where every test passed are skipped.

caution

Re-run optimization is experimental. We are shipping an early version to learn how it performs across real CI setups, and we expect it to evolve. Request access from your Cypress representative if you don't see this available in your organization or project settings pages.

Review the behavior and limitations before enabling it on critical pipelines.

How it works​

  1. You trigger a rerun from your CI provider after a run fails. For example, "Re-run jobs" or "Re-run failed jobs". Re-run optimization behaves the same way for both.

    A run in CI provider UI showing button to re-run workflow from failed

  2. Cypress Cloud links the original run to every rerun. A stable rerun group ID tells Cloud they belong to the same CI build. On supported CI providers, Cypress sets this ID automatically from your CI environment. On other providers, you can set it manually with CYPRESS_RERUN_GROUP_ID.

  3. Cypress Cloud picks the latest completed run in that group as the anchor run. The anchor run is the reference point that determines which specs still need to run.

  4. Only the specs that failed in the anchor run are re-executed. Cypress will skip every spec that already passed on rerun, so your rerun focuses on what is still broken.

When this happens, the Cypress App prints a notice near the start of the run's CLI output, for example:

Warning from Cypress Cloud: This run is only retrying failed specs from run 1234.
It will not include specs that passed in that run.

The anchor is always the latest completed run for the rerun group, regardless of which specific run you clicked "rerun" on in your CI provider's UI.

In Cypress Cloud, a run that was rerun is labeled with a Re-run tag, so you can identify reruns at a glance and confirm that Re-run optimization was applied.

A run in Cypress Cloud showing a Re-run tag indicating the run was rerun

Availability​

Re-run optimization is a Smart Orchestration feature available to users on a Business or Enterprise tier Cypress Cloud plan, as well as during a free trial. If you do not see this feature in your settings page during the experimental period, request access from your Cypress representative.

tip

Wondering if upgrading your Team tier subscription is worth it? Check out the recommendations on the run overview page to see how much time we predict Smart Orchestration features would save you.

Enable Re-run optimization​

Re-run optimization is configured in the Smart Orchestration section of your organization and project settings. Only Owners and Admins can change the setting. Members and Viewers have read-only access.

Project setting​

Each project can inherit the organization default or override it.

  • Organization default (selected by default) follows the org-level setting.
  • Run everything again disables Re-run optimization for the project.
  • Run only failed specs enables Re-run optimization for the project.
Re-run optimization project setting in Cypress Cloud, showing the Organization default, Run everything again, and Run only failed specs options

Organization setting​

Sets the default behavior for every project in the organization.

  • Run everything again rebuilds the full suite on a rerun. This is the default for existing organizations.
  • Run only failed specs enables Re-run optimization. This will be the default for newly created organizations.
Re-run optimization organization setting in the Smart Orchestration section of Cypress Cloud, showing the Run everything again and Run only failed specs options

CI provider support​

On supported providers, Cypress detects reruns automatically and builds the rerun group ID for you. For any other provider, use the CYPRESS_RERUN_GROUP_ID environment variable to enable Re-run optimization manually.

CI providers that don't require manual setup:

note

CircleCI and Bitbucket Pipelines require Cypress v15.15.0 or later.

Setting the rerun group ID manually​

All other CI providers that require manual setup

For these providers, CYPRESS_RERUN_GROUP_ID is the rerun group ID that links an original CI run to all of its reruns. Set it when your CI provider isn't automatically supported, or when you want explicit control over grouping. Requires Cypress v15.15.0 or later.

The value must be:

  • Shared across an original run and all of its reruns.
  • Unique between builds that are not related to one another.

A CI build identifier that persists across retries is usually a good fit. When Cloud receives a run with CYPRESS_RERUN_GROUP_ID set, it uses that value to find the anchor run and, if Re-run optimization is enabled, skips the specs that passed there.

note

CYPRESS_RERUN_GROUP_ID takes precedence over automatic detection. On supported providers, setting it overrides the rerun group ID that Cypress would otherwise construct for you.

Opting out in CI​

To force a full run and skip the optimization, set the CYPRESS_RERUN_ALL_TESTS environment variable to true (requires Cypress v15.15.0 or later). Cloud then treats the run as a full run and runs every spec, even if a matching anchor run exists. This is useful for specific branches or pipelines where you always want the complete suite to run.

env:
  CYPRESS_RERUN_ALL_TESTS: true

What a rerun will execute​

Every rerun is compared against your most recent completed run in the rerun group, and re-executes only the specs that were still failing there. That means you can trust a rerun to always work from your latest results: within the depth limit it does not re-run specs that already passed, and it does not revert to an older, larger set of failures. That most-recent completed run is called the anchor run.

Knowing this lets you predict exactly what a rerun will do:

  • You rerun a completed run → it retries that run's failing specs. The common case, and where you see the biggest time and cost savings.
  • You rerun after several attempts → each rerun anchors on the latest completed run, so chained reruns keep narrowing toward what's still broken instead of replaying earlier failures you've already fixed.
  • You rerun while another run is still in progress → Cloud anchors on the last completed run, since the in-progress one has no final results yet.
  • You rerun within the run-completion delay window → Cloud hasn't marked the previous run complete yet, so the rerun safely runs the full suite. Set a short run-completion delay so more of your reruns get optimized — this is the main lever for getting consistent savings.

Cloud never blocks parallel reruns: if several start at once, each one anchors on whichever run is complete at the time it begins.

Behavior and limitations​

These tradeoffs are why the feature is experimental and opt-in. For most reruns the speed and cost savings far outweigh them, but it's worth understanding them before enabling Re-run optimization on critical pipelines:

  • Passing results are not carried forward. A rerun-optimized run shows only the specs that were re-executed. Specs that passed in the anchor run do not appear in the rerun's results.
  • Passing specs are skipped for up to 5 chained reruns. Re-run optimization filters out specs that passed in earlier runs in the group, looking back up to 5 runs. A 6th rerun re-executes the passing specs from the original run.
  • Reporter output reflects only the re-executed specs. CI guardrails based on test counts (JUnit/XML reporters, custom reporters, threshold checks) will see fewer specs and tests than a full run. You may need to adjust these on your end.
  • CLI messaging is limited. The CLI prints a notice for the specs being re-run, but the skipped specs are not listed in the output.
  • Analytics may be incomplete. Analytics features such as App Quality won't be fully accurate for rerun-optimized runs, because those runs contain only a subset of specs.
  • Cypress Accessibility and UI Coverage reports may be incomplete. Rerun-optimized runs reflect only the specs that were re-executed, not the full suite from the anchor run.
tip

Pair Re-run optimization with other Smart Orchestration features for compounding savings. With Spec Prioritization failures surface first, with Auto Cancellation the run stops early once they do, and with Re-run optimization the retry replays only the failed specs — so each layer gets you to a passing build faster and cheaper.

See also​

Contents