Cypress CircleCI Orb
About
The Cypress CircleCI Orb is a
piece of configuration set in your .circleci/config.yml
file to correctly
install, cache and run Cypress with very little effort.
For the Orb Quick Start Guide and usage cases, view the CircleCI Cypress orb documentation.
How to enable
Note: To use CircleCI Orbs in your projects, you need to enable some settings:
From organization settings allow using uncertified orbs Settings -> Security -> Allow uncertified orbs
See the official CircleCI documentation.
Jobs
run
A complete job to install your application's node modules and Cypress dependencies, handle caching and run your tests. This is the out-of-the-box solution that will work for most use cases.
Basic Setup
A typical project can have:
version: 2.1
orbs:
# "cypress-io/cypress@3" installs the latest published
# version "s.x.y" of the orb. We recommend you then use
# the strict explicit version "cypress-io/[email protected]"
# to lock the version and prevent unexpected CI changes
cypress: cypress-io/cypress@3
workflows:
build:
jobs:
- cypress/run # "run" job comes from "Cypress" orb
start-command: 'npm run start'
By using the run
job definitions that Cypress provides inside the orb, it
brings simplicity and static checks of parameters to your CircleCI
configuration.
You can find more usage examples at our official orb page.
Arguments
You can pass arguments to the cypress/run
job to override any default behaviors. See the full list of arguments.
Parallelization
A more complex project that needs to install dependencies and run tests across 4 CI machines in parallel may have:
version: 2.1
orbs:
cypress: cypress-io/cypress@3
workflows:
build:
jobs:
- cypress/run:
# split specs across machines
# record results with Cypress Cloud
cypress-command: 'npx cypress run --parallel --record'
start-command: 'npm run start'
parallelism: 4 # use 4 CircleCI machines to finish quickly
Note: recording test results and spec parallelization requires Cypress Cloud account. You should also set your record key as CYPRESS_RECORD_KEY
environment variable in the CircleCI project.
⚠️ Usage and Consumption
There are 2 key metrics to understand when running a CI job across multiple machines:
- Consumption time on CircleCI
- Actual time it takes for tests to run
Consumption time is essentially the amount of CircleCI resources that a job requires to execute. For example, you may have a job that runs on 5 machines and takes 1 minute for all to complete. In this example it would only take 1 minute of actual time to execute all the jobs but would consume 5 minutes of CircleCI resources.
The Cypress CircleCI Orb
was designed to be as simple and fast as possible for the majority of use cases.
If you are running your tests in parallel across more than 5
machines, you may not want to use the cypress/run
job directly as it will consume
more CircleCI resources than are necessary.
Parallelization Across 5+ Machines
To lower your consumption time when running in parallel on more than 5 machines, see this example.
Here we use the
cypress/install
andcypress/run-tests
commands separately to first install dependencies to a workspace and then run tests in parallel.
Commands
install
Command that installs your application's node modules and Cypress dependencies.
⚠️ Note: this command is only necessary if you plan to execute therun-tests
command in a separate job. Especially if you run the tests on multiple machines in parallel.
Arguments
You can pass arguments to the cypress/install
command to override any default behaviors. See the full list of arguments.
run-tests
Command that runs Cypress tests (assuming your machine has already installed necessary dependencies).
Arguments
You can pass arguments to the cypress/run-tests
command to override any default behaviors. See the full list of arguments.
Executors
A single Docker container used to run Cypress tests. This default executor extends the circleci/browser-tools orb.
version: 2.1
orbs:
cypress: cypress-io/cypress@3
executor: cypress/default
jobs:
- cypress/run:
You can also use your own executor by passing in your own Docker image. See the full list of Cypress images on Docker Hub, or compose your own image with the Cypress Docker Factory.
version: 2.1
orbs:
cypress: cypress-io/cypress@3
executor:
docker:
image: cypress/browsers:node-16.18.1-chrome-109.0.5414.74-1-ff-109.0-edge-109.0.1518.52-1 # your Docker image here
jobs:
- cypress/run:
Examples
cypress/default
executor with cypress/install
and cypress/run-tests
commands:
Example using the version: 2.1
orbs:
cypress: cypress-io/cypress@3
jobs:
install:
executor: cypress/default
steps:
- cypress/install:
install-browsers: true
- persist_to_workspace:
root: ~/
paths:
- .cache/Cypress
- project
run-tests:
executor: cypress/default
parallelism: 10
steps:
- run: echo "This step assumes dependencies were installed using the cypress/install job"
- attach_workspace:
at: ~/
- cypress/run-tests:
cypress-command: 'npx cypress run --parallel --record'
start-command: 'npm run start'
Additional Info
Effective config
If you install CircleCI local CLI, you can see the final effective configuration your project resolves to by running circleci config process <config filename>
from the terminal.
Versions
Cypress orb is versioned so you can be sure that the configuration will not suddenly change as we change orb commands. We follow semantic versioning to make sure you can upgrade project configuration to minor and patch versions without breaking changes.
You can find all changes and published orb versions for Cypress orb at cypress-io/circleci-orb/releases.
We are using cypress-io/cypress@3
version in our examples, so you get the latest published orb version 3.x.x. But we recommend locking it down to an exact version to prevent unexpected changes from suddenly breaking your builds.
License
This project is licensed under the terms of the MIT license.