Cypress plugin grep-boxes

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

!cy-grep-boxes-demo

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:

> [!NOTE]
> To support cypress-plugin-grep-boxes displaying test tags in the Cypress Test Runner, @bahmutov/cy-grep must be on version >= 2.1.0

``sh
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),

> [!IMPORTANT]
> In the plugin version 2.0.0, the e2e.js (or component.js) support file import has been updated for simplicity:

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

registerCypressGrep();
`

---

🦺 Setup

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.

✅ 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

$3

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!

$3

> [!NOTE]
> Read more about this topic within a blog post Use Required Test Tags Instead Of Skipping Tests and within the README for @bahmutov/cy-grep.

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:

`js
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:

`bash
npx cypress open --env 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 environment variable hideSpecTags set to an array of tags you do not want to be displayed in the Cypress Test Runner.

$3

Example:

`json
{
"env": {
"hideSpecTags": ["@smoke", "@sanity"]
}
}
`

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

$3

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

`json
{
"env": {
"hideSpecTags": ["*"]
}
}
`

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

$3

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 +:

`json
{
"env": {
"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 environment variable disableInitialAutoRun=true:

!disableInitialAutoRun_demo

`bash


Example via CLI


npx cypress open --env disableInitialAutoRun=true
`

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

`js
// config file
{
"e2e": {
"env": {
"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.