DEV Community

Aurore T
Aurore T

Posted on • Updated on

GitHub Action, Cypress and Percy parallelisation setup

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 }}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  • 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]
Enter fullscreen mode Exit fullscreen mode
  • Checkout the repo
steps:
  - name: Checkout
    uses: actions/checkout@v2       
Enter fullscreen mode Exit fullscreen mode
  • Set up node 10.x
- name: Setup node
  uses: actions/setup-node@v1
  with:
    node-version: '10.x'
    registry-url: 'https://registry.npmjs.org'
Enter fullscreen mode Exit fullscreen mode
  • Install npm dependencies with NPM TOKEN for private repo
- name: Install dependencies
  run: npm ci
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Enter fullscreen mode Exit fullscreen mode
  • 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 }}
Enter fullscreen mode Exit fullscreen mode

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

Top comments (8)

Collapse
 
mohsenny profile image
Mohsen

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.

Collapse
 
digitaledawn profile image
Aurore T

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.

Collapse
 
justtrey profile image
just-trey • 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!

Collapse
 
digitaledawn profile image
Aurore T

Oh thanks! Glad it's useful :)

Collapse
 
mongopark profile image
Ola' John Ajiboye

Thanks so much for this. Exactly what I was looking for!

Collapse
 
digitaledawn profile image
Aurore T

Glad it helps!

Collapse
 
devsrihari4 profile image
devsrihari4

Nice artilce. What is the difference using containers: [1, 2, 3] and machines: [1, 2, 3]? Thank you!

Collapse
 
digitaledawn profile image
Aurore T

Thanks! I am not sure. I've never used machines: [1, 2, 3]. Have you checked GitHub action documentation?