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
-
- Cypress action configuration
- 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)
Hey Aurore, thanks for the great article. We have the exact same setup:
PERCY_PARALLEL_TOTAL
andPERCY_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.
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.
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!
Oh thanks! Glad it's useful :)
Thanks so much for this. Exactly what I was looking for!
Glad it helps!
Nice artilce. What is the difference using containers: [1, 2, 3] and machines: [1, 2, 3]? Thank you!
Thanks! I am not sure. I've never used
machines: [1, 2, 3]
. Have you checked GitHub action documentation?