@bahmutov/cy-grep 1.11.5 → 2.0.0

package/README.md

@@ -1,4 +1,4 @@
-# @bahmutov/cy-grep ![cypress version](https://img.shields.io/badge/cypress-13.13.0-brightgreen)
+# @bahmutov/cy-grep ![cypress version](https://img.shields.io/badge/cypress-13.15.0-brightgreen)
 
 > Filter tests using substring or tag
 
@@ -30,6 +30,9 @@ Watch the video [intro to cypress-grep plugin](https://www.youtube.com/watch?v=H
 - [Lesson k5: Filter the tests to run using OR of several tags](https://cypress.tips/courses/cypress-plugins/lessons/k5)
 - [Lesson k6: Repeat selected tests N times](https://cypress.tips/courses/cypress-plugins/lessons/k6)
 - [Lesson k7: Pick the tests to run in the interactive mode](https://cypress.tips/courses/cypress-plugins/lessons/k7)
+- [Lesson k8: Automatically prefix tags with the "@" character](https://cypress.tips/courses/cypress-plugins/lessons/k8)
+- [Lesson k9: Set baseUrl depending on the test tag](https://cypress.tips/courses/cypress-plugins/lessons/k9)
+- [Lesson k10: Limit test tags to specific values](https://cypress.tips/courses/cypress-plugins/lessons/k10)
 
 ## Table of Contents
 
@@ -76,6 +79,8 @@ Watch the video [intro to cypress-grep plugin](https://www.youtube.com/watch?v=H
   - [Examples](#examples)
   - [See also](#see-also)
   - [cy-grep vs cypress-grep vs @cypress/grep](#cy-grep-vs-cypress-grep-vs-cypressgrep)
+  - [Major migrations](#major-migrations)
+    - [v1 to v2](#v1-to-v2)
   - [Small Print](#small-print)
 
 <!-- /MarkdownTOC -->
@@ -559,23 +564,41 @@ it('runs on deploy', { tags: 'smoke' }, () => {
 })
 ```
 
-This package comes with [src/index.d.ts](./src/index.d.ts) definition file that adds the property `tags` to the Cypress test overrides interface. Include this file in your specs or TS config settings. For example, you can load it using a reference comment
-
-```js
-// cypress/integration/my-spec.js
-/// <reference types="@bahmutov/cy-grep" />
-```
-
-If you have `tsconfig.json` file, add this library to the types list
+If you want to allow any strings to be test tags, simply include [src/tags-are-strings.d.ts](./src/tags-are-strings.d.ts) included with this package in your project TS config:
 
 ```json
 {
+  "include": [
+    "cypress/**/*",
+    "node_modules/@bahmutov/cy-grep/src/tags-are-strings.d.ts"
+  ],
   "compilerOptions": {
-    "target": "es5",
-    "lib": ["es5", "dom"],
     "types": ["cypress", "@bahmutov/cy-grep"]
-  },
-  "include": ["**/*.ts"]
+  }
+}
+```
+
+If you want to provide your _own_ list of allowed tags, create a `.d.ts` file or extend your `index.d.ts` file
+
+```ts
+// your project's index.d.ts file
+/// <reference types="cypress" />
+
+/**
+ * The only allowed test tags in this project
+ */
+type AllowedTag = '@smoke' | '@misc' | '@new-todo'
+
+declare namespace Cypress {
+  interface SuiteConfigOverrides {
+    tags?: AllowedTag | AllowedTag[]
+    requiredTags?: AllowedTag | AllowedTag[]
+  }
+
+  interface TestConfigOverrides {
+    tags?: AllowedTag | AllowedTag[]
+    requiredTags?: AllowedTag | AllowedTag[]
+  }
 }
 ```
 
@@ -742,6 +765,45 @@ Many years ago I wrote a plugin `cypress-grep`. When I left the company Cypress,
 
 I plan to maintain the plugin `@bahmutov/cy-grep` in the future, since I rely on it myself **a lot**.
 
+## Major migrations
+
+### v1 to v2
+
+Adding a type for `tags` and `requiredTags` moved from default to its own `.d.ts` file.
+
+**v1**
+
+For example, the plugin `@bahmutov/cy-grep@v1` simply could add itself to the `types` list in your `tsconfig.json` / `jsconfig.json` file
+
+```json
+{
+  "include": ["cypress/**/*"],
+  "compilerOptions": {
+    "types": ["cypress", "@bahmutov/cy-grep"]
+  }
+}
+```
+
+This made `tags` property a string, so you could use `it('works', { tags: '@smoke' }, () => ...)`
+
+**v2**
+
+If you want to use _any_ strings as tags, you need to add the file [src/tags-are-strings.d.ts](./src/tags-are-strings.d.ts)
+
+```json
+{
+  "include": [
+    "cypress/**/*",
+    "node_modules/@bahmutov/cy-grep/src/tags-are-strings.d.ts"
+  ],
+  "compilerOptions": {
+    "types": ["cypress", "@bahmutov/cy-grep"]
+  }
+}
+```
+
+**Note:** you still want to include the `@bahmutov/cy-grep` default types, since they provide additional static methods, like `Cypress.grep`
+
 ## Small Print
 
 Author: Gleb Bahmutov &lt;gleb.bahmutov@gmail.com&gt; &copy; 2022

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahmutov/cy-grep",
-  "version": "1.11.5",
+  "version": "2.0.0",
   "description": "Filter Cypress tests using title or tags",
   "main": "src/support.js",
   "scripts": {
@@ -20,11 +20,11 @@
     "globby": "^11.1.0"
   },
   "devDependencies": {
-    "cypress": "13.13.0",
+    "cypress": "13.17.0",
     "cypress-each": "^1.11.0",
     "cypress-expect": "^3.1.0",
     "prettier": "^3.0.0",
-    "semantic-release": "^24.1.2",
+    "semantic-release": "^24.2.0",
     "stop-only": "^3.3.1",
     "typescript": "^5.0.0"
   },

package/src/index.d.ts

@@ -1,44 +1,6 @@
 /// <reference types="cypress" />
 
 declare namespace Cypress {
-  interface SuiteConfigOverrides {
-    /**
-     * List of tags for this suite
-     * @example a single tag
-     *  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
-  // in our case we will add "tags" property
-  interface TestConfigOverrides {
-    /**
-     * List of tags for this test
-     * @example a single tag
-     *  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 {
     /**
      * Runs only the tests that contain the given "grep" string

package/src/tags-are-strings.d.ts

@@ -0,0 +1,45 @@
+/// <reference types="cypress" />
+
+// default types for test "tags" and "requiredTags" properties
+// tags could be a single string or an array of strings
+// see https://github.com/bahmutov/cy-grep?tab=readme-ov-file#typescript-support
+
+declare namespace Cypress {
+  interface SuiteConfigOverrides {
+    /**
+     * List of tags for this suite
+     * @example a single tag
+     *  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
+  // in our case we will add "tags" property
+  interface TestConfigOverrides {
+    /**
+     * List of tags for this test
+     * @example a single tag
+     *  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[]
+  }
+}