🚀 Enhancing Cypress Test Stability and Retry Capabilities

Introduction

The cypress-retry-after-run plugin brings a smart way to rerun only the tests that failed in a previous Cypress run, saving pipeline time, infrastructure resources, and frustration when dealing with flaky tests. It was designed mainly for real-world teams that run large suites in CI/CD and do not want to pay the price of re-executing the entire test set just because a handful of tests were unstable.

The problem this plugin solves

In modern QA pipelines, it is very common to have:

• Large suites that take minutes (or hours) to run and consume a lot of CI resources.
• Intermittent tests (flaky tests) that fail occasionally due to environment instability, networking, data issues, and so on.
• A real need to isolate and rerun only what failed, instead of running everything again manually or rerun on demand, as the data can be corrupted at runtime.

Native Cypress retries will retry the test within the same execution, but that is not always what you want. In many pipelines, you first want to run the full suite, then do something (deploy fresh data, restart a service, clean up the environment), and only then trigger a new execution focused exclusively on the failures.

Core idea of cypress-retry-after-run

The plugin implements a two-step flow:

• During the normal run, it listens to test execution and records failed tests into a .cypress-failures.json file at the project root.
• Then you trigger a CLI command (cypress-retry) that reads this file, uses @cypress/grep under the hood, and starts a new Cypress run that executes only the tests that failed before.

In practice, the plugin turns “Run once, record failures, and rerun only what matters”.

Concrete benefits for CI/CD

For CI/CD pipelines, cypress-retry-after-run delivers very tangible advantages:

• Time savings: instead of running the entire suite twice, the second run usually will be much smaller and focused only on the failed specs/cases.
• Lower infrastructure cost: fewer runner minutes, fewer containers, less CPU and memory usage on shared environments.
• More focused feedback: you quickly get a clean “retry run” that shows only the behavior of the failed tests, which helps distinguish real bugs from pure flakiness (either due to the tests or due to the environment, bad data, or other things), so it will make your debugging much faster, specially in larger suites as mentioned.

This pattern is especially useful for:

• Pipelines that run multiple times a day.
• Monorepos with dozens or hundreds of specs (which was my case, by the way).
• Quality gates that only block merges if failures persist even after a dedicated retry run.

How the plugin works under the hood

The internal logic is simple but powerful:

• Execution hook: the plugin plugs into Cypress via setupNodeEvents and listens to information about failed tests as the run progresses.
• Persistence: at the end of the run, it writes a .cypress-failures.json file with identifiers of the tests/specs that failed.
• Smart CLI: the cypress-retry command reads this file, builds the proper filters, and starts a new Cypress execution using @cypress/grep to run only the relevant tests.

Effectively, you get a selective replay of the failing tests, fully automated and integrated into your normal Cypress workflow.

Easy installation

Installation follows the standard pattern for modern Cypress plugins, with no extra friction.

• With npm:
  • npm install --save-dev cypress-retry-after-run @cypress/grep.
• With yarn:
  • yarn add -D cypress-retry-after-run @cypress/grep.

The only additional requirement is @cypress/grep, which the plugin uses to filter tests on the retry run, so it is installed alongside the plugin in a single command.

JavaScript and Typescript configuration

This plugin can be used in both JS and TS projects. Refer to the plugin's official npm link to get the full instructions on how to set it up and how to run it:

• https://www.npmjs.com/package/cypress-retry-after-run

Pipeline and automation integration

cypress-retry-after-run fits naturally into any CI/CD pipeline design.

• Step 1 – Main run:

  • A standard job that runs the full suite (if you want) and generates .cypress-failures.json if there are failures.

• Step 2 (Optional) – Do anything, like cleaning a database, or any operation in the environment you want, if necessary.

• Step 3 – Automated retry:

  • A second job/step that executes npm run retry (or an equivalent command you created) only if the failures file exists and/or if the previous job failed.

This design enables:

• Conditional pipelines (retry only if there were actual failures).
• Richer monitoring (separate dashboards for the full run and the retry run).
• Smarter alerting (a test that still fails even after a dedicated retry can trigger a stronger alert or block a merge).

Why this plugin stands out

A few things make cypress-retry-after-run stand out in the Cypress ecosystem:

• Built from real QA pain points: the “run everything, fix the environment, then rerun only failures” flow comes directly from production CI/CD needs.
• Native integration with @cypress/grep: instead of reinventing filtering, it relies on a widely used community library, staying aligned with the Cypress ecosystem.
• Minimal configuration: just a few lines in cypress.config and in the support file are enough to adopt it in both new and legacy projects.
• Lightweight and focused: small package, no unnecessary dependencies, easy to drop into any repository without bloating your project.

For teams that already care deeply about automation quality and are tired of flakiness and wasted CI resources, cypress-retry-after-run is a strong ally to make pipelines more efficient, predictable, and truly professional.

You can check both links below with the plugin and a LinkedIn post with everything here, but summarized:

• Npm Official plugin page
• Linkedin post