README.md

Cypress plugin grep-boxes

A companion Cypress plugin for cy-grep that allows user to run specific test(s) in open mode.

Features

• ✅ A new UI test selection within cypress open to filter and run only selected tests in a given spec
• 🚩 NEW in v2.0.0: Tags are now displayed and can be clicked to filter by respective tag in cypress open

Table of Contents

• Installation
• Setup
• Open mode
  • Using cypress-plugin-filter-runnables
  • Use Required Test Tags Instead Of Skipping Tests
• hideSpecTags
• disableInitialAutoRun
• Contributions

---

📦 Installation

1. Install the following packages:

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

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

import 'cypress-plugin-grep-boxes';
import registerCypressGrep from '@bahmutov/cy-grep/src/support';

registerCypressGrep();

---

🦺 Setup

Recommended: Set two common expose 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:

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

✅ Open mode

Within each spec in Cypress open mode:

• You can select any given number of individual test(s) and click the filter toggle located on the reporter above
• You can click on any available tag and run only tests in the spec with the respective tag

Using cypress-plugin-filter-runnables

NEW in v2.1.0: If filtering tests using cypress-plugin-filter-runnables, simply click the filter toggle located on the reporter above to only run those tests.

No need to check each checkbox of each test you see after filtering by test title!

Use Required Test Tags Instead Of Skipping Tests

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 expose variable grepTags=@skip).

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

npx cypress open --expose grepTags=@skip

hideSpecTags

The cypress-plugin-grep-boxes plugin (new in v2.0.0) displays all available effectiveTestTags in the Cypress Test Runner for each test.

If for any reason you'd like to exclude tags from being displayed in the Cypress Test Runner, use the expose variable hideSpecTags set to an array of tags you do not want to be displayed in the Cypress Test Runner.

Hide specific tags

Example:

{
  "expose": {
    "hideSpecTags": ["@smoke", "@sanity"]
  }
}

The example above would hide @smoke and @sanity tags, but show all other tags, in the Cypress Test Runner.

Hide all tags

If you'd like to exclude all tags from being displayed in the Cypress Test Runner, use the following:

{
  "expose": {
    "hideSpecTags": ["*"]
  }
}

The example above would not display ANY tags to Cypress Test Runner.

Hide all tags EXCEPT specified

If you'd like to ONLY display a specific subset of tags in the Cypress Test Runner, prefix tags you'd like to see displayed with +:

{
  "expose": {
    "hideSpecTags": ["*", "+@smoke", "+@sanity"]
  }
}

The example above would hide all tags EXCEPT @smoke and @sanity tags in the Cypress Test Runner.

disableInitialAutoRun

Cypress Test Runner UI automatically runs available tests once a spec file is open.

To prevent this behavior to have control of when and which tests to run, add the expose variable disableInitialAutoRun=true:

# Example via CLI
npx cypress open --expose disableInitialAutoRun=true

Tip: you can set this expose variable in the config file file to enable it by default and skip using the expose variable:

// config file
{
  "e2e": {
    "expose": {
      "disableInitialAutoRun": true
    }
  }
}

Contributions

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.