How to Retry and Rerun Cypress Tests

Cypress retries and reruns happen at different times. A retries setting makes Cypress attempt a failed test again within the same run. To rerun a spec after a run has finished, use the CLI --spec option, or use Cypress Cloud rerun optimization for an eligible recorded CI build.

Retries are disabled by default. A setting of retries: 2 means two additional attempts after the first, for up to three attempts total. Retries can help identify flaky tests, but a test that only passes on a later attempt still deserves investigation.

1. Configure retries within a Cypress run

Set retries in your Cypress configuration file. A number applies to both interactive and run modes:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  retries: 2,
})

To use separate settings for headless or CI runs and interactive runs, provide an object:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  retries: {
    runMode: 2,
    openMode: 0,
  },
})

This CommonJS example fits a cypress.config.js project configured for require and module.exports. In a TypeScript configuration, import defineConfig from cypress and use the same retries property in the exported config. Match the module syntax to your project.

The documented defaults for runMode and openMode are both 0. See Cypress’s test retries guide and configuration reference.

Set a retry count for a specific test

Cypress also supports per-test retry configuration. Use it for a targeted test when there is a clear reason for different handling; keep global retries modest so a broad suite does not repeat unnecessary work.

it('loads the account summary', { retries: 2 }, () => {
  cy.visit('/account')
  cy.get('[data-testid="account-summary"]').should('be.visible')
})

Confirm the per-test configuration syntax against the Cypress version in your project using the official guide.

What happens on another attempt?

The configured retry count is the number of attempts after the initial attempt. Two retries allow up to three total attempts.
beforeEach and afterEach hooks run again for a retried test.
Failures in before and after hooks do not trigger a test retry.

These lifecycle details matter when tests create, mutate, or clean up shared state. Ensure setup can safely run again and cleanup does not assume it will happen only once.

2. Rerun a failed spec from the command line

After a completed run, select the spec file explicitly from the project root:

npx cypress run --spec "cypress/e2e/my-spec.cy.js"

The path must match your configured specPattern. The --spec option can also accept a glob or multiple comma-separated spec paths.

If a package script wraps Cypress, pass the option through the package manager. For npm:

npm run e2e:chrome -- --spec "cypress/e2e/my-spec.cy.js"

The arguments after -- are forwarded to the script. Refer to the Cypress CLI reference for command and option details.

Rerun several selected specs

npx cypress run --spec "cypress/e2e/login.cy.js,cypress/e2e/checkout.cy.js"

For a glob, quote it so the shell passes it to Cypress rather than expanding it first:

npx cypress run --spec "cypress/e2e/**/*.cy.js"

This runs the files selected by the pattern that also match Cypress’s configured spec pattern. A manual spec rerun runs the selected spec again; it does not automatically identify only the individual failed test inside it.

3. Rerun failed work in Cypress Cloud CI

A CI rerun happens after a Cypress run has completed. Cypress Cloud rerun optimization can use a completed recorded run as an anchor and skip work that passed, when the project, plan, CI provider, runner version, and rerun grouping meet the feature requirements.

Rerun mode	What runs again	Requirement or detail
Only failed specs	Each spec that contains a failure runs again, including tests in that spec that previously passed.	Available for eligible Cypress Cloud projects and CI configurations.
Only failed tests	Tests that did not pass in the anchor run are selected for rerun.	Requires Cypress 15.21.0 or later, as stated in the current Cloud documentation.

Cloud availability and setup depend on Cloud tier and project or organization settings. The documentation lists Business or Enterprise tiers and a free trial for rerun optimization; verify the current requirements before enabling it. Supported CI providers include GitHub Actions, Azure Pipelines, CircleCI, Bitbucket Pipelines, and GitLab CI. Other providers may require manual rerun grouping with CYPRESS_RERUN_GROUP_ID.

Record the Cypress run to Cypress Cloud in CI.
Check the project’s rerun optimization settings and the relevant Cloud plan.
Confirm that the CI provider and Cypress runner version satisfy the documented requirements.
Ensure the rerun is associated with the intended anchor run. Cloud compares it with the latest completed run in its rerun group.
Choose whether to rerun failed specs or, with a supported version, only failed tests.

Do not assume that a CI retry button automatically invokes optimized reruns. Check the Cloud project configuration and grouping for your provider. See Cypress Cloud’s rerun optimization guide for current availability and provider-specific setup.

For recorded CI failures, Cypress also documents a Cloud CLI for retrieving run status and failure details, screenshots, and Test Replay data from a terminal. Its documentation says it is available on Cypress Cloud plans including Starter at no additional cost; check the Cloud CLI guide for current usage.

4. Distinguish test retries from query retry-ability

Cypress has two behaviors developers often call “retries.” Query retry-ability happens while a test attempt is running: linked queries and assertions retry together while waiting for a condition. Non-query commands execute once. Test retries happen after an attempt fails and start the test attempt again.

