cypress-cli-select 1.0.0

package/.github/workflows/jest.yml

@@ -0,0 +1,12 @@
+name: Jest
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test

package/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# 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-cli-select
+> 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
+
+1. Run Jest tests via the `npm run test` command
+
+2. Run `npx cypress-cli-select run` to inspect behavior before you commit your changes
+
+## Help needed
+
+Please checkout the [the open issues](https://github.com/dennisbergevin/cypress-plugin-cli-select/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,197 @@
+<h2 align=center>Cypress cli-select</h2>
+<p align="center">
+</p>
+
+<p align="center">
+Cypress interactive cli prompts to select and run specs, tests or tags.
+</p>
+
+<img src="./assets/run-spec-title.gif" alt="Cypress-cli-select demo" loop=infinite>
+
+## Features
+
+- ⌨ New interactive CLI prompts to select and run specs, tests or tags
+- 👟 A new `cypress run` command to allow user to pass desired arguments
+
+#### Table of Contents
+
+- [Installation](#installation)
+  - [@bahmutov/cy-grep](#bahmutov-cy-grep)
+  - [@cypress/grep](#cypress-grep-package)
+- [Run mode](#run-mode)
+  - [Keyboard controls](#keyboard-controls)
+- [Test titles or tags](#test-titles-or-tags)
+- [Help mode](#help-mode)
+- [Choose spec pattern](#choose-spec-pattern)
+  - [Keyboard controls](#keyboard-controls)
+- [Print selected](#print-selected)
+- [Submit focused](#submit-focused)
+- [Using a custom cypress config](#using-a-custom-cypress-config)
+- [Setting up a `npm` script](#setting-up-a-npm-script)
+- [Typescript support](#typescript-support)
+- [Contributions](#contributions)
+
+---
+
+## Installation
+
+1. Install the following package:
+
+```sh
+npm install --save-dev cypress-cli-select
+```
+
+### bahmutov cy-grep
+
+In order to run specific tests by their title or tag, install the following plugin:
+
+```sh
+npm install --save-dev @bahmutov/cy-grep
+```
+
+Follow the installation and setup for `@bahmutov/cy-grep` in the project [README](https://github.com/bahmutov/cy-grep)
+
+### cypress grep package
+
+If you use `@cypress/grep`, you can use this package for specs **or** tag selection, but this package uses functionality not currently supported by `@cypress/grep` to allow for other uses.
+
+---
+
+## Run mode
+
+If you want to select e2e specs to run, simply run the following command:
+
+```bash
+npx cypress-cli-select run
+```
+
+For selecting component specs:
+
+```bash
+npx cypress-cli-select run --component
+```
+
+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-cli-select run --component --browser=chrome
+```
+
+### Keyboard controls
+
+|              Keys              |             Action              |
+| :----------------------------: | :-----------------------------: |
+|         <kbd>Up</kbd>          | Move to selection above current |
+|        <kbd>Down</kbd>         | Move to selection below current |
+|         <kbd>Tab</kbd>         |         Select current          |
+| <kbd>Ctrl</kbd> + <kbd>a</kbd> |           Select all            |
+|      <kbd>Backspace</kbd>      |        Remove selection         |
+|        <kbd>Enter</kbd>        |             Proceed             |
+| <kbd>Ctrl</kbd> + <kbd>c</kbd> |              Exit               |
+
+**Note**: You can also filter choices displayed in list by typing
+
+---
+
+## Test titles or tags
+
+If [@bahmutov/cy-grep](https://github.com/bahmutov/cy-grep) package is installed in your project, test titles and tags are available to select.
+
+<img src="./assets/run-spec-tag.gif" alt="Cypress-cli-select tag selection" loop=infinite>
+
+---
+
+## Help mode
+
+To open the cli help menu, pass the `--help` flag:
+
+```bash
+npx cypress-cli-select run --help
+```
+
+<img src="./assets/run-help.gif" alt="Cypress-cli-select help menu" loop=infinite>
+
+---
+
+## Choose spec pattern
+
+If you are interested in running selected specs in a specific order, pass the following flag:
+
+```bash
+npx cypress-cli-select run --choose-spec-pattern
+```
+
+**Note**: If you pass `--choose-spec-pattern` you will not have the choice to run test titles or tags.
+
+### Keyboard controls
+
+|               Keys               |             Action              |
+| :------------------------------: | :-----------------------------: |
+|          <kbd>Up</kbd>           | Move to selection above current |
+|         <kbd>Down</kbd>          | Move to selection below current |
+| <kbd>Shift</kbd> + <kbd>⬆</kbd> |       Reorder current up        |
+| <kbd>Shift</kbd> + <kbd>⬇</kbd> |      Reorder current down       |
+|         <kbd>Enter</kbd>         |          Confirm order          |
+
+<img src="./assets/choose-spec-pattern-demo.gif" alt="Cypress-cli-select choose-spec-pattern demo" loop=infinite>
+
+---
+
+## Print selected
+
+If you want to print all selected specs, tests or tags just prior to Cypress run, pass the following flag:
+
+```bash
+npx cypress-cli-select run --print-selected
+```
+
+![Cypress cli select --print-selected](./assets/print-selected-demo.png)
+
+---
+
+## Submit focused
+
+When no other options are already selected, automatically select the currently focused option with <kbd>Enter</kbd>.
+
+To enable this feature, pass the following flag:
+
+```bash
+npx cypress-cli-select run --submit-focused
+```
+
+---
+
+## Using a custom cypress config
+
+If you want to use a custom Cypress config, pass it via `--config-file` flag:
+
+```bash
+npx cypress-cli-select run --config-file tests/cypress.config.js
+```
+
+---
+
+## 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": {
+    "cy:select": "npx cypress-cli-select run --browser=firefox"
+  }
+```
+
+---
+
+## 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-cli-select/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', () => {
+    // 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')
+    })
+  })
+})