CircleCI

What you'll learn

How to run Cypress tests with CircleCI as part of CI/CD pipeline
How to parallelize Cypress test runs within CircleCI

Basic Setup

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.

Full documentation can be found at the cypress-io/circleci-orb repo. For the Orb Quick Start Guide and usage cases, view the CircleCI Cypress orb documentation.

A typical project can have:

version: 2.1
orbs:
  # "cypress-io/cypress@2" installs the latest published
  # version "s.x.y" of the orb. We recommend you then use
  # the strict explicit version "cypress-io/cypress@2.x.y"
  # to lock the version and prevent unexpected CI changes
  cypress: cypress-io/cypress@2
workflows:
  build:
    jobs:
      - cypress/run # "run" job comes from "cypress" orb

Parallelization

A 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@2
workflows:
  build:
    jobs:
      - cypress/install:
          build: 'npm run build' # run a custom app build step
      - cypress/run:
          requires:
            - cypress/install
          record: true # record results with Cypress Cloud
          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 tests

In 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.

You can find multiple examples at our orb examples page and in the cypress-example-circleci-orb project.

Real World Example
New

The Cypress Real World App (RWA) uses the Circle CI Cypress Orb, Codecov Orb, and Windows Orb to test over 300 test cases in parallel across 25 machines, multiple browsers, multiple device sizes, and multiple operating systems with full code-coverage reporting and Cypress Cloud recording.

Check out the full RWA Circle CI configuration.

Additional Examples

Example `.circleci/config.yml` v2 config file

version: 2
jobs:
  build:
    docker:
      - image: cypress/base:14.16.0
        environment:
          ## this enables colors in the output
          TERM: xterm
    working_directory: ~/app
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-deps-{{ .Branch }}-{{ checksum "package.json" }}
            - v1-deps-{{ .Branch }}
            - v1-deps
      - run:
          name: Install Dependencies
          command: npm ci
      - save_cache:
          key: v1-deps-{{ .Branch }}-{{ checksum "package.json" }}
          # cache NPM modules and the folder with the Cypress binary
          paths:
            - ~/.npm
            - ~/.cache
      - run: $(npm bin)/cypress run --record --key <record_key>

Example `.circleci/config.yml` v2 config file with `yarn`

version: 2
jobs:
  build:
    docker:
      - image: cypress/base:14.16.0
        environment:
          ## this enables colors in the output
          TERM: xterm
    working_directory: ~/app
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-deps-{{ .Branch }}-{{ checksum "package.json" }}
            - v1-deps-{{ .Branch }}
            - v1-deps
      - run:
          name: Install Dependencies
          command: yarn install --frozen-lockfile
      - save_cache:
          key: v1-deps-{{ .Branch }}-{{ checksum "package.json" }}
          paths:
            - ~/.cache ## cache both yarn and Cypress!
      - run: $(yarn bin)/cypress run --record --key <record_key>

Find the complete CircleCI v2 example with caching and artifact upload in the cypress-example-docker-circle repo.

RAM Disk

You can speed up Cypress test jobs by using CircleCI RAM disk, read Start CircleCI Machines Faster by Using RAM Disk blog post.