Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
cypress: cypress-io/cypress@3.4.2
Use cypress
elements in your existing workflows and jobs.
Opt-in to use of uncertified orbs on your organization’s Security settings page.
Run Cypress tests using specified browser. The CircleCI Browser Tools orb at https://circleci.com/developer/orbs/orb/circleci/browser-tools#commands-install-browser-tools currently supports Chrome & Firefox. See https://circleci.com/developer/orbs/orb/cypress-io/cypress#usage-edge, for Microsoft Edge support.
1
2
3
4
5
6
7
8
9
10
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx cypress run --browser chrome
install-browsers: true
start-command: npm run start:dev
Runs Cypress tests and and invalidate the current cache
1
2
3
4
5
6
7
8
9
10
11
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-cache-key: custom-cypress-cache-v1-{{ arch }}-{{ checksum "package.json" }}
cypress-cache-path: ~/.cache/custom-dir/Cypress
cypress-command: npx cypress run --component
node-cache-version: v2
Runs Cypress tests in your own job using commands
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
jobs:
install-and-persist:
executor: cypress/default
steps:
- cypress/install
- persist_to_workspace:
paths:
- .cache/Cypress
- project
root: ~/
run-tests-in-parallel:
executor: cypress/default
parallelism: 8
steps:
- attach_workspace:
at: ~/
- cypress/run-tests:
cypress-command: npx cypress run --component --parallel --record
workflows:
use-my-orb:
jobs:
- install-and-persist:
name: Install & Persist To Workspace
- run-tests-in-parallel:
name: Run Tests in Parallel
requires:
- Install & Persist To Workspace
Runs Cypress component tests. Installs dependencies and caches NPM modules and the Cypress binary.
1
2
3
4
5
6
7
8
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx cypress run --component
Runs Cypress tests and install dependencies using a custom install and post-install script.
1
2
3
4
5
6
7
8
9
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
install-command: npm install && echo hello
post-install: npm run build
Run Cypress tests in Microsoft Edge.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
jobs:
edge-test:
executor: cypress-browsers
steps:
- cypress/install
- cypress/run-tests:
cypress-command: npx cypress run --browser edge
start-command: npm run start:dev
workflows:
use-my-orb:
jobs:
- edge-test
Runs Cypress tests in a monorepo or when your Cypress folder is somewhere other than the root directory.
1
2
3
4
5
6
7
8
9
10
11
12
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-cache-key: >-
cypress-cache-{{ arch }}-{{ checksum "libs/shared-ui/package.json"
}}
cypress-command: npx cypress run --component
working-directory: libs/shared-ui
Run Cypress tests using the cypress/default executor with a specified node version.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
jobs:
run-cypress-in-specified-node-version:
executor:
name: cypress/default
node-version: '20.6'
steps:
- cypress/install:
package-manager: npm
- cypress/run-tests:
cypress-command: npx cypress run
start-command: npm run start:dev
workflows:
use-my-orb:
jobs:
- run-cypress-in-specified-node-version:
name: Run Cypress in Node 20
Runs Cypress tests using pnpm. Installs dependencies and caches NPM modules and the Cypress binary.
1
2
3
4
5
6
7
8
9
10
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
install-command: pnpm install --frozen-lockfile
package-manager: pnpm
start-command: pnpm start
Runs Cypress end-to-end tests in parallel and record results to Cypress Cloud. Installs dependencies and caches NPM modules and the Cypress binary.
1
2
3
4
5
6
7
8
9
10
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx cypress run --parallel --record
parallelism: 3
start-command: npm run start
Runs Cypress end-to-end tests without recording results to Cypress Cloud. Installs dependencies and caches NPM modules and the Cypress binary.
1
2
3
4
5
6
7
8
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
start-command: npm run start
Runs Cypress tests after waiting for the local server to start using the wait-on package (https://github.com/jeffbski/wait-on).
1
2
3
4
5
6
7
8
9
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx wait-on@latest http://localhost:8080 && npx cypress run
start-command: npm start
Runs Cypress tests using yarn. Installs dependencies and caches NPM modules and the Cypress binary.
1
2
3
4
5
6
7
8
9
version: '2.1'
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
package-manager: yarn
start-command: yarn start
A single, complete job to run Cypress end-to-end tests in your application.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
cypress-cache-key | Cache key used to cache the Cypress binary. | No | cypress-cache-{{ arch }}-{{ checksum "package.json" }} | string |
cypress-cache-path | By default, this will cache the '~/.cache/Cypress' directory so that the Cypress binary is cached. You can override this by providing your own cache path.
| No | ~/.cache/Cypress | string |
cypress-command | Command used to run your Cypress tests | No | npx cypress run | string |
include-branch-in-node-cache-key | If true, this cache will only apply to runs within the same branch. (Adds -{{ .Branch }}- to the node cache key)
| No | false | boolean |
install-browsers | Cypress runs by default in the Electron browser. Use this flag to install additional browsers to run your tests in.
This is only needed if you are passing the `--browser` flag in your `cypress-command`.
This parameter leverages the `circleci/browser-tools` orb and includes Chrome and FireFox.
If you need additional browser support you can set this to false and use an executor with a docker image
that includes the browsers of your choosing. See https://hub.docker.com/r/cypress/browsers/tags
| No | false | boolean |
install-command | Overrides the default NPM command (npm ci) | No | '' | string |
node-cache-version | Change the default node cache version if you need to clear the cache for any reason. | No | v1 | string |
node-version | The version of Node to run your tests with.
| No | 18.16.1 | string |
package-manager | Select the default node package manager to use. NPM v5+ Required. | No | npm | enum |
parallelism | Number of Circle machines to use for load balancing, min 1
(requires `parallel` and `record` flags in your `cypress-command`)
| No | 1 | integer |
post-install | Additional commands to run after running install but before verifying Cypress and saving cache.
| No | '' | string |
skip-checkout | Whether to skip code checkout | No | false | boolean |
start-command | Command used to start your local dev server for Cypress to tests against | No | '' | string |
working-directory | Directory containing package.json | No | '' | string |
Installs your application's node modules and cypress dependencies
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
cypress-cache-key | Cache key used to cache the Cypress binary. | No | cypress-cache-{{ arch }}-{{ checksum "package.json" }} | string |
cypress-cache-path | By default, this will cache the '~/.cache/Cypress' directory so that the Cypress binary is cached. You can override this by providing your own cache path.
| No | ~/.cache/Cypress | string |
include-branch-in-node-cache-key | If true, this cache will only apply to runs within the same branch. (Adds -{{ .Branch }}- to the node cache key)
| No | false | boolean |
install-browsers | Cypress runs by default in the Electron browser. Use this flag to install additional browsers to run your tests in.
This is only needed if you are passing the `--browser` flag in your `cypress-command`.
This parameter leverages the `circleci/browser-tools` orb and includes Chrome and FireFox.
If you need additional browser support you can set this to false and use an executor with a docker image
that includes the browsers of your choosing. See https://hub.docker.com/r/cypress/browsers/tags
| No | false | boolean |
install-command | Overrides the default NPM command (npm ci) | No | '' | string |
node-cache-version | Change the default node cache version if you need to clear the cache for any reason. | No | v1 | string |
package-manager | Select the default node package manager to use. NPM v5+ Required. | No | npm | enum |
post-install | Additional commands to run after running install but before verifying Cypress and saving cache.
| No | '' | string |
skip-checkout | Allow skipping the `checkout` command | No | false | boolean |
working-directory | Directory containing package.json | No | '' | string |
A single, complete job to run Cypress tests
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
cypress-command | Command used to run your Cypress tests | No | npx cypress run | string |
start-command | Command used to start your local dev server for Cypress to tests against | No | '' | string |
working-directory | Directory containing package.json | No | . | string |
Single Docker container used to run Cypress Tests
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
node-version | The version of Node to run your tests with.
| No | 18.16.1 | string |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
Run your Cypress.io end-to-end & component tests without spending time configuring CircleCI
display:
home_url: https://cypress.io
source_url: https://github.com/cypress-io/circleci-orb
orbs:
browser-tools: circleci/browser-tools@1.4.8
node: circleci/node@6
commands:
install:
description: |
Installs your application's node modules and cypress dependencies
parameters:
cypress-cache-key:
default: cypress-cache-{{ arch }}-{{ checksum "package.json" }}
description: Cache key used to cache the Cypress binary.
type: string
cypress-cache-path:
default: ~/.cache/Cypress
description: |
By default, this will cache the '~/.cache/Cypress' directory so that the Cypress binary is cached. You can override this by providing your own cache path.
type: string
include-branch-in-node-cache-key:
default: false
description: |
If true, this cache will only apply to runs within the same branch. (Adds -{{ .Branch }}- to the node cache key)
type: boolean
install-browsers:
default: false
description: |
Cypress runs by default in the Electron browser. Use this flag to install additional browsers to run your tests in.
This is only needed if you are passing the `--browser` flag in your `cypress-command`.
This parameter leverages the `circleci/browser-tools` orb and includes Chrome and FireFox.
If you need additional browser support you can set this to false and use an executor with a docker image
that includes the browsers of your choosing. See https://hub.docker.com/r/cypress/browsers/tags
type: boolean
install-command:
default: ""
description: Overrides the default NPM command (npm ci)
type: string
node-cache-version:
default: v1
description: Change the default node cache version if you need to clear the cache for any reason.
type: string
package-manager:
default: npm
description: Select the default node package manager to use. NPM v5+ Required.
enum:
- npm
- yarn
- yarn-berry
- pnpm
type: enum
post-install:
default: ""
description: |
Additional commands to run after running install but before verifying Cypress and saving cache.
type: string
skip-checkout:
default: false
description: Allow skipping the `checkout` command
type: boolean
working-directory:
default: ""
description: Directory containing package.json
type: string
steps:
- unless:
condition: << parameters.skip-checkout >>
steps:
- checkout
- when:
condition: << parameters.install-browsers >>
steps:
- browser-tools/install-browser-tools
- restore_cache:
key: << parameters.cypress-cache-key >>
name: Restore Cypress cache
- when:
condition:
and:
- equal:
- pnpm
- << parameters.package-manager >>
steps:
- node/install:
install-pnpm: true
- node/install-packages:
app-dir: << parameters.working-directory >>
cache-version: << parameters.node-cache-version >>
include-branch-in-cache-key: << parameters.include-branch-in-node-cache-key >>
override-ci-command: << parameters.install-command >>
pkg-manager: << parameters.package-manager >>
- when:
condition: << parameters.post-install >>
steps:
- run:
command: << parameters.post-install >>
name: Post Install Script
working_directory: << parameters.working-directory >>
- run:
command: npx cypress verify
name: Verify Cypress
working_directory: << parameters.working-directory >>
- save_cache:
key: << parameters.cypress-cache-key >>
name: Save Cypress Binary
paths:
- << parameters.cypress-cache-path >>
run-tests:
description: |
A single, complete job to run Cypress tests
parameters:
cypress-command:
default: npx cypress run
description: Command used to run your Cypress tests
type: string
start-command:
default: ""
description: Command used to start your local dev server for Cypress to tests against
type: string
working-directory:
default: .
description: Directory containing package.json
type: string
steps:
- when:
condition: << parameters.start-command >>
steps:
- run:
background: true
command: << parameters.start-command >>
name: Start Server
working_directory: << parameters.working-directory >>
- run:
command: << parameters.cypress-command >>
name: Run Cypress
working_directory: << parameters.working-directory >>
- store_artifacts:
path: << parameters.working-directory >>/cypress/videos
- store_artifacts:
path: << parameters.working-directory >>/cypress/screenshots
executors:
default:
description: |
Single Docker container used to run Cypress Tests
docker:
- image: cimg/node:<< parameters.node-version >>-browsers
parameters:
node-version:
default: 18.16.1
description: |
The version of Node to run your tests with.
type: string
jobs:
run:
description: |
A single, complete job to run Cypress end-to-end tests in your application.
executor:
name: default
node-version: << parameters.node-version >>
parallelism: << parameters.parallelism >>
parameters:
cypress-cache-key:
default: cypress-cache-{{ arch }}-{{ checksum "package.json" }}
description: Cache key used to cache the Cypress binary.
type: string
cypress-cache-path:
default: ~/.cache/Cypress
description: |
By default, this will cache the '~/.cache/Cypress' directory so that the Cypress binary is cached. You can override this by providing your own cache path.
type: string
cypress-command:
default: npx cypress run
description: Command used to run your Cypress tests
type: string
include-branch-in-node-cache-key:
default: false
description: |
If true, this cache will only apply to runs within the same branch. (Adds -{{ .Branch }}- to the node cache key)
type: boolean
install-browsers:
default: false
description: |
Cypress runs by default in the Electron browser. Use this flag to install additional browsers to run your tests in.
This is only needed if you are passing the `--browser` flag in your `cypress-command`.
This parameter leverages the `circleci/browser-tools` orb and includes Chrome and FireFox.
If you need additional browser support you can set this to false and use an executor with a docker image
that includes the browsers of your choosing. See https://hub.docker.com/r/cypress/browsers/tags
type: boolean
install-command:
default: ""
description: Overrides the default NPM command (npm ci)
type: string
node-cache-version:
default: v1
description: Change the default node cache version if you need to clear the cache for any reason.
type: string
node-version:
default: 18.16.1
description: |
The version of Node to run your tests with.
type: string
package-manager:
default: npm
description: Select the default node package manager to use. NPM v5+ Required.
enum:
- npm
- yarn
- yarn-berry
- pnpm
type: enum
parallelism:
default: 1
description: |
Number of Circle machines to use for load balancing, min 1
(requires `parallel` and `record` flags in your `cypress-command`)
type: integer
post-install:
default: ""
description: |
Additional commands to run after running install but before verifying Cypress and saving cache.
type: string
skip-checkout:
default: false
description: Whether to skip code checkout
type: boolean
start-command:
default: ""
description: Command used to start your local dev server for Cypress to tests against
type: string
working-directory:
default: ""
description: Directory containing package.json
type: string
steps:
- install:
cypress-cache-key: << parameters.cypress-cache-key >>
cypress-cache-path: << parameters.cypress-cache-path >>
include-branch-in-node-cache-key: << parameters.include-branch-in-node-cache-key >>
install-browsers: << parameters.install-browsers >>
install-command: << parameters.install-command >>
node-cache-version: << parameters.node-cache-version >>
package-manager: << parameters.package-manager >>
post-install: << parameters.post-install >>
skip-checkout: << parameters.skip-checkout >>
working-directory: << parameters.working-directory >>
- run-tests:
cypress-command: << parameters.cypress-command >>
start-command: << parameters.start-command >>
working-directory: << parameters.working-directory >>
examples:
browser:
description: |
Run Cypress tests using specified browser. The CircleCI Browser Tools orb at https://circleci.com/developer/orbs/orb/circleci/browser-tools#commands-install-browser-tools currently supports Chrome & Firefox. See https://circleci.com/developer/orbs/orb/cypress-io/cypress#usage-edge, for Microsoft Edge support.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx cypress run --browser chrome
install-browsers: true
start-command: npm run start:dev
caching:
description: |
Runs Cypress tests and and invalidate the current cache
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-cache-key: custom-cypress-cache-v1-{{ arch }}-{{ checksum "package.json" }}
cypress-cache-path: ~/.cache/custom-dir/Cypress
cypress-command: npx cypress run --component
node-cache-version: v2
commands:
description: |
Runs Cypress tests in your own job using commands
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
jobs:
install-and-persist:
executor: cypress/default
steps:
- cypress/install
- persist_to_workspace:
paths:
- .cache/Cypress
- project
root: ~/
run-tests-in-parallel:
executor: cypress/default
parallelism: 8
steps:
- attach_workspace:
at: ~/
- cypress/run-tests:
cypress-command: npx cypress run --component --parallel --record
workflows:
use-my-orb:
jobs:
- install-and-persist:
name: Install & Persist To Workspace
- run-tests-in-parallel:
name: Run Tests in Parallel
requires:
- Install & Persist To Workspace
component:
description: |
Runs Cypress component tests. Installs dependencies and caches NPM modules and the Cypress binary.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx cypress run --component
custom-install:
description: |
Runs Cypress tests and install dependencies using a custom install and post-install script.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
install-command: npm install && echo hello
post-install: npm run build
edge:
description: |
Run Cypress tests in Microsoft Edge.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
jobs:
edge-test:
executor: cypress-browsers
steps:
- cypress/install
- cypress/run-tests:
cypress-command: npx cypress run --browser edge
start-command: npm run start:dev
workflows:
use-my-orb:
jobs:
- edge-test
mono-repo:
description: |
Runs Cypress tests in a monorepo or when your Cypress folder is somewhere other than the root directory.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-cache-key: cypress-cache-{{ arch }}-{{ checksum "libs/shared-ui/package.json" }}
cypress-command: npx cypress run --component
working-directory: libs/shared-ui
node-version:
description: |
Run Cypress tests using the cypress/default executor with a specified node version.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
jobs:
run-cypress-in-specified-node-version:
executor:
name: cypress/default
node-version: "20.6"
steps:
- cypress/install:
package-manager: npm
- cypress/run-tests:
cypress-command: npx cypress run
start-command: npm run start:dev
workflows:
use-my-orb:
jobs:
- run-cypress-in-specified-node-version:
name: Run Cypress in Node 20
pnpm:
description: |
Runs Cypress tests using pnpm. Installs dependencies and caches NPM modules and the Cypress binary.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
install-command: pnpm install --frozen-lockfile
package-manager: pnpm
start-command: pnpm start
recording:
description: |
Runs Cypress end-to-end tests in parallel and record results to Cypress Cloud. Installs dependencies and caches NPM modules and the Cypress binary.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx cypress run --parallel --record
parallelism: 3
start-command: npm run start
run:
description: |
Runs Cypress end-to-end tests without recording results to Cypress Cloud. Installs dependencies and caches NPM modules and the Cypress binary.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
start-command: npm run start
wait-on:
description: |
Runs Cypress tests after waiting for the local server to start using the wait-on package (https://github.com/jeffbski/wait-on).
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
cypress-command: npx wait-on@latest http://localhost:8080 && npx cypress run
start-command: npm start
yarn:
description: |
Runs Cypress tests using yarn. Installs dependencies and caches NPM modules and the Cypress binary.
usage:
version: "2.1"
orbs:
cypress: cypress-io/cypress@3
workflows:
use-my-orb:
jobs:
- cypress/run:
package-manager: yarn
start-command: yarn start