Welcome to Replayβs Cypress plugin documentation!
Step 1: Installing the Replay plugin (Cypress v10.9+)
Install the
@replayio/cypress
package in your project:bashnpm install @replayio/cypress -D # or yarn add @replayio/cypress --dev
Add the Replay plugin to
cypress.config.js
javascriptconst { defineConfig } = require('cypress'); // πββοΈ Add this line to require the replay plugin const replay = require("@replayio/cypress") module.exports = defineConfig({ e2e: { setupNodeEvents(on, config) { // πββοΈ Add this line to install the replay plugin replay.default(on, config); // Make sure that setupNodeEvents returns config return config; }, }, });
Add this line your support file, which should be
cypress/support/e2e.js
for e2e tests (unless modified)javascript// cypress/support/e2e.js require('@replayio/cypress/support');
After the setup is complete, you can now try running your tests locally with the Replay browser:
bashnpx cypress run --browser=replay-firefox
Replay Chromium is only available for linux, but we hope to ship Chromium for Mac and Windows soon!
If you run into any problems, consult our troubleshooting guide here.
Step 2: Creating a Replay Team
We recommend creating a new team in Replay to organize your Cypress replays. Youβll also need an API Key to upload your replays and team API keys have much higher limits than personal API keys.
- Visit app.replay.io/team/new to create a team.
- Once youβve created a team, create a new API Key.
- Save that API in your GitHub Repository secrets as
RECORD_REPLAY_API_KEY
so itβs available for the workflow weβll make next!
Step 3: Recording and uploading tests in CI
Hereβs a basic GitHub Action configuration which you can add to you project as
.github/workflows/e2e.yaml
to get started.yamlname: End-to-end tests on: [push, pull_request] jobs: cypress-run: runs-on: ubuntu-22.04 steps: - name: Checkout uses: actions/checkout@v3 # Install NPM dependencies, cache them correctly # and run all Cypress tests - name: Cypress run uses: cypress-io/github-action@v5.1.0 with: browser: replay-chromium build: npm run build start: npm start # Always run this step so failed tests are uploaded - name: Upload replays if: always() uses: replayio/action-upload@v0.4.7 with: api-key: ${{ secrets.RECORD_REPLAY_API_KEY }}
The steps may be different depending on how you run tests in CI, so pick one of the options below that best applies to you.
Troubleshooting
If youβre encountering issues configuring Cypress with Replay or if the Replay browser is crashing or producing unexpected results, check out the resources below or reach out to us over email or discord and weβll help!
Troubleshooting GuideCypress FAQsDiagnostic Modes