GitHub Action, Cypress and Percy parallelisation setup
Tags: frontend, cypress, ci, githubactions
Published: 2020-03-21 15:44:33

---
title: GitHub Action, Cypress and Percy parallelisation setup
published: true
description: Example of how to set up Cypress and Percy test as Continuous Integration in GitHub Action with parallelisation
tags: 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`:

```yaml
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](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) to save them and access them in the GitHub action.


## **Breaking it down**

- Running test on pull request to the develop branch

```yaml
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`)

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

```yaml
steps:
  - name: Checkout
    uses: actions/checkout@v2       
```
- Set up node 10.x

```yaml
- 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

```yaml
- 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](https://www.cypress.io/blog/2019/11/20/drastically-simplify-your-testing-with-cypress-github-action/) 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

```yaml
- 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 :tada: