A companion Cypress plugin for cy-grep that re-runs the last failed test(s).

• 👟 A new cypress run command to only run the previous run's failed tests
• ⏳ A new UI toggle within cypress open to filter and only run any failed tests in a given spec
• 🤖 CI/CD support

• Features
  • Table of Contents
• 📦 Installation
• 👟 Run mode
  • Specify a custom test-results directory
  • Add rule to gitignore
  • 📃 Setting up a npm script
• ⌛ Open mode
  • Recommended open mode env variables
  • Use Required Test Tags Instead Of Skipping Tests
• Continuous integration support
• Typescript support
• Contributions

1. Install the following packages:

npm install --save-dev @bahmutov/cy-grep # Dependent package for the plugin
npm install --save-dev cypress-plugin-last-failed

2. In cypress/support/e2e.js (For E2E tests) and/or cypress/support/component.js (For Component tests),

import failedTestToggle from 'cypress-plugin-last-failed/src/toggle';

const registerCypressGrep = require('@bahmutov/cy-grep');
registerCypressGrep();

failedTestToggle();

3. In cypress.config, include the following within setupNodeEvents for e2e and/or component testing:

const { defineConfig } = require('cypress');
const { collectFailingTests } = require('cypress-plugin-last-failed');

module.exports = defineConfig({
  screenshotOnRunFailure: false,
  env: {
    grepOmitFiltered: true,
    grepFilterSpecs: true,
  },
  e2e: {
    setupNodeEvents(on, config) {
      collectFailingTests(on, config);

      require('@bahmutov/cy-grep/src/plugin')(config);
      return config;
    },
  },
  component: {
    setupNodeEvents(on, config) {
      collectFailingTests(on, config);

      require('@bahmutov/cy-grep/src/plugin')(config);
      return config;
    },
  },
});

1. Run tests using cypress run:

# Example
npx cypress run

2. If there are failed tests, run the following command from the directory of the project's cypress.config:

npx cypress-plugin-last-failed run

You can also include more cli arguments similar to cypress run, as the command harnesses the power of Cypress module API:

# Example
npx cypress-plugin-last-failed run --e2e --browser chrome

There will be a folder called test-results created in the directory of the cypress.config. If you would like to specify a different folder for test results, use the LAST_FAILED_RESULTS_PATH environment variable:

# Example
LAST_FAILED_RESULTS_PATH=cypress/custom-test-results npx cypress-plugin-last-failed run

This environment variable will direct the plugin to store or retrieve the last run's failed test results from the specified folder.

• Optional: If you do not want to commit the file storing last failed tests to your remote repository, include a rule within your project's .gitignore file:

# Example

**/test-results

For convenience, you may desire to house the npx command within an npm script in your project's package.json, including any desired cli arguments:

  "scripts": {
    "last-failed": "npx cypress-plugin-last-failed run --e2e --browser electron"
  }

Toggling the filter will run any previously failed tests on the particular spec file.

• Recommended: Set two common environment variables tied to the @bahmutov/cy-grep package to enhance the experience utilizing the grep logic within the Cypress Test Runner UI using cypress open:

{
  "env": {
    "grepOmitFiltered": true,
    "grepFilterSpecs": true
  }
}

Normally, any Cypress test or suite of tests marked with a .skip will be shown when running tests or within the Cypress test runner UI.

Since this plugin uses @bahmutov/cy-grep plugin, we can instead designate skipped tests using a required tag:

it('deletes an item', { requiredTags: '@skip' }, () => {
  expect(1).to.equal(2);
});

Now running or opening Cypress in interactive mode, you will not see any tests with requiredTags including @skip (unless setting environment variable grepTags=@skip).

To run just those tests with the required tag @skip in interactive mode:

npx cypress open --env grepTags=@skip

An example of utilizing the plugin to re-run only the failed tests from a previous step in CI:

name: test-last-failed-node-script
on:
  push:
    branches:
      - 'main'
  pull_request:
  workflow_dispatch:

jobs:
  node-script:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout 📦
        uses: actions/checkout@v4
      - name: Cypress run 👟
        uses: cypress-io/github-action@v6
      - name: Output the file contents 📝
        if: always()
        run: |
          cat ./test-results/last-run.json
      - name: Custom tests 🧪
        if: always()
        uses: cypress-io/github-action@v6
        with:
          command: npx cypress-plugin-last-failed run
          working-directory: ${{ github.workspace }}

For more information on Typescript support involved with @bahmutov/cy-grep package, refer to it's README.

Feel free to open a pull request or drop any feature request or bug in the issues.

Please see more details in the contributing doc.