Skip to content
This repository was archived by the owner on Mar 29, 2023. It is now read-only.

Commit 455836f

Browse files
NarretzNarretz
committed
docs: re-organize readme
- table of contents - move "api" sections to the top - separate name + tag filter docs, because not all functionality is available for both - group general api info together
1 parent 2568aeb commit 455836f

File tree

1 file changed

+167
-128
lines changed

1 file changed

+167
-128
lines changed

‎README.md

Lines changed: 167 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,46 @@ If you have multiple spec files, all specs will be loaded, and every test will b
2323

2424
Watch the video [intro to cypress-grep plugin](https://www.youtube.com/watch?v=HS-Px-Sghd8)
2525

26+
Table of Contents
27+
28+
<!-- MarkdownTOC autolink="true" -->
29+
30+
- [Install](#install)
31+
- [Plugin file](#plugin-file)
32+
- [Usage Overview](#usage-overview)
33+
- [Filter by test title](#filter-by-test-title)
34+
- [OR substring matching](#or-substring-matching)
35+
- [Test suites](#test-suites)
36+
- [Invert filter](#invert-filter)
37+
- [Filter with tags](#filter-with-tags)
38+
- [Tags in the test config object](#tags-in-the-test-config-object)
39+
- [AND tags](#and-tags)
40+
- [OR tags](#or-tags)
41+
- [Test suites](#test-suites-1)
42+
- [Invert tag](#invert-tag)
43+
- [Grep untagged tests](#grep-untagged-tests)
44+
- [Pre-filter specs \(grepFilterSpecs\)](#pre-filter-specs-grepfilterspecs)
45+
- [Omit filtered tests \(grepOmitFiltered\)](#omit-filtered-tests-grepomitfiltered)
46+
- [Disable grep](#disable-grep)
47+
- [Burn \(repeat\) tests](#burn-repeat-tests)
48+
- [TypeScript support](#typescript-support)
49+
- [General advice](#general-advice)
50+
- [DevTools console](#devtools-console)
51+
- [Debugging](#debugging)
52+
- [Log messages](#log-messages)
53+
- [Debugging in the plugin](#debugging-in-the-plugin)
54+
- [Debugging in the browser](#debugging-in-the-browser)
55+
- [Examples](#examples)
56+
- [See also](#see-also)
57+
- [Migration guide](#migration-guide)
58+
- [from v1 to v2](#from-v1-to-v2)
59+
- [Videos & Blog Posts](#videos--blog-posts)
60+
- [Blog posts](#blog-posts)
61+
- [Small print](#small-print)
62+
- [MIT License](#mit-license)
63+
64+
<!-- /MarkdownTOC -->
65+
2666
## Install
2767

2868
Assuming you have Cypress installed, add this module as a dev dependency
@@ -68,9 +108,13 @@ registerCypressGrep()
68108

69109
Installing the plugin via `setupNodeEvents()` is required to enable the [grepFilterSpecs](#grepfilterspecs) feature.
70110

71-
## Use
111+
## Usage Overview
112+
113+
You can filter tests to run using part of their title via `grep`, and via explicit tags via `grepTags` Cypress environment variables.
72114

73-
Start grepping by title and tags:
115+
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:
116+
117+
Here are a few examples:
74118

75119
```shell
76120
# run only the tests with "auth user" in the title
@@ -92,32 +136,7 @@ $ npx cypress run --env grepTags=@smoke,grepFilterSpecs=true
92136
$ npx cypress run --env grepUntagged=true
93137
```
94138

95-
## Videos
96-
97-
Watch the video [intro to cypress-grep](https://www.youtube.com/watch?v=HS-Px-Sghd8) which shows how this repository tags tests, uses [cypress-grep](https://github.com/cypress-io/cypress-grep) plugin, and sets up the TypeScript intelligent code completion.
98-
99-
You can also watch [How I organize pull request workflows](https://youtu.be/SFW7Ecj5TNE) where I show how the GitHub workflows in [.github/workflows](./.github/workflows) are organized to run the smoke tests first on pull request.
100-
101-
Watch the video [Filter Specs First When Using cypress-grep Plugin](https://youtu.be/adL7KzO5dR0)
102-
103-
Watch the video [Run All Tests That Have No Tags Using cypress-grep Plugin](https://youtu.be/CtU43GzaicI)
104-
105-
## Blog posts
106-
107-
- [Burning Tests with cypress-grep](https://glebbahmutov.com/blog/burning-tests/)
108-
- [Faster test execution with cypress-grep](https://glebbahmutov.com/blog/cypress-grep-filters/)
109-
110-
## Filters
111-
112-
You can filter tests to run using part of their title via `grep`, and via explicit tags via `grepTags` Cypress environment variables.
113-
114-
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:
115-
116-
```shell
117-
$ npx cypress run --env grep=login,grepTags=smoke
118-
```
119-
120-
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 [config file](https://docs.cypress.io/guides/references/configuration) to run only tests with the substring `viewport` in their names
139+
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
121140

122141
```json
123142
{
@@ -139,15 +158,7 @@ module.exports = (on, config) => {
139158

140159
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).
141160

142-
### Disable grep
143-
144-
If you specify the `grep` parameters inside the [config file](https://docs.cypress.io/guides/references/configuration), you can disable it from the command line
145-
146-
```
147-
$ npx cypress run --env grep=,grepTags=,burn=
148-
```
149-
150-
### grep by test title
161+
## Filter by test title
151162

152163
```shell
153164
# run all tests with "hello" in their title
@@ -156,14 +167,35 @@ $ npx cypress run --env grep=hello
156167
$ npx cypress run --env grep="hello world"
157168
```
158169

170+
### OR substring matching
171+
159172
You can pass multiple title substrings to match separating them with `;` character. Each substring is trimmed.
160173

161174
```shell
162175
# run all tests with "hello world" or "auth user" in their title
163176
$ npx cypress run --env grep="hello world; auth user"
164177
```
165178

166-
### negative filter
179+
### Test suites
180+
181+
The filter is also applied to the "describe" blocks. In that case, the tests look up if any of their outer suites are enabled.
182+
183+
```js
184+
describe('block for config', () => {
185+
it('should run', () => {})
186+
187+
it('should also work', () => {})
188+
})
189+
```
190+
191+
```
192+
# run any tests in the blocks including "config"
193+
--env grep=config
194+
```
195+
196+
**Note:** global function `describe` and `context` are aliases and both supported by this plugin.
197+
198+
### Invert filter
167199

168200
```shell
169201
# run all tests WITHOUT "hello world" in their title
@@ -172,6 +204,8 @@ $ npx cypress run --env grep="-hello world"
172204
$ npx cypress run --env grep="hello; -world"
173205
```
174206

207+
**Note:** An inverted name filter that matches a suite name does not exclude its tests.
208+
175209
## Filter with tags
176210

177211
You can select tests to run or skip using tags by passing `--env grepTags=...` value.
@@ -208,7 +242,66 @@ it('works as a string', { tags: 'config' }, () => {
208242

209243
You can run both of these tests using `--env grepTags=config` string.
210244

211-
### grepFilterSpecs
245+
### AND tags
246+
247+
Use `+` to require both tags to be present
248+
249+
```
250+
--env grepTags=@smoke+@fast
251+
```
252+
253+
### OR tags
254+
255+
You can run tests that match one tag or another using spaces. Make sure to quote the grep string!
256+
257+
```
258+
# run tests with tags "@slow" or "@critical" in their names
259+
--env grepTags='@slow @critical'
260+
```
261+
262+
### Test suites
263+
264+
The tags are also applied to the "describe" blocks. In that case, the tests look up if any of their outer suites are enabled.
265+
266+
```js
267+
describe('block with config tag', { tags: '@smoke' }, () => {})
268+
```
269+
270+
```
271+
# run any tests in the blocks having "@smoke" tag
272+
--env grepTags=@smoke
273+
# skip any blocks with "@smoke" tag
274+
--env grepTags=-@smoke
275+
```
276+
277+
See the [cypress/integration/describe-tags-spec.js](./cypress/integration/describe-tags-spec.js) file.
278+
279+
**Note:** global function `describe` and `context` are aliases and both supported by this plugin.
280+
281+
### Invert tag
282+
283+
You can skip running the tests with specific tag using the invert option: prefix the tag with the character `-`.
284+
285+
```
286+
# do not run any tests with tag "@slow"
287+
--env grepTags=-@slow
288+
```
289+
290+
If you want to run all tests with tag `@slow` but without tag `@smoke`:
291+
292+
```
293+
--env grepTags=@slow+-@smoke
294+
```
295+
296+
### Grep untagged tests
297+
298+
Sometimes you want to run only the tests without any tags, and these tests are inside the describe blocks without any tags.
299+
300+
```
301+
$ npx cypress run --env grepUntagged=true
302+
```
303+
304+
## Pre-filter specs (grepFilterSpecs)
212305

213306
By default, when using `grep` and `grepTags` all specs are executed, and inside each the filters are applied. This can be very wasteful, if only a few specs contain the `grep` in the test titles. Thus when doing the positive `grep`, you can pre-filter specs using the `grepFilterSpecs=true` parameter.
214307

@@ -220,11 +313,11 @@ $ npx cypress run --env grep="it loads",grepFilterSpecs=true
220313
$ npx cypress run --env grepTags=@smoke,grepFilterSpecs=true
221314
```
222315

223-
Note: this requires installing this plugin in your project's plugin file, see the [Install](#install).
316+
**Note 1:** this requires installing this plugin in your project's plugin file, see the [Install](#install).
224317

225-
Note 2: the `grepFilterSpecs` option is only compatible with the positive `grep` and `grepTags` options, not with the negative "!..." filter.
318+
**Note 2:** the `grepFilterSpecs` option is only compatible with the positive `grep` and `grepTags` options, not with the negative "!..." filter.
226319

227-
Note 3: if there are no files remaining after filtering, the plugin prints a warning and leaves all files unchanged to avoid the test runner erroring with "No specs found".
320+
**Note 3:** if there are no files remaining after filtering, the plugin prints a warning and leaves all files unchanged to avoid the test runner erroring with "No specs found".
228321

229322
**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:
230323

@@ -236,7 +329,7 @@ Note 3: if there are no files remaining after filtering, the plugin prints a war
236329
}
237330
```
238331

239-
### omit filtered tests
332+
## Omit filtered tests (grepOmitFiltered)
240333

241334
By default, all filtered tests are made _pending_ using `it.skip` method. If you want to completely omit them, pass the environment variable `grepOmitFiltered=true`.
242335

@@ -266,15 +359,27 @@ cypress run --env grep="works 2",grepOmitFiltered=true
266359
}
267360
```
268361

269-
### grep untagged tests
362+
## Disable grep
270363

271-
Sometimes you want to run only the tests without any tags, and these tests are inside the describe blocks without any tags.
364+
If you specify the `grep` parameters inside `cypress.json` file, you can disable it from the command line
272365

273366
```
274-
$ npx cypress run --env grepUntagged=true
367+
$ npx cypress run --env grep=,grepTags=,burn=
275368
```
276369

277-
### TypeScript users
370+
## Burn (repeat) tests
371+
372+
You can burn the filtered tests to make sure they are flake-free
373+
374+
```
375+
npx cypress run --env grep="hello world",burn=5
376+
```
377+
378+
You can pass the number of times to run the tests via environment name `burn` or `grepBurn` or `grep-burn`. Note, if a lot of tests match the grep and grep tags, a lot of tests will be burnt!
379+
380+
If you do not specify the "grep" or "grep tags" option, the "burn" will repeat _every_ test.
381+
382+
## TypeScript support
278383

279384
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:
280385

@@ -305,87 +410,6 @@ If you have `tsconfig.json` file, add this library to the types list
305410
}
306411
```
307412

308-
## Test suites
309-
310-
The tags are also applied to the "describe" blocks. In that case, the tests look up if any of their outer suites are enabled.
311-
312-
```js
313-
describe('block with config tag', { tags: '@smoke' }, () => {})
314-
```
315-
316-
```
317-
# run any tests in the blocks having "@smoke" tag
318-
--env grepTags=@smoke
319-
# skip any blocks with "@smoke" tag
320-
--env grepTags=-@smoke
321-
```
322-
323-
See the [cypress/integration/describe-tags-spec.js](./cypress/integration/describe-tags-spec.js) file.
324-
325-
**Note:** global function `describe` and `context` are aliases and both supported by this plugin.
326-
327-
### AND tags
328-
329-
Use `+` to require both tags to be present
330-
331-
```
332-
--env grepTags=@smoke+@fast
333-
```
334-
335-
### Invert tag
336-
337-
You can skip running the tests with specific tag using the invert option: prefix the tag with the character `-`.
338-
339-
```
340-
# do not run any tests with tag "@slow"
341-
--env grepTags=-@slow
342-
```
343-
344-
If you want to run all tests with tag `@slow` but without tag `@smoke`:
345-
346-
```
347-
--env grepTags=@slow+-@smoke
348-
```
349-
350-
### OR tags
351-
352-
You can run tests that match one tag or another using spaces. Make sure to quote the grep string!
353-
354-
```
355-
# run tests with tags "@slow" or "@critical" in their names
356-
--env grepTags='@slow @critical'
357-
```
358-
359-
### NOT tags
360-
361-
You can skip running the tests with specific tag, even if they have a tag that should run, using the not option: prefix the tag with `--`.
362-
363-
Note this is the same as appending `+-<tag to never run>` to each tag. May be useful with large number of tags.
364-
365-
If you want to run tests with tags `@slow` or `@regression` but without tag `@smoke`
366-
367-
```
368-
--env grepTags='@slow @regression --@smoke'
369-
```
370-
371-
which is equivalent to
372-
373-
```
374-
--env grepTags='@slow+-@smoke @regression+-@smoke'
375-
```
376-
377-
## Burn
378-
379-
You can repeat (burn) the filtered tests to make sure they are flake-free
380-
381-
```
382-
npx cypress run --env grep="hello world",burn=5
383-
```
384-
385-
You can pass the number of times to run the tests via environment name `burn` or `grepBurn` or `grep-burn`. Note, if a lot of tests match the grep and grep tags, a lot of tests will be burnt!
386-
387-
If you do not specify the "grep" or "grep tags" option, the "burn" will repeat _every_ test.
388-
389413
## General advice
390414

391415
- keep it simple.
@@ -536,6 +560,21 @@ The above scenario was confusing - did you want to find all tests with title con
536560
--env grep=hello,grepTags=smoke
537561
```
538562

563+
## Videos & Blog Posts
564+
565+
Watch the video [intro to cypress-grep](https://www.youtube.com/watch?v=HS-Px-Sghd8) which shows how this repository tags tests, uses [cypress-grep](https://github.com/cypress-io/cypress-grep) plugin, and sets up the TypeScript intelligent code completion.
566+
567+
You can also watch [How I organize pull request workflows](https://youtu.be/SFW7Ecj5TNE) where I show how the GitHub workflows in [.github/workflows](./.github/workflows) are organized to run the smoke tests first on pull request.
568+
569+
Watch the video [Filter Specs First When Using cypress-grep Plugin](https://youtu.be/adL7KzO5dR0)
570+
571+
Watch the video [Run All Tests That Have No Tags Using cypress-grep Plugin](https://youtu.be/CtU43GzaicI)
572+
573+
## Blog posts
574+
575+
- [Burning Tests with cypress-grep](https://glebbahmutov.com/blog/burning-tests/)
576+
- [Faster test execution with cypress-grep](https://glebbahmutov.com/blog/cypress-grep-filters/)
577+
539578
## Small print
540579

541580
Author: Gleb Bahmutov &lt;gleb.bahmutov@gmail.com&gt; &copy; 2021

0 commit comments

Comments
 (0)