The Cypress CircleCI Orb is a piece of configuration set in your circle.yml file to correctly install, cache and run Cypress.io tests on CircleCI with very little effort. See this orb in CircleCI Registry.
- How to enable orbs
- Lots of examples
- Jobs and executors in this orb
- Orb versions
- Effective config
- Development and license
Note
- From organization settings allow using uncertified orbs
Settings -> Security -> Allow uncertified orbs - From the project's settings allow beta features
Settings -> Advanced Settings -> Enable pipelines
See the official CircleCI documentation.
Each example below should be placed into circle.yml or .circleci/config.yml file:
Install dependencies (using npm ci) and run all Cypress tests:
# to use orbs, must use version >= 2.1
version: 2.1
orbs:
# import Cypress orb by specifying an exact version x.y.z
# or the latest version 1.x.x using "@1" syntax
cypress: cypress-io/cypress@1
workflows:
build:
jobs:
# "cypress" is the name of the imported orb
# "run" is the name of the job defined in Cypress orb
- cypress/runRuns all Cypress tests and records them on the Cypress Dashboard:
version: 2.1
orbs:
cypress: cypress-io/cypress@1
workflows:
build:
jobs:
- cypress/run:
record: trueA more complex project that needs to install dependencies, build an application and run tests across 4 CI machines in parallel may have:
version: 2.1
orbs:
cypress: cypress-io/cypress@1
workflows:
build:
jobs:
# first get the source code and install npm dependencies
- cypress/install:
# run a custom app build step
build: 'npm run build'
- cypress/run:
# make sure app has been installed and built
# before running tests across multiple machines
# this avoids installing same dependencies 10 times
requires:
- cypress/install
record: true # record results on Cypress Dashboard
parallel: true # split all specs across machines
parallelism: 4 # use 4 CircleCI machines to finish quickly
group: 'all tests' # name this group "all tests" on the dashboard
start: 'npm start' # start server before running testsIn all cases, you are using run and install job definitions that Cypress provides inside the orb. Using the orb brings simplicity and static checks of parameters to CircleCI configuration.
- install dependencies using Yarn
- running tests using Node 6
- running tests using Chrome browser
- start server before running tests
- wait for server to respond before starting tests
- parallel run across two machines
- build application after install
- running several groups of tests
- running another job after tests
- building using orb on Mac and Linux
- use custom executor
- set additional environment variables
- install private NPM dependencies
- complete NPM module publishing example
- store test reports on Circle
- store screenshots and videos on Circle
- store other folders as artifacts on Circle
- use your own custom command to run tests
- skip saving workspace
- run commands in a subfolder of a monorepo
- cache using custom key in a monorepo
- custom configuration file
All examples are in docs/examples.md and are generated from the src/orb.yml file.
Also take a look at cypress-io/cypress-example-circleci-orb and cypress-io/cypress-example-kitchensink.
See docs/jobs.md and docs/executors.md for a full list of public jobs and executors that this orb provides.
The CircleCI Orb exports the following job definitions to be used by the user projects:
This job allows you to run Cypress tests on a one or more machines, record screenshots and videos, use the custom Docker image, etc.
A typical example:
# to use orbs, must use version >= 2.1
version: 2.1
orbs:
# import Cypress orb by specifying an exact version x.y.z
# or the latest version 1.x.x
cypress: cypress-io/cypress@1
workflows:
build:
jobs:
# checks out code, installs npm dependencies
# and runs all Cypress tests and records results on Cypress Dashboard
# cypress/run job comes from "cypress" orb imported above
- cypress/run:
record: trueSee all its parameters at the cypress/run job example.
run job later. If you only want to run all tests on a single machine, then you do not need a separate install job.
Sometimes you need to install the project's npm dependencies and build the application once before running tests, especially if you run the tests on multiple machines in parallel. For example:
version: 2.1
orbs:
cypress: cypress-io/cypress@1
workflows:
build:
jobs:
# install dependencies first (on 1 machine)
- cypress/install
# now run tests
- cypress/run:
# give this job a custom name for clarity
name: 'end-to-end tests'
requires:
# use previously installed dependencies
# to avoid installing them on each machine running tests
- cypress/install
record: true # record results to Cypress Dashboard
parallel: true # run tests in parallel
parallelism: 3 # use 3 CircleCI machines
group: 3 machines # name this group "3 machines"See available parameters at the cypress/install job example.
To better understand why we use a separate install job, take a look at the workflow diagram below.
The first job install runs on a single machine, and usually is very fast because it uses previously cached npm modules and Cypress binary to avoid reinstalling them. The second job run can run on multiple machines (in this case it runs on 3 machines), and uses workspace created by the install job to get 3 identical file systems before running tests. You can see the 3 parallel runs by clicking on the run job.
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. See CircleCI Orb versioning documentation.
You can find all changes and published orb versions for Cypress orb at cypress-io/circleci-orb/releases.
We are using cypress-io/cypress@1 version in our examples, so you get the latest published orb version 1.x.x. But we recommend locking it down to an exact version to prevent unexpected changes from suddenly breaking your builds.
If you install Circle local CLI, you can see the final effective configuration your project resolves to by running circleci config process <config filename> from the terminal.
For example, if your current CircleCI configuration file is .circleci/config.yml and it contains the following:
version: 2.1
orbs:
cypress: cypress-io/cypress@1
workflows:
build:
jobs:
- cypress/runThe fully resolved configuration will show:
$ circleci config process .circleci/config.yml
# Orb 'cypress-io/cypress@1' resolved to 'cypress-io/cypress@1.1.0'
version: 2
jobs:
cypress/run:
docker:
- image: cypress/base:12.14.0
parallelism: 1
steps:
- checkout
- restore_cache:
keys:
- cache-{{ .Branch }}-{{ checksum "package.json" }}
- run:
name: Npm CI
command: npm ci
- run:
command: npx cypress verify
- save_cache:
key: cache-{{ .Branch }}-{{ checksum "package.json" }}
paths:
- ~/.npm
- ~/.cache
- persist_to_workspace:
root: ~/
paths:
- project
- .cache/Cypress
- attach_workspace:
at: ~/
- run:
name: Run Cypress tests
command: 'npx cypress run'
workflows:
build:
jobs:
- cypress/run
version: 2If you want to customize the orb configuration, you can save and tweak the output of the circleci config process ... to suit your needs.
If you want to develop this orb and publish new versions, see our Contributing Guide.
This project is licensed under the terms of the MIT license.