@bahmutov/cy-grep 1.1.0 → 1.2.1

package/README.md

@@ -19,7 +19,7 @@ All other tests will be marked pending, see why in the [Cypress test statuses](h
 
 If you have multiple spec files, all specs will be loaded, and every test will be filtered the same way, since the grep is run-time operation and cannot eliminate the spec files without loading them. If you want to run only specific tests, use the built-in [--spec](https://on.cypress.io/command-line#cypress-run-spec-lt-spec-gt) CLI argument.
 
-Watch the video [intro to cypress-grep plugin](https://www.youtube.com/watch?v=HS-Px-Sghd8)
+Watch the video [intro to cypress-grep plugin](https://www.youtube.com/watch?v=HS-Px-Sghd8) and study my 🎓 Cypress course [Cypress Plugins](https://cypress.tips/courses/cypress-plugins).
 
 Table of Contents
 
@@ -56,9 +56,6 @@ Table of Contents
     - [Debugging in the browser](#debugging-in-the-browser)
   - [Examples](#examples)
   - [See also](#see-also)
-  - [Migration guide](#migration-guide)
-    - [from v1 to v2](#from-v1-to-v2)
-    - [from v2 to v3](#from-v2-to-v3)
   - [Small Print](#small-print)
 
 <!-- /MarkdownTOC -->
@@ -81,7 +78,8 @@ yarn add -D @bahmutov/cy-grep
 **required:** load this module from the [support file](https://on.cypress.io/writing-and-organizing-tests#Support-file) or at the top of the spec file if not using the support file. You import the registration function and then call it:
 
 ```js
-// cypress/support/index.js
+// cypress/support/e2e.js
+
 // load and register the grep feature using "require" function
 // https://github.com/bahmutov/cy-grep
 const registerCypressGrep = require('@bahmutov/cy-grep')
@@ -90,7 +88,7 @@ registerCypressGrep()
 // if you want to use the "import" keyword
 // note: `./index.d.ts` currently extends the global Cypress types and
 // does not define `registerCypressGrep` so the import path is directly
-// pointed to the `support.js` file
+// pointed to the support file
 import registerCypressGrep from '@bahmutov/cy-grep/src/support'
 registerCypressGrep()
 
@@ -111,13 +109,14 @@ registerCypressGrep()
   e2e: {
     setupNodeEvents(on, config) {
       require('@bahmutov/cy-grep/src/plugin')(config);
+      // IMPORTANT: return the config object
       return config;
-  },
+    },
   }
 }
 ```
 
-Installing the plugin via `setupNodeEvents()` is required to enable the [grepFilterSpecs](#grepfilterspecs) feature.
+Installing the plugin via `setupNodeEvents()` is required to enable the [grepFilterSpecs](#pre-filter-specs-grepfilterspecs) feature.
 
 ## Usage Overview
 
@@ -215,8 +214,6 @@ $ npx cypress run --env grep="-hello world"
 $ npx cypress run --env grep="hello; -world"
 ```
 
-**Note:** Inverted title filter is not compatible with the `grepFilterSpecs` option
-
 ## Filter with tags
 
 You can select tests to run or skip using tags by passing `--env grepTags=...` value.
@@ -353,9 +350,12 @@ $ npx cypress run --env grepTags=@smoke,grepFilterSpecs=true
 **Tip:** you can set this environment variable in the [config file](https://docs.cypress.io/guides/references/configuration) file to enable it by default and skip using the environment variable:
 
 ```js
+// config file
 {
-  "env": {
-    "grepFilterSpecs": true
+  "e2e": {
+    "env": {
+      "grepFilterSpecs": true
+    }
   }
 }
 ```
@@ -505,20 +505,23 @@ Once the tests finish, you can run just the failed tests from DevTools console
 
 **Tip:** use `Cypress.grep()` to reset and run all the tests
 
+📝 Read the blog post [Run Just The Failed Tests In Cypress](https://glebbahmutov.com/blog/run-failed-tests/).
+
 ## Debugging
 
-When debugging a problem, first make sure you are using the expected version of this plugin, as some features might be only available in the [later releases](https://github.com/cypress-io/cypress-grep/releases).
+When debugging a problem, first make sure you are using the expected version of this plugin, as some features might be only available in the [later releases](https://github.com/bahmutov/cy-grep/releases).
 
 ```
-# get the cypress-grep version using NPM
-$ npm ls cypress-grep
+# get the plugin's version using NPM
+$ npm ls @bahmutov/cy-grep
 ...
-└── cypress-grep@2.10.1
-# get the cypress-grep version using Yarn
-$ yarn why cypress-grep
+└── @bahmutov/cy-grep@1.1.0
+
+# get the plugin's version using Yarn
+$ yarn why @bahmutov/cy-grep
 ...
-=> Found "cypress-grep@2.10.1"
-info Has been hoisted to "cypress-grep"
+=> Found "@bahmutov/cy-grep@1.1.0"
+info Has been hoisted to "@bahmutov/cy-grep"
 info This module exists because it's specified in "devDependencies".
 ...
 ```
@@ -539,30 +542,28 @@ This module uses [debug](https://github.com/visionmedia/debug#readme) to log ver
 
 ### Debugging in the plugin
 
-Start Cypress with the environment variable `DEBUG=cypress-grep`. You will see a few messages from this plugin in the terminal output:
+Start Cypress with the environment variable `DEBUG=cy-grep`. You will see a few messages from this plugin in the terminal output:
 
 ```
-$ DEBUG=cypress-grep npx cypress run --env grep=works,grepFilterSpecs=true
-cypress-grep: tests with "works" in their names
-cypress-grep: filtering specs using "works" in the title
-  cypress-grep Cypress config env object: { grep: 'works', grepFilterSpecs: true }
+$ DEBUG=cy-grep npx cypress run --env grep=works,grepFilterSpecs=true
+cy-grep: tests with "works" in their names
+cy-grep: filtering specs using "works" in the title
+  cy-grep Cypress config env object: { grep: 'works', grepFilterSpecs: true }
   ...
-  cypress-grep found 1 spec files +5ms
-  cypress-grep [ 'spec.js' ] +0ms
-  cypress-grep spec file spec.js +5ms
-  cypress-grep suite and test names: [ 'hello world', 'works', 'works 2 @tag1',
+  cy-grep found 1 spec files +5ms
+  cy-grep [ 'spec.js' ] +0ms
+  cy-grep spec file spec.js +5ms
+  cy-grep suite and test names: [ 'hello world', 'works', 'works 2 @tag1',
     'works 2 @tag1 @tag2', 'works @tag2' ] +0ms
-  cypress-grep found "works" in 1 specs +0ms
-  cypress-grep [ 'spec.js' ] +0ms
+  cy-grep found "works" in 1 specs +0ms
+  cy-grep [ 'spec.js' ] +0ms
 ```
 
 ### Debugging in the browser
 
-To enable debug console messages in the browser, from the DevTools console set `localStorage.debug='cypress-grep'` and run the tests again.
-
-![Debug messages](./images/debug.png)
+To enable debug console messages in the browser, from the DevTools console set `localStorage.debug='cy-grep'` and run the tests again.
 
-To see how to debug this plugin, watch the video [Debug cypress-grep Plugin](https://youtu.be/4YMAERddHYA).
+To see how to debug this plugin, watch the video [Debug cypress-grep Plugin](https://youtu.be/4YMAERddHYA) but use the string `cy-grep`
 
 ## Examples
 
@@ -574,37 +575,6 @@ To see how to debug this plugin, watch the video [Debug cypress-grep Plugin](htt
 - [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests)
 - [cypress-skip-test](https://github.com/cypress-io/cypress-skip-test)
 
-## Migration guide
-
-### from v1 to v2
-
-In v2 we have separated grepping by part of the title string from tags.
-
-**v1**
-
-```
---env grep="one two"
-```
-
-The above scenario was confusing - did you want to find all tests with title containing "one two" or did you want to run tests tagged `one` or `two`?
-
-**v2**
-
-```
-# enable the tests with string "one two" in their titles
---env grep="one two"
-# enable the tests with tag "one" or "two"
---env grepTags="one two"
-# enable the tests with both tags "one" and "two"
---env grepTags="one+two"
-# enable the tests with "hello" in the title and tag "smoke"
---env grep=hello,grepTags=smoke
-```
-
-### from v2 to v3
-
-Version >= 3 of cypress-grep _only_ supports Cypress >= 10.
-
 ## Small Print
 
 License: MIT - do anything with the code, but don't blame me if it does not work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahmutov/cy-grep",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Filter Cypress tests using title or tags",
   "main": "src/support.js",
   "scripts": {
@@ -12,15 +12,15 @@
   "dependencies": {
     "cypress-plugin-config": "^1.2.0",
     "debug": "^4.3.2",
-    "find-test-names": "^1.22.2",
+    "find-test-names": "^1.23.0",
     "globby": "^11.0.4"
   },
   "devDependencies": {
-    "cypress": "12.1.0",
+    "cypress": "12.3.0",
     "cypress-each": "^1.11.0",
     "cypress-expect": "^2.5.3",
     "prettier": "^2.8.1",
-    "semantic-release": "^19.0.5",
+    "semantic-release": "^20.0.2",
     "typescript": "^4.7.4"
   },
   "peerDependencies": {

package/src/plugin.js

@@ -1,15 +1,15 @@
-const debug = require('debug')('cypress-grep')
+const debug = require('debug')('cy-grep')
 const globby = require('globby')
-const { getTestNames } = require('find-test-names')
+const { getTestNames, findEffectiveTestTags } = require('find-test-names')
 const fs = require('fs')
 const { version } = require('../package.json')
 const { parseGrep, shouldTestRun } = require('./utils')
 
 /**
- * Prints the cypress-grep environment values if any.
+ * Prints the cy-grep environment values if any.
  * @param {Cypress.ConfigOptions} config
  */
-function cypressGrepPlugin (config) {
+function cypressGrepPlugin(config) {
   if (!config || !config.env) {
     return config
   }
@@ -18,23 +18,23 @@ function cypressGrepPlugin (config) {
 
   if (!config.specPattern) {
     throw new Error(
-      'Incompatible versions detected, cypress-grep 3.0.0+ requires Cypress 10.0.0+',
+      'Incompatible versions detected, cy-grep requires Cypress 10.0.0+',
     )
   }
 
-  debug('cypress-grep plugin version %s', version)
+  debug('cy-grep plugin version %s', version)
   debug('Cypress config env object: %o', env)
 
   const grep = env.grep ? String(env.grep) : undefined
 
   if (grep) {
-    console.log('cypress-grep: tests with "%s" in their names', grep.trim())
+    console.log('cy-grep: tests with "%s" in their names', grep.trim())
   }
 
   const grepTags = env.grepTags || env['grep-tags']
 
   if (grepTags) {
-    console.log('cypress-grep: filtering using tag(s) "%s"', grepTags)
+    console.log('cy-grep: filtering using tag(s) "%s"', grepTags)
     const parsedGrep = parseGrep(null, grepTags)
 
     debug('parsed grep tags %o', parsedGrep.tags)
@@ -43,19 +43,19 @@ function cypressGrepPlugin (config) {
   const grepBurn = env.grepBurn || env['grep-burn'] || env.burn
 
   if (grepBurn) {
-    console.log('cypress-grep: running filtered tests %d times', grepBurn)
+    console.log('cy-grep: running filtered tests %d times', grepBurn)
   }
 
   const grepUntagged = env.grepUntagged || env['grep-untagged']
 
   if (grepUntagged) {
-    console.log('cypress-grep: running untagged tests')
+    console.log('cy-grep: running untagged tests')
   }
 
   const omitFiltered = env.grepOmitFiltered || env['grep-omit-filtered']
 
   if (omitFiltered) {
-    console.log('cypress-grep: will omit filtered tests')
+    console.log('cy-grep: will omit filtered tests')
   }
 
   const { specPattern, excludeSpecPattern } = config
@@ -78,7 +78,7 @@ function cypressGrepPlugin (config) {
     let greppedSpecs = []
 
     if (grep) {
-      console.log('cypress-grep: filtering specs using "%s" in the title', grep)
+      console.log('cy-grep: filtering specs using "%s" in the title', grep)
       const parsedGrep = parseGrep(grep)
 
       debug('parsed grep %o', parsedGrep)
@@ -117,15 +117,14 @@ function cypressGrepPlugin (config) {
         const text = fs.readFileSync(specFile, { encoding: 'utf8' })
 
         try {
-          const testInfo = getTestNames(text)
-
+          const testTags = findEffectiveTestTags(text)
+          // we get back a single object with keys being full test titles
+          // and the values being arrays of effective test tags
           debug('spec file %s', specFile)
-          debug('test info: %o', testInfo.tests)
-
-          return testInfo.tests.some((info) => {
-            const shouldRun = shouldTestRun(parsedGrep, null, info.tags)
-
-            return shouldRun
+          debug('effective test tags %o', testTags)
+          return Object.keys(testTags).some((testTitle) => {
+            const effectiveTags = testTags[testTitle].effectiveTags
+            return shouldTestRun(parsedGrep, null, effectiveTags)
           })
         } catch (err) {
           console.error('Could not determine test names in file: %s', specFile)

package/src/support.js

@@ -8,7 +8,8 @@ const {
   getPluginConfigValue,
   setPluginConfigValue,
 } = require('cypress-plugin-config')
-const debug = require('debug')('@bahmutov/cy-grep')
+// to debug in the browser, set the "localStorage.debug='cy-grep'"
+const debug = require('debug')('cy-grep')
 
 debug.log = console.info.bind(console)
 
@@ -18,7 +19,7 @@ const _describe = describe
 
 /**
  * Wraps the "it" and "describe" functions that support tags.
- * @see https://github.com/cypress-io/cypress-grep
+ * @see https://github.com/bahmutov/cy-grep
  */
 function cypressGrep() {
   /** @type {string} Part of the test title go grep */
@@ -70,9 +71,8 @@ function cypressGrep() {
   debug('parsed grep %o', parsedGrep)
 
   // prevent multiple registrations
-  // https://github.com/cypress-io/cypress-grep/issues/59
   if (it.name === 'itGrep') {
-    debug('already registered cypress-grep')
+    debug('already registered cy-grep')
 
     return
   }
@@ -205,7 +205,6 @@ function cypressGrep() {
   it.skip = _it.skip
   it.only = _it.only
   // preserve "it.each" method if found
-  // https://github.com/cypress-io/cypress-grep/issues/72
   if (typeof _it.each === 'function') {
     it.each = _it.each
   }
@@ -237,7 +236,6 @@ if (!Cypress.grep) {
    *  // remove all current grep settings
    *  // and run all tests
    *  Cypress.grep()
-   * @see "Grep from DevTools console" https://github.com/cypress-io/cypress-grep#devtools-console
    */
   Cypress.grep = function grep(grep, tags, burn) {
     setPluginConfigValue('grep', grep)