Cypress Integration - Frequently Asked Questions (FAQs)

What does the plugin do?

How do I see the replays created from my tests?

When you create replays of your automated tests, they are first written to disk locally. The replay browser creates a set of files containing raw replay data including user events, network requests and responses, source code and more.

Then you upload those files and associated metadata to Replay using our CLI. The CLI will print links to each uploaded replay or they can be viewed in your library.

Note: You’ll need to create an API key to upload replays which can be created either for your account (a personal API key) or for a team. We recommend creating a team for uploading automated tests because personal API keys are limited to 10 replays.

json
npx @replayio/replay upload-all --api-key <your-api-key-here>

How do I tell Cypress to run with a Replay browser?

If you’re using cypress open and have configured the plugin, the Replay browser should be listed alongside the other browsers installed on your system

If you’re using cypress run, it includes a command line parameter, --browser, which you can use to configure the browser.

sql
npx cypress run --browser 'Replay Chromium'

Note: Be sure to wrap the replay browser name in quotes because the name includes a space.

If you’re using the Cypress GitHub action, it includes a parameter, browser, to configure the browser:

yaml
name: E2E on Replay Chromium
on: [push]
jobs:
  cypress-run:
    runs-on: ubuntu-20.04
    # let's record our tests with Replay
    name: E2E on Replay Chromium
    steps:
      - uses: actions/checkout@v3
      - uses: cypress-io/github-action@v5
        with:
          browser: 'Replay Chromium'

How do I configure the browser with start-server-and-test?

start-server-and-test is a popular utility to start a dev server for your app and then run your tests. It accepts three arguments:

A command or npm script to start the server,

A URL to wait for a successful response, and

A command or npm script to run your tests

If you’re using an npm script to run your tests, you will need to either modify that script to specify the browser or create a new one to use with Replay.

json
{
    "scripts": {
        "start-server": "npm start",
        "test": "npx cypress run",
        "test:replay": "npx cypress run --browser 'Replay Chromium'",
        "ci": "start-server-and-test start-server http://localhost:8080 test",
        "ci:replay": "start-server-and-test start-server http://localhost:8080 test:replay"
    }
}

Why is the Cypress panel missing when I open my replays of a Cypress test?

When everything is working correctly, you should see a Cypress button in the left sidebar navigation to view the Cypress panel. If it’s missing, we are likely missing metadata from your Cypress recordings.

If your Cypress version is less than 10.9, there are two environment variables that must be set either in your npm script or in your CI configuration:

json
{
	"scripts": {
		"test:replay": "RECORD_ALL_CONTENT=1 RECORD_REPLAY_METADATA_FILE=/tmp/replay-metadat npx cypress run"
	}
}

yaml
  - name: Run Tests
		run: npx cypress run
		env:
			RECORD_ALL_CONTENT: 1
			RECORD_REPLAY_METADATA_FILE: /tmp/replay-metadata

If these environment variables are set or your Cypress version is 10.9 or greater, you can check the metadata saved before you upload recording with the Replay CLI.

shell
$ npx @replayio/replay ls --json

[
  {
    "id": "80645144-9c67-4cb4-a0d7-83a3895bc1f5",
    "createTime": "2023-01-11T16:24:44.564Z",
    "runtime": "gecko",
    "metadata": {
      "x-replay-test": {
        "id": "99e14e28-49bb-4762-9c94-736bc500a805"
      },
      "title": "cypress/e2e/cast-alias-spec.ts",
      "uri": "http://localhost:8888/__/#/specs/runner?file=cypress/e2e/cast-alias-spec.ts",
      "test": {
        "title": "cypress/e2e/cast-alias-spec.ts",
        "result": "passed",
        "path": [
          "",
          "firefox",
          "cypress/e2e/cast-alias-spec.ts",
          "integration"
        ],
        "runner": {
          "name": "cypress",
          "version": "10.9.0",
          "plugin": "0.4.6"
        },
        "run": {
          "id": "99e14e28-49bb-4762-9c94-736bc500a805"
        },
        "file": "cypress/e2e/cast-alias-spec.ts",
        "tests": [
          // ... test metadata would be here
        ],
        "version": 1
      }
    },
    "sourcemaps": [],
    "status": "onDisk",
    "path": "..."
  }
]