@bahmutov/cy-grep 1.2.0 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# @bahmutov/cy-grep ![cypress version](https://img.shields.io/badge/cypress-12.1.0-brightgreen)
+# @bahmutov/cy-grep ![cypress version](https://img.shields.io/badge/cypress-12.3.0-brightgreen)
 
 > Filter tests using substring or tag
 
@@ -46,6 +46,7 @@ Table of Contents
   - [Omit filtered tests (grepOmitFiltered)](#omit-filtered-tests-grepomitfiltered)
   - [Disable grep](#disable-grep)
   - [Burn (repeat) tests](#burn-repeat-tests)
+  - [Required tags](#required-tags)
   - [TypeScript support](#typescript-support)
   - [General advice](#general-advice)
   - [DevTools console](#devtools-console)
@@ -56,9 +57,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 -->
@@ -217,8 +215,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.
@@ -415,6 +411,16 @@ You can pass the number of times to run the tests via environment name `burn` or
 
 If you do not specify the "grep" or "grep tags" option, the "burn" will repeat _every_ test.
 
+## Required tags
+
+Sometimes you might want to run a test or a suite of tests _only_ if a specific tag or tags are present. For example, you might have a test that cleans the data. This test is meant to run nightly, not on every test run. Thus you can set a `required` tag:
+
+```js
+it('cleans up the data', { requiredTags: '@nightly' }, () => {...})
+```
+
+When you run the tests now, this test will be skipped, as if it were `it.skip`. It will only run if you use the tag `@nightly`, for example: `npx cypress run --env grepTags=@nightly`.
+
 ## TypeScript support
 
 Because the Cypress test config object type definition does not have the `tags` property we are using above, the TypeScript linter will show an error. Just add an ignore comment above the test:
@@ -547,30 +553,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.
+To enable debug console messages in the browser, from the DevTools console set `localStorage.debug='cy-grep'` and run the tests again.
 
-![Debug messages](./images/debug.png)
-
-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
 
@@ -582,37 +586,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.2.0",
+  "version": "1.3.0",
   "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.25.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.3",
     "typescript": "^4.7.4"
   },
   "peerDependencies": {

package/src/index.d.ts

@@ -8,8 +8,15 @@ declare namespace Cypress {
      *  describe('block with config tag', { tags: '@smoke' }, () => {})
      * @example multiple tags
      *  describe('block with config tag', { tags: ['@smoke', '@slow'] }, () => {})
+     * @see https://github.com/bahmutov/cy-grep
      */
     tags?: string | string[]
+    /**
+     * Provide a tag or a list of tags that is required for this suite to run.
+     * @example describe('mobile tests', { requiredTags: '@mobile' }, () => {})
+     * @see https://github.com/bahmutov/cy-grep
+     */
+    requiredTags?: string | string[]
   }
 
   // specify additional properties in the TestConfig object
@@ -21,8 +28,15 @@ declare namespace Cypress {
      *  it('logs in', { tags: '@smoke' }, () => { ... })
      * @example multiple tags
      *  it('works', { tags: ['@smoke', '@slow'] }, () => { ... })
+     * @see https://github.com/bahmutov/cy-grep
      */
     tags?: string | string[]
+    /**
+     * Provide a tag or a list of tags that is required for this test to run.
+     * @example it('cleans the data', { requiredTags: '@nightly' }, () => {})
+     * @see https://github.com/bahmutov/cy-grep
+     */
+    requiredTags?: string | string[]
   }
 
   interface Cypress {

package/src/plugin.js

@@ -1,4 +1,4 @@
-const debug = require('debug')('cypress-grep')
+const debug = require('debug')('cy-grep')
 const globby = require('globby')
 const { getTestNames, findEffectiveTestTags } = require('find-test-names')
 const fs = require('fs')
@@ -6,7 +6,7 @@ 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) {
@@ -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)
@@ -123,7 +123,7 @@ function cypressGrepPlugin(config) {
           debug('spec file %s', specFile)
           debug('effective test tags %o', testTags)
           return Object.keys(testTags).some((testTitle) => {
-            const effectiveTags = testTags[testTitle]
+            const effectiveTags = testTags[testTitle].effectiveTags
             return shouldTestRun(parsedGrep, null, effectiveTags)
           })
         } catch (err) {

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,9 +19,9 @@ 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() {
+function registerCyGrep() {
   /** @type {string} Part of the test title go grep */
   let grep = getPluginConfigValue('grep')
 
@@ -41,12 +42,12 @@ function cypressGrep() {
     getPluginConfigValue('grepUntagged') ||
     getPluginConfigValue('grep-untagged')
 
-  if (!grep && !grepTags && !burnSpecified && !grepUntagged) {
-    // nothing to do, the user has no specified the "grep" string
-    debug('Nothing to grep, version %s', version)
+  // if (!grep && !grepTags && !burnSpecified && !grepUntagged) {
+  // nothing to do, the user has no specified the "grep" string
+  // debug('Nothing to grep, version %s', version)
 
-    return
-  }
+  // return
+  // }
 
   /** @type {number} Number of times to repeat each running test */
   const grepBurn =
@@ -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
   }
@@ -90,32 +90,41 @@ function cypressGrep() {
     }
 
     let configTags = options && options.tags
-
     if (typeof configTags === 'string') {
       configTags = [configTags]
     }
+    let configRequiredTags = options && options.requiredTags
+    if (typeof configRequiredTags === 'string') {
+      configRequiredTags = [configRequiredTags]
+    }
 
     const nameToGrep = suiteStack
       .map((item) => item.name)
       .concat(name)
       .join(' ')
-    const tagsToGrep = suiteStack
+    const effectiveTestTags = suiteStack
       .flatMap((item) => item.tags)
       .concat(configTags)
       .filter(Boolean)
+    const requiredTestTags = suiteStack
+      .flatMap((item) => item.requiredTags)
+      .concat(configRequiredTags)
+      .filter(Boolean)
+    // console.log({ nameToGrep, effectiveTestTags, requiredTestTags })
 
     const shouldRun = shouldTestRun(
       parsedGrep,
       nameToGrep,
-      tagsToGrep,
+      effectiveTestTags,
       grepUntagged,
+      requiredTestTags,
     )
 
-    if (tagsToGrep && tagsToGrep.length) {
+    if (effectiveTestTags && effectiveTestTags.length) {
       debug(
         'should test "%s" with tags %s run? %s',
         name,
-        tagsToGrep.join(','),
+        effectiveTestTags.join(','),
         shouldRun,
       )
     } else {
@@ -171,7 +180,6 @@ function cypressGrep() {
     }
 
     let configTags = options && options.tags
-
     if (typeof configTags === 'string') {
       configTags = [configTags]
     }
@@ -205,7 +213,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 +244,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)
@@ -287,4 +293,4 @@ if (!Cypress.grepFailed) {
   }
 }
 
-module.exports = cypressGrep
+module.exports = registerCyGrep

package/src/utils.js

@@ -7,7 +7,7 @@
  * The string can have "-" in front of it to invert the match.
  * @param {string} s Input substring of the test title
  */
-function parseTitleGrep (s) {
+function parseTitleGrep(s) {
   if (!s || typeof s !== 'string') {
     return null
   }
@@ -26,7 +26,7 @@ function parseTitleGrep (s) {
   }
 }
 
-function parseFullTitleGrep (s) {
+function parseFullTitleGrep(s) {
   if (!s || typeof s !== 'string') {
     return []
   }
@@ -39,7 +39,7 @@ function parseFullTitleGrep (s) {
  * Parses tags to grep for.
  * @param {string} s Tags string like "@tag1+@tag2"
  */
-function parseTagsGrep (s) {
+function parseTagsGrep(s) {
   if (!s) {
     return []
   }
@@ -48,37 +48,37 @@ function parseTagsGrep (s) {
 
   // top level split - using space or comma, each part is OR
   const ORS = s
-  .split(/[ ,]/)
-  // remove any empty tags
-  .filter(Boolean)
-  .map((part) => {
-    // now every part is an AND
-    if (part.startsWith('--')) {
-      explicitNotTags.push({
-        tag: part.slice(2),
-        invert: true,
-      })
+    .split(/[ ,]/)
+    // remove any empty tags
+    .filter(Boolean)
+    .map((part) => {
+      // now every part is an AND
+      if (part.startsWith('--')) {
+        explicitNotTags.push({
+          tag: part.slice(2),
+          invert: true,
+        })
 
-      return
-    }
+        return
+      }
+
+      const parsed = part.split('+').map((tag) => {
+        if (tag.startsWith('-')) {
+          return {
+            tag: tag.slice(1),
+            invert: true,
+          }
+        }
 
-    const parsed = part.split('+').map((tag) => {
-      if (tag.startsWith('-')) {
         return {
-          tag: tag.slice(1),
-          invert: true,
+          tag,
+          invert: false,
         }
-      }
+      })
 
-      return {
-        tag,
-        invert: false,
-      }
+      return parsed
     })
 
-    return parsed
-  })
-
   // filter out undefined from explicit not tags
   const ORS_filtered = ORS.filter((x) => x !== undefined)
 
@@ -88,14 +88,29 @@ function parseTagsGrep (s) {
     })
 
     if (ORS_filtered.length === 0) {
-      ORS_filtered[ 0 ] = explicitNotTags
+      ORS_filtered[0] = explicitNotTags
     }
   }
 
   return ORS_filtered
 }
 
-function shouldTestRunTags (parsedGrepTags, tags = []) {
+function shouldTestRunRequiredTags(parsedGrepTags, requiredTags = []) {
+  if (!requiredTags.length) {
+    // there are no tags to check
+    return true
+  }
+
+  return requiredTags.every((onlyTag) => {
+    return parsedGrepTags.some((orPart) => {
+      return orPart.some((p) => {
+        return !p.invert && p.tag === onlyTag
+      })
+    })
+  })
+}
+
+function shouldTestRunTags(parsedGrepTags, tags = []) {
   if (!parsedGrepTags.length) {
     // there are no parsed tags to search for, the test should run
     return true
@@ -121,7 +136,7 @@ function shouldTestRunTags (parsedGrepTags, tags = []) {
   return onePartMatched
 }
 
-function shouldTestRunTitle (parsedGrep, testName) {
+function shouldTestRunTitle(parsedGrep, testName) {
   if (!testName) {
     // if there is no title, let it run
     return true
@@ -152,7 +167,20 @@ function shouldTestRunTitle (parsedGrep, testName) {
 }
 
 // note: tags take precedence over the test name
-function shouldTestRun (parsedGrep, testName, tags = [], grepUntagged = false) {
+/**
+ * Returns boolean if the test with the given name and effective tags
+ * should run, given the runtime grep (parsed) structure.
+ * @param {string|undefined} testName The full test title
+ * @param {string[]} tags The effective test tags
+ * @param {string[]} requiredTags The effective "required" test tags
+ */
+function shouldTestRun(
+  parsedGrep,
+  testName,
+  tags = [],
+  grepUntagged = false,
+  requiredTags = [],
+) {
   if (grepUntagged) {
     return !tags.length
   }
@@ -163,13 +191,16 @@ function shouldTestRun (parsedGrep, testName, tags = [], grepUntagged = false) {
     testName = undefined
   }
 
+  const combinedTagsAndRequiredTags = [...tags, ...requiredTags]
+
   return (
     shouldTestRunTitle(parsedGrep.title, testName) &&
-    shouldTestRunTags(parsedGrep.tags, tags)
+    shouldTestRunTags(parsedGrep.tags, combinedTagsAndRequiredTags) &&
+    shouldTestRunRequiredTags(parsedGrep.tags, requiredTags)
   )
 }
 
-function parseGrep (titlePart, tags) {
+function parseGrep(titlePart, tags) {
   return {
     title: parseFullTitleGrep(titlePart),
     tags: parseTagsGrep(tags),
@@ -183,5 +214,6 @@ module.exports = {
   parseTagsGrep,
   shouldTestRun,
   shouldTestRunTags,
+  shouldTestRunRequiredTags,
   shouldTestRunTitle,
 }