Record your Cypress.io tests

1

Create a new Test Suite team

Start by visiting our new test suite form. It will create an API key and guide you through each step.

Terminal
npm install --save-dev @replayio/cypress

Terminal
npx replayio install

.env
REPLAY_API_KEY=<your_api_key>

cypress/support/e2e.js
require('@replayio/cypress/support')

cypress.config.js
 1const { defineConfig } = require('cypress')
 2const { plugin: replayPlugin, wrapOn } = require('@replayio/cypress')
 3require('dotenv').config()
 4
 5module.exports = defineConfig({
 6  e2e: {
 7    setupNodeEvents(cyOn, config) {
 8      const on = wrapOn(cyOn)
 9      replayPlugin(on, config, {
10        upload: true, // automatically upload your replays do DevTools
11        apiKey: process.env.REPLAY_API_KEY,
12      })
13      return config
14    },
15  },
16})

Terminal
npx cypress run --browser replay-chromium

Terminal
🕑 Completing some outstanding work ...
🚀 Successfully uploaded 2 recordings:

❌ cypress/e2e/spec.cy.ts
https://app.replay.io/recording/5bab992d-34dd-4853-9f6a-09375a66de98

✅ cypress/e2e/clearCart.cy.js
https://app.replay.io/recording/b37abe67-031c-4d23-ba8b-0224fcd3e0d5

Adding Replay to an existing Cypress project

If you already have a cypress.config.js with custom setupNodeEvents, merge Replay in instead of overwriting it:

• Wrap your existing on — Replace on in your setupNodeEvents signature with cyOn, then call const on = wrapOn(cyOn). Pass that wrapped on to both your existing event handlers and replayPlugin. Without wrapOn, Replay cannot hook into Cypress's lifecycle events.
• Return the config object — setupNodeEvents must return config (or a Promise resolving to it). Forgetting this is the most common cause of "browser not found" errors.
• Keep existing cypress/support/e2e.js content — Add require('@replayio/cypress/support') (or import '@replayio/cypress/support') alongside whatever else is in your support file.
• Pass --browser replay-chromium when you want Replay to record. Cypress will keep using your default browser otherwise.

Troubleshooting

If something does not look right, work through these in order:

1. No recording uploaded — Confirm REPLAY_API_KEY is set in the shell that runs Cypress (echo $REPLAY_API_KEY) and that the run used --browser replay-chromium.
2. Browser: Replay Chromium was not found — Your setupNodeEvents likely is not returning config, or the support file import is missing. If both look right, see the Cypress troubleshooting guide for the full list of causes (caching, CYPRESS_INSTALL_BINARY, OS support).
3. Tests run but Cypress commands do not appear in Replay DevTools — The support file import is missing or wrapOn is not wrapping the on you pass to your existing handlers.
4. Browser launches but does not record — On older Ubuntu runners, OpenSSL 1.1 may be missing. See the Cypress troubleshooting guide for the install snippet.
5. Errors that look like they come from your app — These usually indicate an application-side problem, not a Replay issue. Run the same test once with stock Chrome (--browser chrome) to confirm.

For deeper issues (browser hangs, diagnostic mode, verbose logs), see the full Cypress troubleshooting guide.

Record your test suite in CI

GitHub Actions is the documented CI path. The minimal workflow installs the Replay browser, then uses cypress-io/github-action with the Replay browser and REPLAY_API_KEY set:

.github/workflows/e2e.yml
name: End-to-end tests
on:
  pull_request:
  push:
    branches: [main]
jobs:
  cypress-run:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: Install Replay Chromium
        run: npx replayio install
      - name: Cypress run
        uses: cypress-io/github-action@v6
        with:
          browser: replay-chromium
        env:
          REPLAY_API_KEY: ${{ secrets.REPLAY_API_KEY }}

Add REPLAY_API_KEY to your repository secrets. For deeper CI guidance, see the GitHub Actions reference. Other CI providers follow the same pattern; see other CI providers. To tune what gets uploaded (failed-only, branch-based), see Upload strategies.