GitHub actions

Cypress team has created its official GitHub Action. The action provides dependency installation, built-in caching, and multiple options for advanced workflow configuration.

Using this GitHub Action is optional and some teams prefer their own custom setup. Replay integrates well with both workflows, as shown in examples below

These instructions assume that you have already installed @replayio/cypress plugin into your project. Follow the instructions on this page to learn how to install the plugin.

Using GitHub Actions with cypress-io/github-action

When using the Cypress GitHub Action, the CI setup requires just a couple of lines of code. For the Cypress run itself, the replay-chromium browser needs to be passed in to create recordings.

After test run finishes, an additional step needs to be added to upload all the recordings using @replayio/action-upload action.

1name: End-to-end tests
2on: push
4 cypress-run:
5 runs-on: ubuntu-22.04
6 steps:
7 - name: Checkout
8 uses: actions/checkout@v4
9 - name: Install Replay Chromium
10 run: npx replayio install
11 - name: Cypress run
12 uses: cypress-io/github-action@v6
13 with:
14 browser: replay-chromium
15 env:
16 REPLAY_API_KEY: ${{ secrets.REPLAY_API_KEY }}
17 - name: Upload replays
18 if: always()
19 uses: replayio/action-upload@v0.5.1
20 with:
21 api-key: ${{ secrets.REPLAY_API_KEY }}

Using GitHub Actions without cypress-io/github-action

Without using GitHub Actions and running your Cypress tests by calling a script, the main principles stay the same:

  • you need to make sure to pass REPLAY_API_KEY to your test run
  • add step to your pipeline to upload your replays

There are a couple of different ways to achieve this. For example, you can update your package.json file with a custom script that runs your Cypress tests with Replay Browser

"scripts": {
"cy:run": "cypress run", // original test script
"cy:run:replay": "cypress run --browser=replay-chromium" // new test script

Use that new test script instead in your current workflow file, and add the environment variable(s):

.github/workflows/e2e.yml (partial)
1- name: Cypress run
2 run: npm run cy:run:replay
3 env:

Add a new step to run after your Cypress tests for uploading the replays:

.github/workflows/e2e.yml (partial)
1- name: Upload replays
2 if: always()
3 uses: replayio/action-upload@v0.5.1
4 with:
5 api-key: ${{ secrets.REPLAY_API_KEY }}

Upload strategies

There are different strategies for uploading your replays. For example you can use Replay only when retrying a failed test, or choose to upload recordings from failed tests only. See docs on upload strategies to learn more.