Cypress Test Retries

UI automation is naturally flaky. Even well-written tests may occasionally fail due to timing issues, environment instability, or application state problems.

A test might:

• pass 10 times

• fail once

• pass again on the next run

This creates noise in CI pipelines and can break the expectation of a 100% passing test suite.

Cypress provides a built-in retry mechanism that automatically reruns failed tests before marking them as failed.

Why Retries Exist

Retries help stabilize test reporting when failures are caused by temporary issues such as:

• slow API responses

• rendering delays

• unstable test environments

• network hiccups

• CI machines being slower than local machines

If a retry passes, Cypress marks the test as passed, reducing false failures.

However, retries should not replace proper test design. They are a safety net, not a solution for badly written tests.

Basic Retry Configuration

Retries are configured in cypress.config.js.

Example: retry a failed test up to 3 additional times.

Execution flow:

1. Initial test execution

2. If it fails → retry attempt #1

3. If it fails again → retry attempt #2

4. Continue until retries are exhausted

If any retry passes, the test is marked passed.

Runner Behavior

In Cypress Test Runner you will see:

Each retry also generates separate artifacts such as:

• screenshots

• videos

• logs

This helps debugging flaky tests.

Advanced Retry Configuration

Retries can be configured differently depending on how tests are executed.

Cypress supports two modes:

Mode	Usage
openMode	Interactive test runner (npx cypress open)
runMode	Headless mode (npx cypress run) used in CI

Example configuration:

Explanation:

• openMode: 0 No retries while developing locally. Immediate feedback is preferred.

• runMode: 2 In CI pipelines, Cypress will retry failing tests twice.

This separation makes sense because:

• CI environments are slower

• shared machines introduce instability

• retries reduce false negatives in regression suites

Overriding Retries for Specific Tests

Sometimes a single test is known to be unstable. Instead of increasing retries globally, Cypress allows overriding retry configuration per test.

Example:

This configuration means:

• initial run

• retry #1

• retry #2

Total possible executions: 3 times

Test-level settings override global configuration.

Best Practices for Test Retries

Retries are helpful, but should be used carefully.

Good practices:

• use retries mainly in CI environments

• investigate flaky tests instead of ignoring them

• keep retry counts small (1–2 attempts)

• use test-level overrides instead of increasing retries globally

Retries should improve stability, not hide real problems.

Key Takeaway

Cypress retries provide a simple mechanism to reduce flaky failures in UI automation.

They allow:

• automatic re-execution of failed tests

• different retry strategies for development vs CI

• targeted retries for specific unstable tests

Used correctly, retries can significantly improve the reliability of large Cypress test suites.