README.md

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)

---

cypress-plugin-retries

A Cypress plugin to retry failed tests

Please report bugs in the issues of this repo.

Installation

Add the plugin to devDependencies

npm install -D cypress-plugin-retries

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

require('cypress-plugin-retries')

Optional Installation

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

module.exports = (on, config) => {
  require('cypress-plugin-retries/lib/plugin')(on)
}

example output:

Usage

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:

{
  "env":
  {
    "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', () => {
    Cypress.currentTest.retries(2)
})

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

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

it('test', function() {
    this.retries(2)
})

FAQ

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

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: https://docs.cypress.io/api/commands/screenshot.html#Test-Failures
• 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) ...)

License

MIT