Welcome to Replay’s Cypress plugin documentation!

💡

This guide assumes that you already have a Cypress 10.9+ test suite. If you’re just setting up your Cypress test suite, first follow the instructions here. If your Cypress Test Suite is below 10.9, follow the instructions here.

Step 1: Installing the Replay plugin (Cypress v10.9+)

Install the @replayio/cypress package in your project:

bash
npm install @replayio/cypress -D
# or
yarn add @replayio/cypress --dev

Add the Replay plugin to cypress.config.js

javascript
const { 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:

bash
npx 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.

yaml
name: 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.

Using GitHub Actions with cypress-io/github-action

Using GitHub Actions without cypress-io/github-action

Using other CI providers

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 Guide Cypress FAQs Diagnostic Modes

Cypress Instructions

Step 1: Installing the Replay plugin (Cypress v10.9+)

Step 2: Creating a Replay Team

Step 3: Recording and uploading tests in CI

Troubleshooting