Setting up a team

You’ll need a Replay team specifically for your automated test replays. This lets you set up an API key for recording in CI and provides

Start by creating a new team in the Replay Library sidebar and inviting your team members. Once created, we’ll enable access to the Test Suite Dashboard.

When you’re ready to record, you can create an API Key from the Team Settings. Using the API Key connects your recordings to the correct team to ensure access to your replays is protected and your Test Suite Dashboard views are accurate.

Configuring Cypress

Replay records automated browser tests by replacing the browser normally used to run your tests. Cypress must be configured to launch the Replay Browser to generate recordings.

Installation

Run the following in your project directory:

npm install @replayio/cypress -D or

yarn add @replayio/cypress -D

This installs the Replay Browsers on your machine and provides functionality for recording tests with Replay.

Configuration

How you configure Replay will depend on what version of Cypress you are using. Replay is supported for Cypress versions 6+.

Cypress v10+

In your Cypress config file, import cypressReplay from @replayio/cypress.

Then, add cypressReplay inside setupNodeEvents .

👉

As of version 10, Cypress provides separate configuration options for e2e and component testing. setupNodeEvents is set within one of these options, NOT at a global level. See Cypress documentation here.

The examples below correspond to the configuration examples in the Cypress docs.

CommonJS syntax

javascript
const { defineConfig } = require("cypress");
const cypressReplay = require("@replayio/cypress");

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      cypressReplay.default(on, config);
      return config;
    },
  },
});

cypress.config.js

ESM Module syntax

typescript
import { defineConfig } from "cypress";
import cypressReplay from "@replayio/cypress";

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      cypressReplay(on, config);
      return config;
    },
  },
});

cypress.config.ts

Cypress plugins file import

If you migrated to Cypress 10 using a migration tool, you may see the following code in your configuration file:

javascript
    // We've imported your old cypress plugins here.
    // You may want to clean this up later by importing these.
    setupNodeEvents(on, config) {
      return require('./test/cypress/plugins/index.js')(on, config)

This line should be removed or altered to import any plugins without a return statement. For example, follow this commit.

Cypress legacy versions

For versions before Cypress 10, use the Cypress plugins file to add Replay. The cypress.json configuration file does not need to be updated.

Add the following to your plugins/index.js file. You may need to update the module.exports to include both on and config.

javascript
const cypressReplay = require("@replayio/cypress");

module.exports = (on, config) => {
  cypressReplay.default(on, config);

  return config;
};

cypress/plugins/index.js

If you have existing code in your plugins file, ensure that there is only one return statement that includes the config option.

Screenshots and Videos

In your Cypress configuration, video and screenshotOnRunFailure can be set to false. This is not required, but recommended to improve performance.

Screenshots and videos typically aren’t needed when you already have a replay!

Recording tests in CI

Replay is designed to record tests in CI so you can debug when tests fail. Without Replay, test failures in CI are like a black box, with little insights into what went wrong. By recording with Replay, you get a full recording of the test run with debugging tools built in.

Configuration instructions will vary based on your CI provider and pipeline.

GitHub Actions

🔂Recording with GitHub Actions

Other CI Providers

🏁Recording with Other CI Providers

Recording tests locally

While Replay Test Suites is designed for debugging tests in CI, it can be helpful to record a test locally for additional debugging or when first getting set up.

Recording replays

🚧

Tests can only be recorded when in cypress run mode. You cannot use Replay to record with cypress open.

Ensure your project is configured with @replayio/cypress

Set RECORD_REPLAY_API_KEY as an environment variable locally

Add required environment variables and the --browser flag to your test run command like in the example below

Browser options are “Replay Chromium” (Linux) or “Replay Firefox” (macOS, Linux)

bash
RECORD_ALL_CONTENT=1 RECORD_REPLAY_METADATA_FILE=$(mktemp) cypress run --browser 'Replay Firefox'

To only run certain tests, use the --spec flag built into Cypress.

Uploading replays

Replays are uploaded locally using the @replayio/replay CLI. Your API key must be set as the RECORD_REPLAY_API_KEY environment variable to upload.

To see available replays for upload, use npx @replayio/replay ls

To upload a single replay, use npx @replayio/replay upload <id>

To upload all available replays, use npx @replayio/replay upload-all

Full instructions at the @replayio/replay repo.

💡

Once you’ve recorded, view test results and replays using the Test Suite Dashboard and Pull Request Comments.

Cypress Instructions