Cypress CircleCI Orb

📚 You will learn

How to easily run Cypress on CircleCI
How to run Cypress tests in parallel
How to split build and test jobs

💡 see github.com/cypress-io/circleci-orb

Motivation

You don't need to fiddle with caching, installation, flags, recording, etc. Let us (Cypress authors) write the CI configuration code.

Repo github.com/cypress-io/circleci-orb

⚠️ You might have to enable 3rd party orbs in your CircleCI settings, see github.com/cypress-io/circleci-orb#how-to-enable

TODO: try running the simplest job

Create file circle.yml in the root of the repo

version: 2.1
orbs:
  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/run:
          start: npm start
          wait-on: 'http://localhost:8080'

Commit and push the code.

start, wait-on parameters github.com/cypress-io/circleci-orb#examples

+++

Create CircleCI project

+++

Use existing config file

+++

Start building

+++

TODO: look at CircleCI steps

find the:

container info
code check out
caching
installation
starting the app
running tests

If you are using Yarn

  version: 2.1
  orbs:
    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/run:
+           yarn: true
            start: npm start
            wait-on: 'http://localhost:8080'

Versions

We publish orbs to CircleCI registry and to GitHub

circleci.com/developer/orbs
github.com/cypress-io/circleci-orb/releases

Picking the version of the orb to use:

cypress-io/cypress@1 is the latest v1 version of the orb
cypress-io/cypress@1.2 is the latest v1.2 version of the orb
cypress-io/cypress@1.19.3 is the specific version

Workspace

Cypress Orb automatically passes all files from one job to another using Cypress workspace. But saving it takes time.

+++

Todo: remove "persisting to workspace" step

We only have the single test job, and do not intend to run any more jobs using this workspace. Thus we can skip saving the workspace to save time.

💡 Hint: look at the examples in github.com/cypress-io/circleci-orb. Answer ⏬

+++

version: 2.1
orbs:
  cypress: cypress-io/cypress@1
workflows:
  build:
    jobs:
      - cypress/run:
          start: npm start
          wait-on: 'http://localhost:8080'
          no-workspace: true

no-workspace parameter github.com/cypress-io/circleci-orb#examples

+++

Record the test results

Look up the project's recording key at https://dashboard.cypress.io/projects/<id>/settings
Add CYPRESS_RECORD_KEY to the CircleCI project's settings

+++

TODO: Set the project to record

Look up the record option at github.com/cypress-io/circleci-orb. Answer ⏬

Bonus: add tag to separate the recorded runs from CircleCI from other CIs +++

version: 2.1
orbs:
  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/run:
          start: npm start
          wait-on: 'http://localhost:8080'
          no-workspace: true
          record: true
          tags: circleci

github.com/cypress-io/circleci-orb#record-on-dashboard

+++

CircleCI Orb is a text macro expansion

Can be checked statically via CircleCI CLI https://circleci.com/docs/2.0/local-cli/

$ circleci config validate circle.yml
Config file at circle.yml is valid.

+++

But if we tried to use tag instead of tags

$ circleci config validate circle.yml
Error: Error calling workflow: 'build'
Error calling job: 'cypress/run'
Unexpected argument(s): tag

+++

We can see the "effective" config after Orb has been expanded in the workflow

$ circleci config process circle.yml
# Orb 'cypress-io/cypress@1' resolved to 'cypress-io/cypress@1.27.0'
version: 2
jobs:
  cypress/run:
    docker:
    - image: cypress/base:10
    parallelism: 1
    environment:
    - CYPRESS_CACHE_FOLDER: ~/.cache/Cypress
    steps:
    - run:
        command: echo "Assuming dependencies were installed using cypress/install job"
    - attach_workspace:
        at: ~/
    - checkout
    - restore_cache:
        keys:
        - cache-{{ arch }}-{{ .Branch }}-{{ checksum "package.json" }}
    - run:
        name: Install
        working_directory: ''
        command: "if [[ ! -z \"\" ]]; then\n  echo \"Installing using custom command\"\n  echo \"\"\n  \nelif [ \"false\" = \"true\" ]; then\n  echo \"Installing using Yarn\"\n  yarn install --frozen-lockfile\nelif [ ! -e ./package-lock.json ]; then\n  echo \"The Cypress orb uses 'npm ci' to install 'node_modules', which requires a 'package-lock.json'.\"\n  echo \"A 'package-lock.json' file was not found. Please run 'npm install' in your project,\"\n  echo \"and commit 'package-lock.json' to your repo.\"\n  exit 1\nelse\n  echo \"Installing dependencies using NPM ci\"\n  npm ci\nfi\n"
    - run:
        name: Verify Cypress
        command: npx cypress verify
        working_directory: ''
    - save_cache:
        key: cache-{{ arch }}-{{ .Branch }}-{{ checksum "package.json" }}
        paths:
        - ~/.npm
        - ~/.cache
    - run:
        name: Start
        command: npm start
        background: true
        working_directory: ''
    - run:
        name: Wait-on http://localhost:8080
        command: npx wait-on http://localhost:8080
    - run:
        name: Run Cypress tests
        no_output_timeout: 10m
        command: |
          npx cypress run \
             \
             \
             \
             \
             --record \
               \
               \
               --tag 'circleci'  \
               \
        working_directory: ''
workflows:
  build:
    jobs:
    - cypress/run
  version: 2

Separate the install job from the test job

Later it will allow us to run multiple test jobs in parallel

version: 2.1
orbs:
  cypress: cypress-io/cypress@1
