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.
💡 In CircleCI, a Job is a collection of steps to carry out an action. A Command defines a sequence of steps as a map to be executed in a job. Executors define the underlying technology to run a job. Below are all of these options that will allow you to run your Cypress tests with an out-of-the-box or customized configuration.
For the Orb Quick Start Guide and usage cases, view the CircleCI Cypress orb documentation.
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.
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.
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/cypress@3.x.y"
# 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.
You can pass arguments to the cypress/run job to override any default behaviors. See the full list of arguments.
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 quicklyNote: 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.
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/installandcypress/run-testscommands separately to first install dependencies to a workspace and then run tests in parallel.
Command that installs your application's node modules and Cypress dependencies.
⚠️ Note: this command is only necessary if you plan to execute therun-testscommand in a separate job. Especially if you run the tests on multiple machines in parallel.
You can pass arguments to the cypress/install command to override any default behaviors. See the full list of arguments.
Command that runs Cypress tests (assuming your machine has already installed necessary dependencies).
You can pass arguments to the cypress/run-tests command to override any default behaviors. See the full list of arguments.
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: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"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.
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.
This project is licensed under the terms of the MIT license.