Behavior	When it happens	What it repeats
Query retry-ability	During one test attempt	Linked queries and assertions while Cypress waits for the condition.
Test retries	After an attempt fails	The failed test attempt, including applicable per-test hooks.
Spec or CI rerun	After a run has completed	A manually selected spec or work selected by the CI/Cloud rerun mechanism.

If an assertion races a changing page, first check whether the test uses retryable queries and a suitable assertion. Increasing test retries may hide timing or synchronization problems without fixing them. See Cypress retry-ability documentation.

5. Choose the right rerun method

Use query retry-ability when the page is expected to reach a condition shortly and a linked query or assertion can wait for it.
Use a small test retry count to expose intermittent failures and collect evidence across attempts.
Use --spec when you want to reproduce a particular spec locally or rerun it from a script.
Use Cloud rerun optimization when you need an eligible recorded CI run to rerun failed specs or failed tests while avoiding work that passed.

These options differ in timing, granularity, and setup. A retry is part of the same Cypress run; CLI and Cloud reruns start after a run has completed. A manual spec rerun selects files, while Cloud can select failed specs or, with the required version, failed tests.

6. Troubleshoot common problems

Symptom	Likely cause	Fix
The test runs only once after failing.	Retries are still at the default of zero, or the retry setting is in a mode that does not apply to this command.	Set `retries` globally or for the test. For mode-specific values, check `runMode` versus `openMode`.
A `before` or `after` hook failure is not retried.	Cypress does not trigger test retries for failures in these hooks.	Fix the failing hook and make setup or teardown reliable. Do not expect a test retry setting to rerun it.
`--spec` finds no tests or selects nothing.	The path may not match the file location or configured `specPattern`; shell glob expansion may also change the argument.	Run from the project root, check the configured pattern, verify the path, and quote glob expressions.
The npm command treats `--spec` as an unknown script argument.	The option was not forwarded through the package script.	Put `--` before Cypress options, as in `npm run e2e:chrome -- --spec "cypress/e2e/my-spec.cy.js"`.
Cloud rerun repeats too much work.	The mode is “failed specs,” which reruns all tests in each spec that had a failure.	Use failed-test-level reruns if your project and Cypress version support them; this requires Cypress 15.21.0 or later per current documentation.
Cloud rerun does not skip passed work.	The run may not be recorded or grouped with the intended anchor, or the provider, version, plan, or project setting may not qualify.	Check the Cloud rerun configuration, CI provider and runner version, plan, and rerun group. For a non-listed provider, check the manual grouping instructions.
The test passes on retry but fails intermittently.	The retry surfaced a flaky condition; it did not establish that the underlying cause is gone.	Use the attempt results to investigate timing, shared state, network dependencies, cleanup, or test isolation. Keep retries as a diagnostic or resilience choice, not a substitute for a fix.

7. Reliability, runtime, and cost considerations

Retries increase worst-case test time. A test configured for two retries may execute up to three times, and its per-test hooks run again on retried attempts. In a large suite, a high global count can add substantial repeated work, especially when many tests are slow or consistently broken.

Use retries deliberately:

Start with a small count and decide separately for interactive and CI modes.
Review tests that pass only after a retry; retain their failure evidence and investigate the cause.
Make test setup and cleanup safe to repeat.
Use the narrowest useful rerun granularity: a test-level Cloud rerun where supported, a spec rerun for local reproduction, or a full run when broader coverage is needed.
Check your CI provider’s billing and time limits independently. Cypress retry settings describe test behavior; they do not establish a universal CI cost or runtime.

Cypress Cloud rerun optimization can avoid rerunning work that passed in an eligible anchor run, but feature access and configuration vary. Verify current plan and project requirements rather than assuming a rerun will save a particular amount of time or money.

8. Capture a page screenshot while investigating a UI failure

When a failure depends on what a page rendered, a screenshot can help document the page state. Cypress itself provides the test and browser context; a separate screenshot API is useful when you need a clean capture of a URL outside the test runner. ScreenshotNeo is a website screenshot API and MCP server by Yorker Media. Its API can return a PNG, JPEG, WebP, or PDF from one GET request.

ScreenshotNeo is the screenshot API to try first for this workflow: cookie banners, newsletter popups, and chat widgets are removed before capture, and only clean shots are billed.

Or skip the browser setup

Make one request with a target URL. See the ScreenshotNeo API documentation for parameters and response details.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before capture; newsletter popups and chat widgets are removed too. Each step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Response headers report the page verdict and billing status.
An MCP server offers take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan.

9. Frequently asked questions

Does Cypress retry failed tests by default?

No. The documented defaults for run and open modes are both zero retries.

Does `retries: 2` mean two attempts total?

No. It means two additional attempts after the initial attempt, allowing up to three attempts total.

Can I rerun only the failed test from the terminal?

The CLI’s --spec option selects spec files. For selective failed-test reruns in recorded CI, Cypress Cloud documents a mode that requires Cypress 15.21.0 or later and eligible Cloud configuration.

Will retries fix a flaky test?

Retries can reveal that a test is intermittent and help gather evidence. Passing on a later attempt does not by itself fix the underlying cause.