cypress-plugin-filter-runnables 1.0.0

package/.github/workflows/main.yml

@@ -0,0 +1,14 @@
+name: Cypress Tests
+
+on: push
+
+jobs:
+  cypress-run:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      # Install npm dependencies, cache them correctly
+      # and run all Cypress tests
+      - name: Cypress run
+        uses: cypress-io/github-action@v6

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "trailingComma": "es5",
+  "semi": true,
+  "singleQuote": true
+}

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-filter-runnables
+> 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 tests in `open` mode to verify functionality before you commit your changes:
+
+```bash
+npx cypress open
+```
+
+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-filter-runnables/issues)
+
+Also, please watch the repo and respond to questions/bug reports/feature
+requests! Thanks!

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025, 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,69 @@
+<h2 align=center>Cypress plugin filter-runnables</h2>
+<p align="center">
+</p>
+
+<p align="center">
+Cypress plugin that allows user to filter suites/tests in Cypress Test Runner.
+</p>
+
+![cypress-plugin-filter-runnables-demo-1](https://github.com/user-attachments/assets/fc9f3a8a-5de2-4ca1-8b73-2e26bacb3bf6)
+
+
+## Features
+
+- 🔍 A new UI search bar within `cypress open` to filter suites/tests in a given spec
+
+#### Table of Contents
+
+- [Installation](#-installation)
+- [Open mode](#-open-mode)
+  - [Pairing with cypress-plugin-grep-boxes](#pairing-with-cypress-plugin-grep-boxes)
+- [Contributions](#contributions)
+
+---
+
+## 📦 Installation
+
+1. Install the following packages:
+
+```sh
+npm install --save-dev cypress-plugin-filter-runnables
+```
+
+2. In `cypress/support/e2e.js` (For E2E tests) and/or `cypress/support/component.js` (For Component tests),
+
+```js
+import 'cypress-plugin-filter-runnables';
+```
+
+---
+
+## 🔍 Open mode
+
+Run `npx cypress open` to launch Cypress in `open` mode.
+
+Choose a spec file to run and you will be able to filter by suite/test title at the top of the reporter.
+
+### Pairing with `cypress-plugin-grep-boxes`
+
+The [cypress-plugin-grep-boxes](https://github.com/dennisbergevin/cypress-plugin-grep-boxes) is a great companion for this plugin.
+
+Paired with `cypress-plugin-grep-boxes` (`@bahmutov/cy-grep` is also required), you can filter suites/tests and use the checkboxes to run only selected tests:
+
+![cypress-plugin-filter-runnables-demo-2](https://github.com/user-attachments/assets/59053e87-cbfa-4a49-81a0-6212abc94ba8)
+
+Additionally, you can filter tags when paired with `cypress-plugin-grep-boxes` (version `2.1.0` of `@bahmutov/cy-grep` required):
+
+![filter-runnables-grep-boxes-tags](https://github.com/user-attachments/assets/2c359ddf-cf54-4f48-a34a-b9cae4620acd)
+
+In addition, `cypress-plugin-grep-boxes` supports a [disableInitialAutoRun feature](https://github.com/dennisbergevin/cypress-plugin-grep-boxes/blob/main/README.md#disableinitialautorun) that will prevent Cypress Test Runner from automatically running available tests once a spec file is open.
+
+This gives you a moment to filter down to whichever tests to select before running them:
+
+![cypress-plugin-filter-runnables-demo-3](https://github.com/user-attachments/assets/e10262db-7f88-4852-9cc8-1b4626e13f45)
+
+## Contributions
+
+Feel free to open a pull request or drop any feature request or bug in the [issues](https://github.com/dennisbergevin/cypress-plugin-filter-runnables/issues).
+
+Please see more details in the [contributing doc](./CONTRIBUTING.md).

package/cypress/e2e/1-getting-started/todo.cy.js

@@ -0,0 +1,143 @@
+/// <reference types="cypress" />
+
+// Welcome to Cypress!
+//
+// This spec file contains a variety of sample tests
+// for a todo list app that are designed to demonstrate
+// the power of writing tests in Cypress.
+//
+// To learn more about how Cypress works and
+// what makes it such an awesome testing tool,
+// please read our getting started guide:
+// https://on.cypress.io/introduction-to-cypress
+
+describe('example to-do app', () => {
+  beforeEach(() => {
+    // Cypress starts out with a blank slate for each test
+    // so we must tell it to visit our website with the `cy.visit()` command.
+    // Since we want to visit the same URL at the start of all our tests,
+    // we include it in our beforeEach function so that it runs before each test
+    cy.visit('https://example.cypress.io/todo');
+  });
+
+  it('displays two todo items by default', { tags: '@smoke' }, () => {
+    // We use the `cy.get()` command to get all elements that match the selector.
+    // Then, we use `should` to assert that there are two matched items,
+    // which are the two default items.
+    cy.get('.todo-list li').should('have.length', 2);
+
+    // We can go even further and check that the default todos each contain
+    // the correct text. We use the `first` and `last` functions
+    // to get just the first and last matched elements individually,
+    // and then perform an assertion with `should`.
+    cy.get('.todo-list li').first().should('have.text', 'Pay electric bill');
+    cy.get('.todo-list li').last().should('have.text', 'Walk the dog');
+  });
+
+  it('can add new todo items', () => {
+    // We'll store our item text in a variable so we can reuse it
+    const newItem = 'Feed the cat';
+
+    // Let's get the input element and use the `type` command to
+    // input our new list item. After typing the content of our item,
+    // we need to type the enter key as well in order to submit the input.
+    // This input has a data-test attribute so we'll use that to select the
+    // element in accordance with best practices:
+    // https://on.cypress.io/selecting-elements
+    cy.get('[data-test=new-todo]').type(`${newItem}{enter}`);
+
+    // Now that we've typed our new item, let's check that it actually was added to the list.
+    // Since it's the newest item, it should exist as the last element in the list.
+    // In addition, with the two default items, we should have a total of 3 elements in the list.
+    // Since assertions yield the element that was asserted on,
+    // we can chain both of these assertions together into a single statement.
+    cy.get('.todo-list li')
+      .should('have.length', 3)
+      .last()
+      .should('have.text', newItem);
+  });
+
+  it('can check off an item as completed', () => {
+    // In addition to using the `get` command to get an element by selector,
+    // we can also use the `contains` command to get an element by its contents.
+    // However, this will yield the <label>, which is lowest-level element that contains the text.
+    // In order to check the item, we'll find the <input> element for this <label>
+    // by traversing up the dom to the parent element. From there, we can `find`
+    // the child checkbox <input> element and use the `check` command to check it.
+    cy.contains('Pay electric bill')
+      .parent()
+      .find('input[type=checkbox]')
+      .check();
+
+    // Now that we've checked the button, we can go ahead and make sure
+    // that the list element is now marked as completed.
+    // Again we'll use `contains` to find the <label> element and then use the `parents` command
+    // to traverse multiple levels up the dom until we find the corresponding <li> element.
+    // Once we get that element, we can assert that it has the completed class.
+    cy.contains('Pay electric bill')
+      .parents('li')
+      .should('have.class', 'completed');
+  });
+
+  context('with a checked task', () => {
+    beforeEach(() => {
+      // We'll take the command we used above to check off an element
+      // Since we want to perform multiple tests that start with checking
+      // one element, we put it in the beforeEach hook
+      // so that it runs at the start of every test.
+      cy.contains('Pay electric bill')
+        .parent()
+        .find('input[type=checkbox]')
+        .check();
+    });
+
+    it('can filter for uncompleted tasks', () => {
+      // We'll click on the "active" button in order to
+      // display only incomplete items
+      cy.contains('Active').click();
+
+      // After filtering, we can assert that there is only the one
+      // incomplete item in the list.
+      cy.get('.todo-list li')
+        .should('have.length', 1)
+        .first()
+        .should('have.text', 'Walk the dog');
+
+      // For good measure, let's also assert that the task we checked off
+      // does not exist on the page.
+      cy.contains('Pay electric bill').should('not.exist');
+    });
+
+    it('can filter for completed tasks', () => {
+      // We can perform similar steps as the test above to ensure
+      // that only completed tasks are shown
+      cy.contains('Completed').click();
+
+      cy.get('.todo-list li')
+        .should('have.length', 1)
+        .first()
+        .should('have.text', 'Pay electric bill');
+
+      cy.contains('Walk the dog').should('not.exist');
+    });
+
+    it('can delete all completed tasks', () => {
+      // First, let's click the "Clear completed" button
+      // `contains` is actually serving two purposes here.
+      // First, it's ensuring that the button exists within the dom.
+      // This button only appears when at least one task is checked
+      // so this command is implicitly verifying that it does exist.
+      // Second, it selects the button so we can click it.
+      cy.contains('Clear completed').click();
+
+      // Then we can make sure that there is only one element
+      // in the list and our element does not exist
+      cy.get('.todo-list li')
+        .should('have.length', 1)
+        .should('not.have.text', 'Pay electric bill');
+
+      // Finally, make sure that the clear button no longer exists.
+      cy.contains('Clear completed').should('not.exist');
+    });
+  });
+});

package/cypress/e2e/2-advanced-examples/window.cy.js

@@ -0,0 +1,22 @@
+/// <reference types="cypress" />
+
+context('Window', () => {
+  beforeEach(() => {
+    cy.visit('https://example.cypress.io/commands/window')
+  })
+
+  it('cy.window() - get the global window object', () => {
+    // https://on.cypress.io/window
+    cy.window().should('have.property', 'top')
+  })
+
+  it('cy.document() - get the document object', () => {
+    // https://on.cypress.io/document
+    cy.document().should('have.property', 'charset').and('eq', 'UTF-8')
+  })
+
+  it('cy.title() - get the title', () => {
+    // https://on.cypress.io/title
+    cy.title().should('include', 'Kitchen Sink')
+  })
+})

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,19 @@
+// ***********************************************************
+// 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 './commands';
+import '../../index';
+

package/cypress.config.js

@@ -0,0 +1,7 @@
+const { defineConfig } = require('cypress');
+
+module.exports = defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {},
+  },
+});

package/index.js

@@ -0,0 +1,160 @@
+/**
+ * Adds a searchbar to reporter to grep suites and tests.
+ */
+
+if (
+  window.top?.document.querySelectorAll('#test-suite-filter-search').length ===
+  0
+) {
+  const style = document.createElement('style');
+  style.textContent = `
+  #test-suite-filter-search::-webkit-search-decoration,
+  #test-suite-filter-search::-webkit-search-cancel-button,
+  #test-suite-filter-search::-webkit-search-results-button,
+  #test-suite-filter-search::-webkit-search-results-decoration {
+    display: none;
+  }
+  #clear-test-suite-filter-search {
+  background: inherit;
+  color: #d0d2e0 !important;
+}
+  #test-suite-filter-search {
+  background: inherit
+}
+`;
+
+  const specContainer = window.top?.document.querySelector('.spec-container');
+  const runnableHeader = window.top?.document.querySelector('.runnable-header');
+
+  window.top?.document.head.appendChild(style);
+  const parentEl = Cypress.version >= '15.0.0' ? specContainer : runnableHeader;
+
+  parentEl.insertAdjacentHTML(
+    'beforebegin',
+    `
+<div class="border-b border-gray-800 h-[64px] mx-[16px] auto-cols-max grid grid-flow-col gap-[8px] grid-cols-[minmax(0,1fr)] pointer-cursor items-center">
+<div class="relative flex items-center w-full h-[48px]">
+
+  <!-- 🔍 Search Icon (Left) -->
+  <div class="absolute left-2 top-1/2 -translate-y-1/2 flex items-center justify-center pointer-events-none">
+    <svg
+      id="search-icon-test-suite-filter"
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      class="icon-dark-gray-800 icon-light-gray-1000"
+      style="min-width: 16px; min-height: 16px;">
+      <path
+        d="M12 7C12 8.38071 11.4404 9.63071 10.5355 10.5355C9.63071 11.4404 8.38071 12 7 12C4.23858 12 2 9.76142 2 7C2 4.23858 4.23858 2 7 2C9.76142 2 12 4.23858 12 7Z"
+        class="icon-light"
+        fill="none" />
+      <path
+        d="M10.5355 10.5355L14 14M10.5355 10.5355C11.4404 9.63071 12 8.38071 12 7C12 4.23858 9.76142 2 7 2C4.23858 2 2 4.23858 2 7C2 9.76142 4.23858 12 7 12C8.38071 12 9.63071 11.4404 10.5355 10.5355Z"
+        class="icon-dark"
+        stroke="#1B1E2E"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round" />
+    </svg>
+  </div>
+
+  <!-- 🏷 Label (Visually Hidden for a11y) -->
+  <label
+    for="test-suite-filter-search"
+    class="cursor-text font-light bottom-[4px] left-[24px] text-gray-500 pointer-events-none absolute sr-only">
+    Filter suites/tests
+  </label>
+
+  <!-- 🔤 Input -->
+  <input
+    id="test-suite-filter-search"
+    type="search"
+    aria-label="filter search for suites and tests"
+    class="pl-8 pr-8 py-3 w-full font-bold text-lg outline-none bg-gray-1100 border-0 placeholder-gray-700 text-white-1500 rounded-md"
+    placeholder="Filter suites/tests"
+    autocapitalize="off"
+    autocomplete="off"
+    spellcheck="false"
+  />
+
+  <!-- ❌ Clear Button (Right) -->
+  <button
+    type="button"
+    id="clear-test-suite-filter-search"
+    aria-label="Clear search field"
+    class="border-transparent rounded-md flex outline-none h-[30px] my-[4px] inset-y-0 right-0 w-[24px] duration-300 absolute items-center justify-center group hocus-default hocus:ring-0">
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      class="icon-light-gray-1000 group-hocus:icon-dark-indigo-300 icon-dark-gray-800"
+      style="min-width: 16px; min-height: 16px;">
+      <path
+        d="M3 13L13 3M3 3L13 13"
+        class="icon-dark"
+        stroke="#1B1E2E"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round" />
+    </svg>
+  </button>
+
+</div>
+</div>  `
+  );
+}
+
+const searchInput = window.top?.document.querySelector(
+  '#test-suite-filter-search'
+);
+const clearBtn = window.top?.document.querySelector(
+  '#clear-test-suite-filter-search'
+);
+
+searchInput?.addEventListener('focus', function () {
+  window.top?.document
+    .querySelector('#search-icon-test-suite-filter')
+    .setAttribute('class', 'icon-dark-indigo-300 icon-light-grey-1700');
+});
+
+searchInput?.addEventListener('focusout', function () {
+  window.top?.document
+    .querySelector('#search-icon-test-suite-filter')
+    .setAttribute('class', 'icon-dark-gray-800 icon-light-gray-1000');
+});
+
+clearBtn?.addEventListener('click', function () {
+  searchInput.value = '';
+  searchInput.focus();
+  searchInput.dispatchEvent(new Event('input', { bubbles: true }));
+});
+
+searchInput?.addEventListener('input', (event) => {
+  const searchTerm = event.target.value.toLowerCase();
+  const testsAndSuites = window.top?.document.querySelectorAll(
+    '.test.runnable, .suite.runnable'
+  );
+
+  for (let i = 0; i < testsAndSuites.length; i++) {
+    const itemText = testsAndSuites[i].textContent.toLowerCase();
+
+    if (itemText.includes(searchTerm)) {
+      testsAndSuites[i].style.display = '';
+    } else {
+      const closestSuiteText = testsAndSuites[i]
+        .closest('.suite.runnable')
+        .innerText.split('\n')[0]
+        .toLowerCase();
+      if (closestSuiteText.includes(searchTerm)) {
+        testsAndSuites[i].style.display = '';
+      } else {
+        testsAndSuites[i].click;
+        testsAndSuites[i].style.display = 'none';
+      }
+    }
+  }
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "cypress-plugin-filter-runnables",
+  "version": "1.0.0",
+  "description": "Cypress plugin that allows user to filter suites/tests in Cypress Test Runner.",
+  "main": "./index.js",
+  "keywords": [
+    "cypress",
+    "testing",
+    "cypress-plugin"
+  ],
+  "devDependencies": {
+    "cypress": "^15.5.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "Dennis Bergevin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dennisbergevin/cypress-plugin-filter-runnables.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dennisbergevin/cypress-plugin-filter-runnables/issues"
+  },
+  "homepage": "https://github.com/dennisbergevin/cypress-plugin-filter-runnables#readme"
+}