@bahmutov/cy-grep 1.2.1 → 1.3.1

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)
@@ -118,6 +119,15 @@ registerCypressGrep()
 
 Installing the plugin via `setupNodeEvents()` is required to enable the [grepFilterSpecs](#pre-filter-specs-grepfilterspecs) feature.
 
+**Tip:** you probably want to set these `env` settings in your config file
+
+```js
+module.exports = defineConfig({
+  env: { grepFilterSpecs: true, grepOmitFiltered: true },
+  ...
+})
+```
+
 ## Usage Overview
 
 You can filter tests to run using part of their title via `grep`, and via explicit tags via `grepTags` Cypress environment variables.
@@ -410,6 +420,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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahmutov/cy-grep",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Filter Cypress tests using title or tags",
   "main": "src/support.js",
   "scripts": {
@@ -12,7 +12,7 @@
   "dependencies": {
     "cypress-plugin-config": "^1.2.0",
     "debug": "^4.3.2",
-    "find-test-names": "^1.23.0",
+    "find-test-names": "1.25.0",
     "globby": "^11.0.4"
   },
   "devDependencies": {
@@ -20,7 +20,7 @@
     "cypress-each": "^1.11.0",
     "cypress-expect": "^2.5.3",
     "prettier": "^2.8.1",
-    "semantic-release": "^20.0.2",
+    "semantic-release": "^20.0.4",
     "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

@@ -124,7 +124,14 @@ function cypressGrepPlugin(config) {
           debug('effective test tags %o', testTags)
           return Object.keys(testTags).some((testTitle) => {
             const effectiveTags = testTags[testTitle].effectiveTags
-            return shouldTestRun(parsedGrep, null, effectiveTags)
+            const requiredTags = testTags[testTitle].requiredTags
+            return shouldTestRun(
+              parsedGrep,
+              null,
+              effectiveTags,
+              false,
+              requiredTags,
+            )
           })
         } catch (err) {
           console.error('Could not determine test names in file: %s', specFile)

package/src/support.js

@@ -21,7 +21,7 @@ const _describe = describe
  * Wraps the "it" and "describe" functions that support tags.
  * @see https://github.com/bahmutov/cy-grep
  */
-function cypressGrep() {
+function registerCyGrep() {
   /** @type {string} Part of the test title go grep */
   let grep = getPluginConfigValue('grep')
 
@@ -42,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 =
@@ -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]
     }
@@ -285,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,
 }