Skip to content

Commit e38e289

Browse files
AtofStrykerAtofStryker
committed
breaking: release version 6.0.0 of @cypress/grep
BREAKING CHANGE: use Cypress.expose() instead of Cypress.env(), which requires a peer dependency on Cypress 15.10.0
1 parent 1d7c6c3 commit e38e289

File tree

4 files changed

+80
-65
lines changed

4 files changed

+80
-65
lines changed

‎npm/grep/README.md‎

Lines changed: 43 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -91,19 +91,19 @@ export default defineConfig({
9191
Run tests with "login" in the title:
9292

9393
```shell
94-
npx cypress run --env grep="login"
94+
npx cypress run --expose grep="login"
9595
```
9696

9797
Run tests with "user authentication" in the title:
9898

9999
```shell
100-
npx cypress run --env grep="user authentication"
100+
npx cypress run --expose grep="user authentication"
101101
```
102102

103103
Multiple title patterns (OR logic):
104104

105105
```shell
106-
npx cypress run --env grep="login; logout; signup"
106+
npx cypress run --expose grep="login; logout; signup"
107107
```
108108

109109
### Filter by Tags
@@ -134,39 +134,39 @@ Then run by tags:
134134
Run tests with @smoke tag:
135135

136136
```shell
137-
npx cypress run --env grepTags="@smoke"
137+
npx cypress run --expose grepTags="@smoke"
138138
```
139139

140140
Run tests with @smoke OR @critical tags:
141141

142142
```shell
143-
npx cypress run --env grepTags="@smoke @critical"
143+
npx cypress run --expose grepTags="@smoke @critical"
144144
```
145145

146146
Run tests with BOTH @smoke AND @critical tags:
147147

148148
```shell
149-
npx cypress run --env grepTags="@smoke+@critical"
149+
npx cypress run --expose grepTags="@smoke+@critical"
150150
```
151151

152152
Run tests with @smoke tag but NOT @slow tag:
153153

154154
```shell
155-
npx cypress run --env grepTags="@smoke+-@slow"
155+
npx cypress run --expose grepTags="@smoke+-@slow"
156156
```
157157

158158
### Combine Title and Tag Filters
159159

160160
Run tests with "login" in title AND tagged @smoke:
161161

162162
```shell
163-
npx cypress run --env grep="login",grepTags="@smoke"
163+
npx cypress run --expose grep="login",grepTags="@smoke"
164164
```
165165

166166
Run tests with "user" in title AND tagged @critical OR @smoke:
167167

168168
```shell
169-
npx cypress run --env grep="user",grepTags="@critical @smoke"
169+
npx cypress run --expose grep="user",grepTags="@critical @smoke"
170170
```
171171

172172
## Advanced Features
@@ -178,21 +178,21 @@ Skip loading specs that don't contain matching tests (requires plugin setup):
178178
Only run specs containing tests with "login" in title:
179179

180180
```shell
181-
npx cypress run --env grep="login",grepFilterSpecs=true
181+
npx cypress run --expose grep="login",grepFilterSpecs=true
182182
```
183183

184184
Only run specs containing tests tagged @smoke:
185185

186186
```shell
187-
npx cypress run --env grepTags="@smoke",grepFilterSpecs=true
187+
npx cypress run --expose grepTags="@smoke",grepFilterSpecs=true
188188
```
189189

190190
### Omit Filtered Tests
191191

192192
By default, filtered tests are marked as pending. To completely omit them:
193193

194194
```shell
195-
npx cypress run --env grep="login",grepOmitFiltered=true
195+
npx cypress run --expose grep="login",grepOmitFiltered=true
196196
```
197197

198198
### Test Burning (Repeat Tests)
@@ -202,41 +202,41 @@ Run filtered tests multiple times to catch flaky behavior:
202202
Run matching tests 5 times:
203203

204204
```shell
205-
npx cypress run --env grep="login",burn=5
205+
npx cypress run --expose grep="login",burn=5
206206
```
207207

208208
Run all tests 10 times:
209209

210210
```shell
211-
npx cypress run --env burn=10
211+
npx cypress run --expose burn=10
212212
```
213213

214214
### Inverted Filters
215215

216216
Run tests WITHOUT "slow" in the title:
217217

218218
```shell
219-
npx cypress run --env grep="-slow"
219+
npx cypress run --expose grep="-slow"
220220
```
221221

222222
Run tests WITHOUT @slow tag:
223223

224224
```shell
225-
npx cypress run --env grepTags="-@slow"
225+
npx cypress run --expose grepTags="-@slow"
226226
```
227227

228228
Complex combinations:
229229

230230
```shell
231-
npx cypress run --env grep="login; -slow",grepTags="@smoke+-@regression"
231+
npx cypress run --expose grep="login; -slow",grepTags="@smoke+-@regression"
232232
```
233233

234234
### Run Untagged Tests
235235

236236
Run only tests without any tags:
237237

238238
```shell
239-
npx cypress run --env grepUntagged=true
239+
npx cypress run --expose grepUntagged=true
240240
```
241241

242242
## Configuration Examples
@@ -248,7 +248,7 @@ import { defineConfig } from 'cypress'
248248
import { plugin as cypressGrepPlugin } from '@cypress/grep/plugin'
249249

250250
export default defineConfig({
251-
env: {
251+
expose: {
252252
// Always filter by viewport tests
253253
grep: "viewport",
254254
// Always enable spec filtering
@@ -270,10 +270,10 @@ export default defineConfig({
270270
```json
271271
{
272272
"scripts": {
273-
"cy:smoke": "cypress run --env grepTags=@smoke",
274-
"cy:critical": "cypress run --env grepTags=@critical",
275-
"cy:fast": "cypress run --env grepTags=@fast",
276-
"cy:burn": "cypress run --env grepTags=@smoke,burn=5"
273+
"cy:smoke": "cypress run --expose grepTags=@smoke",
274+
"cy:critical": "cypress run --expose grepTags=@critical",
275+
"cy:fast": "cypress run --expose grepTags=@fast",
276+
"cy:burn": "cypress run --expose grepTags=@smoke,burn=5"
277277
}
278278
}
279279
```
@@ -338,7 +338,7 @@ Cypress.grep()
338338

339339
1. **Spec Loading**: When not using `grepFilterSpecs`, all spec files are loaded before filtering occurs
340340
2. **Inverted Filters**: Negative filters (`-tag`, `-title`) are not compatible with `grepFilterSpecs`
341-
3. **Runtime Changes**: Cannot change grep filters at runtime using `Cypress.env()`
341+
3. **Runtime Changes**: Cannot change grep filters at runtime using `Cypress.expose()`
342342
4. **Cloud Recordings**: Filtered tests may still appear in Cypress Cloud recordings as pending tests
343343

344344
## Best Practices
@@ -369,7 +369,7 @@ it('should work', { tags: ['@smoke', '@fast'] }, () => {
369369
1. Run smoke tests first:
370370

371371
```shell
372-
npx cypress run --env grepTags="@smoke"
372+
npx cypress run --expose grepTags="@smoke"
373373
```
374374

375375
2. If smoke tests pass, run all tests:
@@ -381,11 +381,11 @@ npx cypress run
381381
3. For debugging, run specific test groups:
382382

383383
```shell
384-
npx cypress run --env grep="user management"
384+
npx cypress run --expose grep="user management"
385385
```
386386

387387
```shell
388-
npx cypress run --env grepTags="@critical"
388+
npx cypress run --expose grepTags="@critical"
389389
```
390390

391391
### Performance Tips
@@ -403,7 +403,7 @@ Enable debug logging to see what's happening:
403403
Terminal debug (for plugin):
404404

405405
```shell
406-
DEBUG=@cypress/grep npx cypress run --env grep="login"
406+
DEBUG=@cypress/grep npx cypress run --expose grep="login"
407407
```
408408

409409
Browser debug (for support file):
@@ -422,6 +422,21 @@ Then refresh and run tests.
422422

423423
## Migration
424424

425+
### From v5 to v6
426+
427+
`Cypress.env()` is deprecated in Cypress 15.10.0. For public configuration, the API has been replaced with `Cypress.expose()`
428+
429+
To migrate, change your `--env`/`-e` CLI arguments from
430+
```sh
431+
npx cypress run --env grepTags="tag1 tag2"
432+
```
433+
434+
to the following to use `--expose`/`-x`
435+
```sh
436+
npx cypress run --expose grepTags="tag1 tag2"
437+
```
438+
439+
425440
### From v4 to v5
426441

427442
The support file registration and plugin have changed their export signature, meaning:

‎npm/grep/cypress.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import debug from 'debug'
88
const debugInstance = debug('cypress:grep:compare-results')
99

1010
export default defineConfig({
11-
allowCypressEnv: true,
11+
allowCypressEnv: false,
1212
e2e: {
1313
defaultCommandTimeout: 1000,
1414
setupNodeEvents (on, config) {

‎npm/grep/package.json‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,32 @@
77
"cypress:open": "node ../../scripts/cypress.js open",
88
"test": "vitest",
99
"test-debug": "vitest --inspect-brk --no-file-parallelism --test-timeout=0",
10-
"and": "PROJECT_NAME=and node ../../scripts/cypress.js run --env grep='Test 2',grepTags='smoke+high' --config specPattern='**/tags/*.cy.ts'",
11-
"and:not": "PROJECT_NAME=and-not node ../../scripts/cypress.js run --env grep='Test 2',grepTags='smoke+-high' --config specPattern='**/tags/*.cy.ts'",
12-
"burn": "PROJECT_NAME=burn node ../../scripts/cypress.js run --env burn=5 --config specPattern='**/burn.cy.ts'",
10+
"and": "PROJECT_NAME=and node ../../scripts/cypress.js run --expose grep='Test 2',grepTags='smoke+high' --config specPattern='**/tags/*.cy.ts'",
11+
"and:not": "PROJECT_NAME=and-not node ../../scripts/cypress.js run --expose grep='Test 2',grepTags='smoke+-high' --config specPattern='**/tags/*.cy.ts'",
12+
"burn": "PROJECT_NAME=burn node ../../scripts/cypress.js run --expose burn=5 --config specPattern='**/burn.cy.ts'",
1313
"each": "PROJECT_NAME=each node ../../scripts/cypress.js run --config specPattern='**/each.cy.ts'",
14-
"filter:specs": "PROJECT_NAME=filter-specs node ../../scripts/cypress.js run --env grep='Test 2',grepFilterSpecs=true --config specPattern='**/tags/*.cy.ts'",
14+
"filter:specs": "PROJECT_NAME=filter-specs node ../../scripts/cypress.js run --expose grep='Test 2',grepFilterSpecs=true --config specPattern='**/tags/*.cy.ts'",
1515
"grep": "PROJECT_NAME=grep node ../../scripts/cypress.js run --config specPattern='**/grep-task.cy.ts'",
16-
"inverted": "PROJECT_NAME=inverted node ../../scripts/cypress.js run --env grep='-Test 2' --config specPattern='**/tags/*.cy.ts'",
16+
"inverted": "PROJECT_NAME=inverted node ../../scripts/cypress.js run --expose grep='-Test 2' --config specPattern='**/tags/*.cy.ts'",
1717
"lint": "eslint",
1818
"multiple-registrations": "PROJECT_NAME=multiple-registrations node ../../scripts/cypress.js run --config specPattern='**/multiple-registrations.cy.ts'",
19-
"omit:specs": "PROJECT_NAME=omit-specs node ../../scripts/cypress.js run --env grep='Test 2',grepOmitFiltered=true --config specPattern='**/tags/*.cy.ts'",
20-
"or": "PROJECT_NAME=or node ../../scripts/cypress.js run --env grep='Test 1',grepTags='regression high' --config specPattern='**/tags/*.cy.ts'",
19+
"omit:specs": "PROJECT_NAME=omit-specs node ../../scripts/cypress.js run --expose grep='Test 2',grepOmitFiltered=true --config specPattern='**/tags/*.cy.ts'",
20+
"or": "PROJECT_NAME=or node ../../scripts/cypress.js run --expose grep='Test 1',grepTags='regression high' --config specPattern='**/tags/*.cy.ts'",
2121
"skip": "PROJECT_NAME=skip node ../../scripts/cypress.js run --config specPattern='**/*skip.cy.ts'",
22-
"tags:inverted": "PROJECT_NAME=tag-inverted node ../../scripts/cypress.js run --env grepTags='-regression' --config specPattern='**/tags/*.cy.ts'",
23-
"tags": "PROJECT_NAME=tags node ../../scripts/cypress.js run --env grepTags=smoke --config specPattern='**/tags/*.cy.ts'",
24-
"tags:and": "PROJECT_NAME=tags-and node ../../scripts/cypress.js run --env grepTags='smoke+high' --config specPattern='**/tags/*.cy.ts'",
25-
"tags:and:not": "PROJECT_NAME=tags-and-not node ../../scripts/cypress.js run --env grepTags='smoke+-high' --config specPattern='**/tags/*.cy.ts'",
26-
"tags:before": "PROJECT_NAME=tags-before node ../../scripts/cypress.js run --env grepTags=@staging --config specPattern='**/before.cy.ts'",
27-
"tags:config": "PROJECT_NAME=tags-config node ../../scripts/cypress.js run --env grepTags=config --config specPattern='**/config-tags.cy.ts'",
28-
"tags:describe": "PROJECT_NAME=tags-describe node ../../scripts/cypress.js run --env grepTags=@smoke --config specPattern='**/describe-tags.cy.ts'",
29-
"tags:filter:specs": "PROJECT_NAME=tags-filter-specs node ../../scripts/cypress.js run --env grepTags='regression',grepFilterSpecs=true --config specPattern='**/tags/*.cy.ts'",
30-
"tags:inherit": "PROJECT_NAME=tags-inherit node ../../scripts/cypress.js run --env grepTags=@screen-b --config specPattern='**/inherits-tag.cy.ts'",
31-
"tags:nested-describe": "PROJECT_NAME=tags-nested-describe node ../../scripts/cypress.js run --env grepTags='@smoke @integration' --config specPattern='**/nested-describe.cy.ts'",
32-
"tags:omit:specs": "PROJECT_NAME=tags-omit-specs node ../../scripts/cypress.js run --env grepTags='regression',grepOmitFiltered=true --config specPattern='**/tags/*.cy.ts'",
33-
"tags:or": "PROJECT_NAME=tags-or node ../../scripts/cypress.js run --env grepTags='regression high' --config specPattern='**/tags/*.cy.ts'",
34-
"this": "PROJECT_NAME=this node ../../scripts/cypress.js run --env grep='this context' --config specPattern='**/this.cy.ts'",
35-
"untagged": "PROJECT_NAME=untagged node ../../scripts/cypress.js run --env grepUntagged=true --config specPattern='**/tags/*.cy.ts'"
22+
"tags:inverted": "PROJECT_NAME=tag-inverted node ../../scripts/cypress.js run --expose grepTags='-regression' --config specPattern='**/tags/*.cy.ts'",
23+
"tags": "PROJECT_NAME=tags node ../../scripts/cypress.js run --expose grepTags=smoke --config specPattern='**/tags/*.cy.ts'",
24+
"tags:and": "PROJECT_NAME=tags-and node ../../scripts/cypress.js run --expose grepTags='smoke+high' --config specPattern='**/tags/*.cy.ts'",
25+
"tags:and:not": "PROJECT_NAME=tags-and-not node ../../scripts/cypress.js run --expose grepTags='smoke+-high' --config specPattern='**/tags/*.cy.ts'",
26+
"tags:before": "PROJECT_NAME=tags-before node ../../scripts/cypress.js run --expose grepTags=@staging --config specPattern='**/before.cy.ts'",
27+
"tags:config": "PROJECT_NAME=tags-config node ../../scripts/cypress.js run --expose grepTags=config --config specPattern='**/config-tags.cy.ts'",
28+
"tags:describe": "PROJECT_NAME=tags-describe node ../../scripts/cypress.js run --expose grepTags=@smoke --config specPattern='**/describe-tags.cy.ts'",
29+
"tags:filter:specs": "PROJECT_NAME=tags-filter-specs node ../../scripts/cypress.js run --expose grepTags='regression',grepFilterSpecs=true --config specPattern='**/tags/*.cy.ts'",
30+
"tags:inherit": "PROJECT_NAME=tags-inherit node ../../scripts/cypress.js run --expose grepTags=@screen-b --config specPattern='**/inherits-tag.cy.ts'",
31+
"tags:nested-describe": "PROJECT_NAME=tags-nested-describe node ../../scripts/cypress.js run --expose grepTags='@smoke @integration' --config specPattern='**/nested-describe.cy.ts'",
32+
"tags:omit:specs": "PROJECT_NAME=tags-omit-specs node ../../scripts/cypress.js run --expose grepTags='regression',grepOmitFiltered=true --config specPattern='**/tags/*.cy.ts'",
33+
"tags:or": "PROJECT_NAME=tags-or node ../../scripts/cypress.js run --expose grepTags='regression high' --config specPattern='**/tags/*.cy.ts'",
34+
"this": "PROJECT_NAME=this node ../../scripts/cypress.js run --expose grep='this context' --config specPattern='**/this.cy.ts'",
35+
"untagged": "PROJECT_NAME=untagged node ../../scripts/cypress.js run --expose grepUntagged=true --config specPattern='**/tags/*.cy.ts'"
3636
},
3737
"dependencies": {
3838
"debug": "^4.3.4",
@@ -46,7 +46,7 @@
4646
"typescript": "~5.4.5"
4747
},
4848
"peerDependencies": {
49-
"cypress": ">=10"
49+
"cypress": ">=15.10.0"
5050
},
5151
"exports": {
5252
".": {

‎npm/grep/src/register.ts‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,27 +21,27 @@ export function register (): void {
2121
// define Cypress.grep function
2222
if (!Cypress.grep) {
2323
Cypress.grep = function grep (grep?: string, tags?: string, burn?: string): void {
24-
Cypress.env('grep', grep)
25-
Cypress.env('grepTags', tags)
26-
Cypress.env('grepBurn', burn)
27-
Cypress.env('grep-tags', null)
28-
Cypress.env('grep-burn', null)
29-
Cypress.env('burn', null)
24+
Cypress.expose('grep', grep)
25+
Cypress.expose('grepTags', tags)
26+
Cypress.expose('grepBurn', burn)
27+
Cypress.expose('grep-tags', null)
28+
Cypress.expose('grep-burn', null)
29+
Cypress.expose('burn', null)
3030

3131
debugInstance('set new grep to "%o" restarting tests', { grep, tags, burn })
3232
restartTests()
3333
}
3434
}
3535

36-
let grep: string | undefined = Cypress.env('grep')
36+
let grep: string | undefined = Cypress.expose('grep')
3737

3838
if (grep) {
3939
grep = String(grep).trim()
4040
}
4141

42-
const grepTags: string | undefined = Cypress.env('grepTags') || Cypress.env('grep-tags')
43-
const burnSpecified: string | undefined = Cypress.env('grepBurn') || Cypress.env('grep-burn') || Cypress.env('burn')
44-
const grepUntagged: string | undefined = Cypress.env('grepUntagged') || Cypress.env('grep-untagged')
42+
const grepTags: string | undefined = Cypress.expose('grepTags') || Cypress.expose('grep-tags')
43+
const burnSpecified: string | undefined = Cypress.expose('grepBurn') || Cypress.expose('grep-burn') || Cypress.expose('burn')
44+
const grepUntagged: string | undefined = Cypress.expose('grepUntagged') || Cypress.expose('grep-untagged')
4545

4646
if (!grep && !grepTags && !burnSpecified && !grepUntagged) {
4747
debugInstance('Nothing to grep, version %s', version)
@@ -50,13 +50,13 @@ export function register (): void {
5050
}
5151

5252
const grepBurn: number =
53-
Cypress.env('grepBurn') ||
54-
Cypress.env('grep-burn') ||
55-
Cypress.env('burn') ||
53+
Cypress.expose('grepBurn') ||
54+
Cypress.expose('grep-burn') ||
55+
Cypress.expose('burn') ||
5656
1
5757

5858
const omitFiltered: boolean =
59-
Cypress.env('grepOmitFiltered') || Cypress.env('grep-omit-filtered')
59+
Cypress.expose('grepOmitFiltered') || Cypress.expose('grep-omit-filtered')
6060

6161
debugInstance('grep %o', { grep, grepTags, grepBurn, omitFiltered, version })
6262
if (!Cypress._.isInteger(grepBurn) || grepBurn < 1) {

0 commit comments

Comments
 (0)