workflows:
  build:
    jobs:
      - cypress/install
      - cypress/run:
          requires:
            - cypress/install
          install-command: echo 'Everything was already installed'
          start: npm start
          wait-on: 'http://localhost:8080'
          no-workspace: true
          record: true
          tags: circleci

💡 Tip: find our CircleCI workflow recipes in github.com/cypress-io/circleci-orb/blob/master/docs/recipes.md

+++

Two jobs in the workflow

+++

Install using Yarn

- - cypress/install
+ - cypress/install:
+     yarn: true

Parallel testing

  - cypress/run:
-     install-command: echo 'Everything was already installed'
      start: npm start
      wait-on: 'http://localhost:8080'
      no-workspace: true
      record: true
      tags: circleci
+     parallel: true
+     parallelism: 2

When we use parallel: true parameter, it implies no install is necessary. See github.com/cypress-io/circleci-orb.

Full workflow on the next slide ⏬

+++ We need to install dependencies using 1 job, then run multiple test jobs using the same workspace. Cypress orb saves and loads the workspace between the jobs automatically

version: 2.1
orbs:
  cypress: cypress-io/cypress@1
workflows:
  build:
    jobs:
      - cypress/install
      - cypress/run:
          requires:
            - cypress/install
          start: npm start
          wait-on: 'http://localhost:8080'
          no-workspace: true
          record: true
          tags: circleci
          parallel: true
          parallelism: 2

+++

Machines view

+++

Parallelization calculator

+++

TODO: Check if 4 machines really take 10 seconds

- parallelism: 2
+ parallelism: 4

🏎 tip: CircleCI gives 16(!) parallel containers for free for open source public projects.

+++

TODO

build app (once) after installing dependencies
run tests in several groups
print Cypress info
run tests using Chrome or Firefox browser
store test artifacts on CircleCI
run tests on Windows, or Mac

How to Keep Cypress Tests in Another Repo While Using CircleCI

Blog post https://glebbahmutov.com/blog/how-to-keep-cypress-tests-in-another-repo-with-circleci/

use one repo to build and deploy the application
after deploy trigger CircleCI workflow that runs the Cypress tests
pass the baseUrl as a workflow parameter

+++

Use bahmutov/trigger-circleci-pipeline

# assuming the environment variable CIRCLE_CI_API_TOKEN
# has your personal CircleCI token, trigger a workflow
# in the CircleCI project bahmutov/todomvc-tests-circleci
# and pass pipeline parameters
$ npx trigger-circleci-pipeline \
    --org bahmutov --project todomvc-tests-circleci --branch ${BRANCH_NAME} \
    --parameters TEST_URL=${TEST_URL},TEST_BRANCH=${BRANCH_NAME}

See bahmutov/todomvc-no-tests-vercel and bahmutov/todomvc-tests-circleci example

Learn more 🎓

Resources 📚

github.com/cypress-io/circleci-orb/blob/master/docs/examples.md
github.com/cypress-io/circleci-orb/blob/master/docs/recipes.md

+++

Blogs and talks 📝

anything tagged "circle" at https://glebbahmutov.com/blog/tags/circle/
"Start CircleCI Machines Faster by Using RAM Disk" at https://glebbahmutov.com/blog/circle-ram-disk/ Jan 2021
"Make Cypress Run Faster by Splitting Specs" at https://glebbahmutov.com/blog/split-spec/ Dec 2020
"Faster, easier, end-to-end testing with CircleCI and Cypress" at https://www.youtube.com/watch?v=v7FCj2LOWgE Oct 2020

+++

Bonus: Cypress Integration App for X

Post pull request results from any CI to GitHub / GitLab / BitBucket

Watch the video "Add Cypress GitHub Integration To A Repo Step By Step" https://youtu.be/4TLjsCmXZlM

⌛️ Review

using cypress-io/circleci-orb is the simplest way to install, cache, and run Cypress tests on CircleCI
running tests in parallel is as simple as parallelism: N
the orb passes the files through the workspace automatically

Jump to: Generic CI, GitHub Action, CircleCI, Netlify Build

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Cypress CircleCI Orb

📚 You will learn

Motivation

TODO: try running the simplest job

Create CircleCI project

Use existing config file

Start building

TODO: look at CircleCI steps

If you are using Yarn

Versions

Workspace

Todo: remove "persisting to workspace" step

Record the test results

TODO: Set the project to record

CircleCI Orb is a text macro expansion

Separate the install job from the test job

Two jobs in the workflow

Install using Yarn

Parallel testing

Machines view

Parallelization calculator

TODO: Check if 4 machines really take 10 seconds

TODO

How to Keep Cypress Tests in Another Repo While Using CircleCI

Learn more 🎓

Resources 📚

Blogs and talks 📝

Bonus: Cypress Integration App for X

⌛️ Review

Files

README.md

Latest commit

History

README.md

File metadata and controls

Cypress CircleCI Orb

📚 You will learn

Motivation

TODO: try running the simplest job

Create CircleCI project

Use existing config file

Start building

TODO: look at CircleCI steps

If you are using Yarn

Versions

Workspace

Todo: remove "persisting to workspace" step

Record the test results

TODO: Set the project to record

CircleCI Orb is a text macro expansion

Separate the install job from the test job

Two jobs in the workflow

Install using Yarn

Parallel testing

Machines view

Parallelization calculator

TODO: Check if 4 machines really take 10 seconds

TODO

How to Keep Cypress Tests in Another Repo While Using CircleCI

Learn more 🎓

Resources 📚

Blogs and talks 📝

Bonus: Cypress Integration App for X

⌛️ Review