GitHub Action, Cypress and Percy parallelisation setup

#frontend #cypress #ci #githubactions

Recently, I moved our Cypress test suite over to GitHub Action, and I had trouble finding a full example of how to run Cypress and Percy together using parallelisation to run the tests quicker. Here is an example of how to do this.

I will assume if you ended up here, you know what all of those tools do.

Full example

In your repo, in .github/workflows/main.yml:

name: End-to-end tests
on:
  pull_request:
    branches:
      - develop
jobs:
  cypress-run:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        containers: [1, 2, 3, 4, 5, 6]
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup node
        uses: actions/setup-node@v1
        with:
          node-version: '10.x'
          registry-url: 'https://registry.npmjs.org'
      - name: Install dependencies
        run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - name: Cypress run
        uses: cypress-io/github-action@v1
        with:
          install: false
          start: npm start
          wait-on: 'http://localhost:8080/'
          record: true
          parallel: true
          command-prefix: 'percy exec -- npx'
        env:
          CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
          PERCY_PARALLEL_TOTAL: 6
          PERCY_PARALLEL_NONCE: '${{ github.event_name }}-${{ github.sha }}'
          PERCY_TARGET_BRANCH: 'develop'
          PERCY_BRANCH: ${{ github.head_ref }}
          COMMIT_INFO_BRANCH: ${{ github.head_ref }}

For any environment variables, use GitHub secrets to save them and access them in the GitHub action.

Breaking it down

Running test on pull request to the develop branch

name: End-to-end tests
on:
  pull_request:
    branches:
      - develop

Start the job and runs it on 6 ubuntu machines. In case of errors, do not cancel other actions (fail-fast: false)

jobs:
  cypress-run:
  runs-on: ubuntu-latest
  strategy:
    fail-fast: false
    matrix:
      containers: [1, 2, 3, 4, 5, 6]

Checkout the repo

steps:
  - name: Checkout
    uses: actions/checkout@v2

Set up node 10.x

- name: Setup node
  uses: actions/setup-node@v1
  with:
    node-version: '10.x'
    registry-url: 'https://registry.npmjs.org'

Install npm dependencies with NPM TOKEN for private repo

- name: Install dependencies
  run: npm ci
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

For running the cypress test, we are using the Cypress GitHub action. Here is the cypress doc which is pretty good but here is a breakdown as well:
- Cypress action configuration
  - install: false Do not install dependencies as we've done it ourselves
  - start: npm start Command to run to start the app
  - wait-on: 'http://localhost:8080/' wait for the app to be started on this url to start testing
  - record: true Record the test in Cypress dashboard
  - parallel: true Runs the test in parallel
  - command-prefix: 'percy exec -- npx' Command to be prefixed to the cypress command run by the action
- Environment variables
  - CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }: Cypress record key
  - PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }: Percy token
  - PERCY_PARALLEL_TOTAL: 6: The number of server used for parallelisation
  - PERCY_PARALLEL_NONCE: '${{ github.event_name }}-${{ github.sha }}': Unique ID for Percy to link builds on each machine together
  - PERCY_TARGET_BRANCH: 'develop' Target branch used by Percy to compare against
  - PERCY_BRANCH: ${{ github.head_ref }} Name to display in Percy for the branch this is being run for
  - COMMIT_INFO_BRANCH: ${{ github.head_ref }} Name to display in Cypress for the branch this is being run for

- name: Cypress run
  uses: cypress-io/github-action@v1
  with:
    install: false
    start: npm start
    wait-on: 'http://localhost:8080/'
    record: true
    parallel: true
    command-prefix: 'percy exec -- npx'
  env:
    CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
    PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
    PERCY_PARALLEL_TOTAL: 6
    PERCY_PARALLEL_NONCE: '${{ github.event_name }}-${{ github.sha }}'
    PERCY_TARGET_BRANCH: 'develop'
    PERCY_BRANCH: ${{ github.head_ref }}
    COMMIT_INFO_BRANCH: ${{ github.head_ref }}

I hope this is useful, comment below if you have any questions.
Happy testing 🎉

Top comments (8)

Mohsen • Apr 22 '21

Hey Aurore, thanks for the great article. We have the exact same setup:

Parallelised Cypress tests
Percy for visual tests
Github Actions But the problem is that it seems not all Percy snapshots are taken. I've passed the exact same PERCY_PARALLEL_TOTAL and PERCY_PARALLEL_NONCE but to n oavail.

Might have you any guesses what the issue could be? I'm wondering if you've encountered the same issue in the past.

Aurore T • Apr 29 '21

Hey Mohsen! Thank you! The only thing that comes to mind, is that PERCY_PARALLEL_TOTAL number you entered doesn't match how many servers or containers you are using. I just fixed a mistake in the article, where it didn't match either.
If your matrix contains 6 containers, PERCY_PARALLEL_TOTAL should be 6.

I can't think of any else. Have you contacted Percy? I find they are very helpful.

just-trey • Jun 22 '20 • Edited

I have something similar I am working on and this literally is a big piece of what part 2 or my post was going to be. I am going to link to yours instead. thanks for the insight and inspiration!