cypress-plugin-last-failed 1.0.0

package/.github/workflows/main.yml

@@ -0,0 +1,28 @@
+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
+        continue-on-error: true
+      - name: Output the file contents 📝
+        if: always()
+        run: |
+          cat ./test-results/last-run.txt
+      - name: Custom tests 🧪
+        if: always()
+        uses: cypress-io/github-action@v6
+        with:
+          # environment variable used for CI/CD tests in this repo
+          command: npx cypress-last-failed run --env shouldPass=true
+          working-directory: ${{ github.workspace }}

package/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Thanks for being willing to contribute!
+
+**Working on your first Pull Request?** You can learn more from [Your First Pull Request on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
+
+## Project setup
+
+1. Fork and clone the repo
+2. Run `npm install` to install dependencies
+3. Create a branch for your PR with `git checkout -b pr/your-branch-name`
+
+> Tip: Keep your `main` branch pointing at the original repository and make
+> pull requests from branches on your fork. To do this, run:
+>
+> ```
+> git remote add upstream https://github.com/dennisbergevin/cypress-plugin-last-failed
+> git fetch upstream
+> git branch --set-upstream-to=upstream/main main
+> ```
+>
+> This will add the original repository as a "remote" called "upstream," Then
+> fetch the git information from that remote, then set your local `main`
+> branch to use the upstream main branch whenever you run `git pull`. Then you
+> can make all of your pull request branches based on this `main` branch.
+> Whenever you want to update your version of `main`, do a regular `git pull`.
+
+## Committing and Pushing changes
+
+Please make sure to run the node script before you commit your changes:
+
+```bash
+npx cypress-last-failed run
+```
+
+For changes related to the `cypress open` toggle, you can run `npx cypress open` to test functionality in the Cypress Test Runner UI. Make sure to include any test changes (if they exist) in your commit.
+
+## Help needed
+
+Please checkout the [the open issues](https://github.com/dennisbergevin/cypress-plugin-last-failed/issues)
+
+Also, please watch the repo and respond to questions/bug reports/feature
+requests! Thanks!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, Dennis Bergevin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+<h2 align=center>Cypress plugin last-failed</h2>
+<p align="center">
+</p>
+
+<p align="center">
+A companion Cypress plugin for <code>cy-grep</code> that re-runs the last failed test(s).
+</p>
+
+![Cypress-last-failed-toggle](./assets/cypress-demo.gif)
+
+![Cypress run example image](./assets/cypress-last-failed.png)
+
+## Features
+
+- 👟 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
+
+#### Table of Contents
+
+- [Installation](#-installation)
+- [Run mode](#-run-mode)
+  - [Optional custom `failedTestDirectory`](#optional-custom-failedtestdirectory)
+  - [Add rule to gitignore](#add-rule-to-gitignore)
+  - [Setting up a `npm` script](#-setting-up-a-npm-script)
+- [Open mode](#-open-mode)
+  - [Recommended open mode env variables](#recommended-open-mode-env-variables)
+- [CI support](#continuous-integration-support)
+- [Typescript support](#typescript-support)
+- [Contributions](#contributions)
+
+---
+
+## 📦 Installation
+
+1. Install the following packages:
+
+```sh
+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),
+
+```js
+import { failedTestToggle } from 'cypress-plugin-last-failed';
+
+const registerCypressGrep = require('@bahmutov/cy-grep');
+registerCypressGrep();
+
+failedTestToggle();
+```
+
+3. In `cypress.config`, include the following within `setupNodeEvents` for `e2e` and/or `component` testing:
+
+```js
+module.exports = defineConfig({
+  screenshotOnRunFailure: false,
+  env: {
+    failedTestDirectory: './',
+    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;
+    },
+  },
+});
+```
+
+---
+
+## 👟 Run mode
+
+1. Run tests using `cypress run`:
+
+```bash
+# Example
+npx cypress run
+```
+
+2. If there are failed tests, run the following command from the **directory of the project's `cypress.config`**:
+
+```bash
+npx cypress-last-failed run
+```
+
+You can also include more cli arguments similar to `cypress run`, as the command harnesses the power of [Cypress module API](https://docs.cypress.io/guides/guides/module-api):
+
+```bash
+# Example
+npx cypress-last-failed run --e2e --browser chrome
+```
+
+### Optional custom `failedTestDirectory`
+
+By default, there will be a folder called `test-results` created in the directory of the `cypress.config`.
+
+- To customize where the `test-results` folder should be stored, add the `failedTestDirectory` environment variable:
+
+```js
+// Example using a fixtures folder path relative to the cypress.config
+
+module.exports = defineConfig({
+  env: {
+    failedTestDirectory: './cypress/fixtures',
+  },
+  e2e: {
+    setupNodeEvents(on, config) {},
+  },
+});
+```
+
+### Add rule to gitignore
+
+- **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
+
+```
+
+### 📃 Setting up a `npm` script
+
+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:
+
+```json
+  "scripts": {
+    "last-failed": "npx cypress-run-last-failed run --e2e --browser electron"
+  }
+```
+
+## ⌛ Open mode
+
+Toggling the filter will run any previously failed tests on the particular spec file.
+
+![Failed test toggle](./assets/failed-test-toggle.png)
+
+### Recommended open mode env variables
+
+- **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`:
+
+```json
+{
+  "env": {
+    "grepOmitFiltered": true,
+    "grepFilterSpecs": true
+  }
+}
+```
+
+> [!NOTE]
+> More information on `grepOmitFiltered` and `grepFilterSpecs` can be read within the [README for `@bahmutov/cy-grep`](https://github.com/bahmutov/cy-grep?tab=readme-ov-file#pre-filter-specs-grepfilterspecs).
+
+---
+
+## Continuous integration support
+
+An example of utilizing the plugin to re-run only the failed tests from a previous step in CI:
+
+```yaml
+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.txt
+      - name: Custom tests 🧪
+        if: always()
+        uses: cypress-io/github-action@v6
+        with:
+          command: npx cypress-last-failed run
+          working-directory: ${{ github.workspace }}
+```
+
+## Typescript support
+
+For more information on Typescript support involved with `@bahmutov/cy-grep` package, refer to it's [README](https://github.com/bahmutov/cy-grep?tab=readme-ov-file#typescript-support).
+
+## Contributions
+
+Feel free to open a pull request or drop any feature request or bug in the [issues](https://github.com/dennisbergevin/cypress-plugin-last-failed/issues).
+
+Please see more details in the [contributing doc](./CONTRIBUTING.md).

package/cypress/e2e/tests.cy.js

@@ -0,0 +1,26 @@
+describe('Should run expected tests', () => {
+  it('should run', () => {
+    if (Cypress.env('shouldPass')) {
+      expect(true).to.eq(true);
+    } else {
+      expect(true).to.eq(false);
+    }
+  });
+  it('should not run', () => {
+    expect(true).to.eq(true);
+  });
+  it('needs to run', () => {
+    if (Cypress.env('shouldPass')) {
+      expect(1).to.eq(1);
+    } else {
+      expect(1).to.eq(2);
+    }
+  });
+  it('will be included in failed tests', () => {
+    if (Cypress.env('shouldPass')) {
+      expect(10).to.eq(10);
+    } else {
+      expect(10).to.eq(2);
+    }
+  });
+});

package/cypress/fixtures/example.json

@@ -0,0 +1,5 @@
+{
+  "name": "Using fixtures to represent data",
+  "email": "hello@cypress.io",
+  "body": "Fixtures are a great way to mock data for responses to routes"
+}

package/cypress/support/commands.js

@@ -0,0 +1,25 @@
+// ***********************************************
+// This example commands.js shows you how to
+// create various custom commands and overwrite
+// existing commands.
+//
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add('login', (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... })

package/cypress/support/e2e.js

@@ -0,0 +1,28 @@
+// ***********************************************************
+// This example support/e2e.js is processed and
+// loaded automatically before your test files.
+//
+// This is a great place to put global configuration and
+// behavior that modifies Cypress.
+//
+// You can change the location of this file or turn off
+// automatically serving support files with the
+// 'supportFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/configuration
+// ***********************************************************
+
+// Import commands.js using ES2015 syntax:
+import { failedTestToggle } from '../../src';
+import './commands';
+
+failedTestToggle();
+
+// load and register the grep feature using "require" function
+// https://github.com/cypress-io/cypress/tree/develop/npm/grep
+const registerCypressGrep = require('@bahmutov/cy-grep');
+registerCypressGrep();
+
+// Alternatively you can use CommonJS syntax:
+// require('./commands')

package/cypress.config.js

@@ -0,0 +1,27 @@
+const { defineConfig } = require('cypress');
+const { collectFailingTests } = require('./src/index');
+
+module.exports = defineConfig({
+  env: {
+    failedTestDirectory: './',
+    grepOmitFiltered: true,
+    grepFilterSpecs: true,
+  },
+  screenshotOnRunFailure: false,
+  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;
+    },
+  },
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "cypress-plugin-last-failed",
+  "version": "1.0.0",
+  "description": "Cypress plugin to rerun last failed tests in cypress run and open mode",
+  "main": "./src/index.js",
+  "scripts": {
+    "last-failed": "node runFailed.js run --e2e --browser electron"
+  },
+  "bin": {
+    "cypress-last-failed": "runFailed.js"
+  },
+  "keywords": [
+    "cypress",
+    "testing",
+    "cypress-plugin"
+  ],
+  "devDependencies": {
+    "@bahmutov/cy-grep": "^1.9.17",
+    "cypress": "^13.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "Dennis Bergevin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dennisbergevin/cypress-plugin-last-failed.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dennisbergevin/cypress-plugin-last-failed/issues"
+  },
+  "homepage": "https://github.com/dennisbergevin/cypress-plugin-last-failed#readme"
+}

package/runFailed.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+const cypress = require('cypress');
+const fs = require('fs');
+const path = require('path');
+const appDir = process.env.INIT_CWD ? process.env.INIT_CWD : path.resolve('.');
+const cypressConfig = require(`${appDir}/cypress.config`);
+
+async function runLastFailed() {
+  const noFailedTestsMessage =
+    'No previous failed tests detected\nTry running tests again with cypress run';
+
+  // Use the cypress environment variable failedTestDirectory for where to store failed tests
+  // If not set then use the directory of the project's cypress.config where the test-results defaults to
+  const failedTestFilePath =
+    cypressConfig.env?.failedTestDirectory === undefined
+      ? `${appDir}/test-results/last-run.txt`
+      : `${cypressConfig.env.failedTestDirectory}/test-results/last-run.txt`;
+
+  if (fs.existsSync(failedTestFilePath)) {
+    // Retrieve the failedTests from the file
+    const failedTests = await fs.promises.readFile(failedTestFilePath, 'utf8');
+
+    if (failedTests.length > 0) {
+      // Allow for additional cli arguments to be passed to the run command
+      const runOptions = await cypress.cli.parseRunArguments(
+        process.argv.slice(2)
+      );
+
+      // Set cypress environment variables needed for running last failed tests
+      process.env.CYPRESS_grep = `${failedTests}`;
+      process.env.CYPRESS_grepFilterSpecs = true;
+      process.env.CYPRESS_grepOmitFiltered = true;
+
+      await cypress.run(runOptions);
+    } else {
+      console.log(noFailedTestsMessage);
+    }
+  } else {
+    console.log(noFailedTestsMessage);
+  }
+}
+
+runLastFailed();

package/src/index.js

@@ -0,0 +1,198 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Collects failed tests from the most recent Cypress test run
+ *
+ * After each run, a file will store failed test titles within a test-results directory
+ *
+ * Environment variable `failedTestDirectory` can be used to set a specific directory to store test-results
+ *
+ * If failedTestDirectory env var is unset, test-results will be stored in cypress.config directory
+ *
+ * Subsequent test runs containing failed tests will overwrite this file
+ * @param {*} on
+ * @param {*} config
+ * @returns
+ */
+
+const collectFailingTests = (on, config) => {
+  // Check for environment variable `collectFailingTests` to be true
+  on('after:run', async (results) => {
+    let failedTests = [];
+    // Grab every failed test's title
+    for (i in results.runs) {
+      const tests = results.runs[i].tests
+        .filter((test) => test.state === 'failed')
+        .map((test) => test.title[test.title.length - 1]);
+
+      // Only store non empty test titles
+      if (tests != '') {
+        failedTests.push(tests);
+      }
+    }
+
+    const stringedTests = failedTests.toString();
+    // Prepare a string that can be read from cy-grep
+    const greppedTestFormat = stringedTests.replaceAll(',', '; ');
+
+    // Use the cypress.config environment variable for failedTestDirectory
+    // If not set then use the cypress.config directory
+    const failedTestFileDirectory =
+      config.env.failedTestDirectory === undefined
+        ? `${path.dirname(config.configFile)}/test-results/`
+        : `${config.env.failedTestDirectory}/test-results/`;
+
+    await fs.promises.mkdir(`${failedTestFileDirectory}`, {
+      recursive: true,
+    });
+    const lastRunReportFile = path.join(
+      `${failedTestFileDirectory}`,
+      'last-run.txt'
+    );
+    await fs.promises.writeFile(lastRunReportFile, greppedTestFormat);
+  });
+
+  return collectFailingTests;
+};
+
+/**
+ * Toggle for use within a spec file during `cypress open`
+ */
+
+const failedTestToggle = () => {
+  const hasStyles = top?.document.querySelector('#runFailedStyle');
+  const hasToggleButton = top?.document.querySelector('#runFailedToggle');
+  const defaultStyles = `
+      .reporter header {
+        overflow: visible;
+        z-index: 2;
+      }
+      #runFailedControls {
+        position: relative;
+        display: inline-block;
+      }
+      #runFailedToggle {
+        display: none;
+      }
+      #runFailedControls label {
+        background-color: transparent;
+        padding-top: 5px;
+      }
+      #runFailedControls #runFailedTooltip {
+        visibility: hidden;
+        width: 134px;
+        background-color: #f3f4fa;
+        color: #1b1e2e;
+        text-align: center;
+        padding: 5px;
+        border-radius: 3px;
+        position: absolute;
+        z-index: 1;
+        top: 27px;
+        left: 0px;
+        height: 28px;
+      }
+      #runFailedControls:hover #runFailedTooltip {
+        visibility: visible;
+      }
+      #runFailedButton #runFailedLabel {
+        cursor: pointer;
+      }
+      #runFailedTooltip::after {
+        content: " ";
+        position: absolute;
+        bottom: 100%;  /* At the top of the tooltip */
+        right: 85%;
+        margin-left: -5px;
+        border-width: 5px;
+        border-style: solid;
+        border-color: transparent transparent #f3f4fa transparent;
+      }
+      .reporter:has(#runFailed:checked) .command.command-name-request:has(.command-is-event) {
+        display:none
+      }
+      `;
+  const turnOffRunFailedIcon = `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#f59aa9" class="bi bi-filter-circle" viewBox="0 0 16 16">
+    <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14m0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16"/>
+    <path d="M7 11.5a.5.5 0 0 1 .5-.5h1a.5.5 0 0 1 0 1h-1a.5.5 0 0 1-.5-.5m-2-3a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5m-2-3a.5.5 0 0 1 .5-.5h9a.5.5 0 0 1 0 1h-9a.5.5 0 0 1-.5-.5"/>
+  </svg>`;
+
+  const turnOnRunFailedIcon = `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#f59aa9" class="bi bi-filter-circle-fill" viewBox="0 0 16 16">
+    <path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16M3.5 5h9a.5.5 0 0 1 0 1h-9a.5.5 0 0 1 0-1M5 8.5a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5m2 3a.5.5 0 0 1 .5-.5h1a.5.5 0 0 1 0 1h-1a.5.5 0 0 1-.5-.5"/>
+  </svg>`;
+
+  const turnOffRunFailedDescription = 'Filter failed tests';
+  const turnOnRunFailedDescription = 'Unfilter failed tests';
+
+  // append styles
+  if (!hasStyles) {
+    const reporterEl = top?.document.querySelector('#unified-reporter');
+    const reporterStyleEl = document.createElement('style');
+    reporterStyleEl.setAttribute('id', 'runFailedStyle');
+    reporterStyleEl.innerHTML = defaultStyles;
+    reporterEl?.appendChild(reporterStyleEl);
+  }
+
+  if (!hasToggleButton) {
+    const header = top?.document.querySelector('#unified-reporter header');
+    const headerToggleDiv = document.createElement('div');
+    const headerToggleSpan = document.createElement('span');
+    const headerToggleTooltip = document.createElement('span');
+    const headerToggleButton = document.createElement('button');
+    const headerToggleInput = document.createElement('input');
+    const headerToggleLabel = document.createElement('label');
+
+    headerToggleInput.setAttribute('type', 'checkbox');
+
+    headerToggleInput.setAttribute('id', 'runFailedToggle');
+    headerToggleLabel.setAttribute('for', 'runFailedToggle');
+    headerToggleLabel.setAttribute('id', 'runFailedLabel');
+    headerToggleLabel.innerHTML = turnOffRunFailedIcon;
+
+    headerToggleDiv.setAttribute('class', 'controls');
+    headerToggleDiv.setAttribute('id', 'runFailedControls');
+    headerToggleTooltip.setAttribute('id', 'runFailedTooltip');
+    headerToggleTooltip.innerText = turnOffRunFailedDescription;
+    headerToggleButton.setAttribute('aria-label', turnOffRunFailedDescription);
+    headerToggleButton.setAttribute('id', 'runFailedButton');
+
+    header?.appendChild(headerToggleDiv);
+    headerToggleDiv?.appendChild(headerToggleSpan);
+    headerToggleDiv?.appendChild(headerToggleTooltip);
+    headerToggleSpan?.appendChild(headerToggleButton);
+    headerToggleButton?.appendChild(headerToggleInput);
+    headerToggleButton?.appendChild(headerToggleLabel);
+  }
+
+  const runFailedElement = top.document.querySelector('#runFailedToggle');
+  const runFailedLabelElement = top.document.querySelector(
+    '[for=runFailedToggle]'
+  );
+  const runFailedTooltipElement =
+    top.document.querySelector('#runFailedTooltip');
+
+  runFailedElement?.addEventListener('change', (e) => {
+    const stopBtn = window.top.document.querySelector('.reporter .stop');
+
+    if (e.target.checked) {
+      if (stopBtn) {
+        stopBtn.click();
+      }
+      // when checked, grep only failed tests in spec
+      Cypress.grepFailed();
+      runFailedLabelElement.innerHTML = turnOnRunFailedIcon;
+      runFailedTooltipElement.innerHTML = turnOnRunFailedDescription;
+    } else {
+      if (stopBtn) {
+        stopBtn.click();
+      }
+      // when unchecked, ungrep and show all tests in spec
+      Cypress.grep();
+      runFailedLabelElement.innerHTML = turnOffRunFailedIcon;
+      runFailedTooltipElement.innerHTML = turnOffRunFailedDescription;
+    }
+  });
+};
+
+module.exports = { collectFailingTests, failedTestToggle };