Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags

Update 08/25/20:

Test retries has made it to Cypress core! Please upgrade to 5.0.0 and remove this plugin

Migrating from cypress-plugin-retries to Cypress 5.0.0:

See the 5.0 migration guide

  • remove cypress-plugin-retries from devDependencies and related code in support/plugin files
  • To enable retries on single test/suite, remove usage of Cypress.currentTest in favor of test config overrides e.g.:
// on a single test
it('test title', { retries: 2 }, () => {

// or on a suite
describe('suite title', { retries: 2 }, () => {
  • To enable retries globally, set retries in cypress.json instead of using Cypress.env('RETRIES') e.g.:
  "retries": { "openMode": 0, "runMode": 2 }
  • remove usage of this.retries(n) (not supported)


A Cypress plugin to retry failed tests

Please report bugs in the issues of this repo.


Add the plugin to devDependencies

npm install -D cypress-plugin-retries

At the top of cypress/support/index.js:


Optional Installation

To enable retry logging in the terminal alongside mocha output
Inside cypress/plugins/index.js:

module.exports = (on, config) => {

example output:


Use the environment variable CYPRESS_RETRIES to set the retry number for all spec files:

CYPRESS_RETRIES=2 npm run cypress

or Set the "env" key in your cypress.json configuration file to set the retry number for all spec files:

    "RETRIES": 2

or On a per-test or per-hook basis, set the retry number:

Note: this plugin adds Cypress.currentTest and you should only access it in the context of this plugin.

it('test', () => {

or [undesirable] Use mocha's this.retries(n) inside of a test:

Note: must use function() notation, not arrows ()=>{}

it('test', function() {


Conditional Logic based on currentRetry number?
add a wait before the next retry?

How it works

  • a test with retries enabled will immediately retry on failure instead of moving on to the next test.
  • tests only retry on failure. If all your tests pass on the first try, it's as if you didn't have this plugin.
  • during a retry, all beforeEach and afterEach hooks that apply the test will be re-ran
  • beforeAll(before) hooks are not re-ran on retry. These are guaranteeed only to be ran once.
  • if a test fails in a beforeEach hook, the test will retry
  • if a test fails in a afterEach/afterAll hook, the test will not retry, but fail as normal (if you want to retry an afterEach hook, see this issue)
  • only the final run of a test will be sent to the mocha reporter/Dashboard. This means if a test passes on the second retry, you'll see one passing test.
  • a screenshot is taken on each test retry. This can be configured as detailed here:
  • commands from past test tries will be faded out, as shown in the screenshot above

Extra Configuration

  • Use env var RETRIES_HIDDEN=1 to hide previous attempts' command log entries (instead of marking them with an orange x)
  • Use env var RETRIES_NO_LOG=1 to omit logging to terminal in Cypress run mode ((retry 1/3) ...)