前端测试工具：主要用于浏览器端到端测试的自动化工具，端到端(E2E)测试就是站在用户的角度，模拟实际使用场景的测试方式

# @cypress/grep > Filter tests using substring ```shell # run only tests with "hello" in their names npx cypress run --env grep=hello ✓ hello world - works - works 2 @tag1 - works 2 @tag1 @tag2 1 passing (38ms) 3 pending ``` All other tests will be marked pending, see why in the [Cypress test statuses](https://on.cypress.io/writing-and-organizing-tests#Test-statuses) blog post. 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. Table of Contents <!-- MarkdownTOC autolink="true" --> - [Install](#install) - [Support file](#support-file) - [Config file](#config-file) - [Usage Overview](#usage-overview) - [Filter by test title](#filter-by-test-title) - [OR substring matching](#or-substring-matching) - [Test suites](#test-suites) - [Invert filter](#invert-filter) - [Filter with tags](#filter-with-tags) - [Tags in the test config object](#tags-in-the-test-config-object) - [AND tags](#and-tags) - [OR tags](#or-tags) - [Inverted tags](#inverted-tags) - [NOT tags](#not-tags) - [Tags in test suites](#tags-in-test-suites) - [Grep untagged tests](#grep-untagged-tests) - [Pre-filter specs \(grepFilterSpecs\)](#pre-filter-specs-grepfilterspecs) - [Omit filtered tests \(grepOmitFiltered\)](#omit-filtered-tests-grepomitfiltered) - [Disable grep](#disable-grep) - [Burn \(repeat\) tests](#burn-repeat-tests) - [TypeScript support](#typescript-support) - [General advice](#general-advice) - [DevTools console](#devtools-console) - [Debugging](#debugging) - [Log messages](#log-messages) - [Debugging in the plugin](#debugging-in-the-plugin) - [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) - [Videos & Blog Posts](#videos--blog-posts) - [Blog posts](#blog-posts) - [Small print](#small-print) - [MIT License](#mit-license) <!-- /MarkdownTOC --> ## Install Assuming you have Cypress installed, add this module as a dev dependency. ```shell # using NPM npm i -D @cypress/grep # using Yarn yarn add -D @cypress/grep ``` **Note**: @cypress/grep only works with Cypress version >= 10. ### Support file **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/e2e.js // load and register the grep feature using "require" function // https://github.com/cypress-io/cypress/tree/develop/npm/grep const registerCypressGrep = require('@cypress/grep') 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 import registerCypressGrep from '@cypress/grep/src/support' registerCypressGrep() // "import" with `@ts-ignore` // @see error 2306 https://github.com/microsoft/TypeScript/blob/3fcd1b51a1e6b16d007b368229af03455c7d5794/src/compiler/diagnosticMessages.json#L1635 // @ts-ignore import registerCypressGrep from '@cypress/grep' registerCypressGrep() ``` ### Config file **optional:** load and register this module from the [config file](https://docs.cypress.io/guides/references/configuration#setupNodeEvents): ```js // cypress.config.js { e2e: { setupNodeEvents(on, config) { require('@cypress/grep/src/plugin')(config); return config; }, } } ``` Installing the plugin via `setupNodeEvents()` is required to enable the [grepFilterSpecs](#grepfilterspecs) feature. ## Usage Overview You can filter tests to run using part of their title via `grep`, and via explicit tags via `grepTags` Cypress environment variables. Most likely you will pass these environment variables from the command line. For example, to only run tests with "login" in their title and tagged "smoke", you would run: Here are a few examples: ```shell # run only the tests with "auth user" in the title $ npx cypress run --env grep="auth user" # run tests with "hello" or "auth user" in their titles # by separating them with ";" character $ npx cypress run --env grep="hello; auth user" # run tests tagged @fast $ npx cypress run --env grepTags=@fast # run only the tests tagged "smoke" # that have "login" in their titles $ npx cypress run --env grep=login,grepTags=smoke # only run the specs that have any tests with "user" in their titles $ npx cypress run --env grep=user,grepFilterSpecs=true # only run the specs that have any tests tagged "@smoke" $ npx cypress run --env grepTags=@smoke,grepFilterSpecs=true # run only tests that do not have any tags # and are not inside suites that have any tags $ npx cypress run --env grepUntagged=true ``` You can use any way to modify the environment values `grep` and `grepTags`, except the run-time `Cypress.env('grep')` (because it is too late at run-time). You can set the `grep` value in the `cypress.json` file to run only tests with the substring `viewport` in their names ```json { "env": { "grep": "viewport" } } ``` You can also set the `env.grep` object in the plugin file, but remember to return the changed config object: ```js // cypress/plugin/index.js module.exports = (on, config) => { config.env.grep = 'viewport' return config } ``` You can also set the grep and grepTags from the DevTools console while running Cypress in the interactive mode `cypress open`, see [DevTools Console section](#devtools-console). ## Filter by test title ```shell # run all tests with "hello" in their title $ npx cypress run --env grep=hello # run all tests with "hello world" in their title $ npx cypress run --env grep="hello world" ``` ### OR substring matching You can pass multiple title substrings to match separating them with `;` character. Each substring is trimmed. ```shell # run all tests with "hello world" or "auth user" in their title $ npx cypress run --env grep="hello world; auth user" ``` ### Test suites The filter is also applied to the "describe" blocks. In that case, the tests look up if any of their outer suites are enabled. ```js describe('block for config', () => { it('should run', () => {}) it('should also work', () => {}) }) ``` ``` # run any tests in the blocks including "config" --env grep=config ``` **Note:** global function `describe` and `context` are aliases and both supported by this plugin. ### Invert filter ```shell # run all tests WITHOUT "hello world" in their title $ npx cypress run --env grep="-hello world" # run tests with "hello", but without "world" in the titles $ 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. ``` # 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 ``` If you can pass commas in the environment variable `grepTags`, you can use `,` to separate the tags ``` # enable the tests with tag "one" or "two" CYPRESS_grepTags=one,two npx cypress run ``` ### Tags in the test config object Cypress tests can have their own [test config object](https://on.cypress.io/configuration#Test-Configuration), and when using this plugin you can put the test tags there, either as a single tag string or as an array of tags. ```js it('works as an array', { tags: ['config',