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 Playwright
Replay records automated browser tests by replacing the browser normally used to run your tests. Playwright must be configured to launch the Replay Browser to generate recordings.
Installation
Run the following in your project directory:
shellnpm install @replayio/playwright -D
This installs the Replay Browsers on your machine and provides functionality for recording tests with Replay.
Configuration
In your
playwright.config.ts
file, import devices
from @replayio/playwright
. This gives you access to “Replay Chromium” devices to set the browser in your config using Playwright projects.
Example config:
typescriptimport { PlaywrightTestConfig, devices } from "@playwright/test"; import { devices as replayDevices } from "@replayio/playwright"; const config: PlaywrightTestConfig = { projects: [ { name: "replay-chromium", use: { ...replayDevices["Replay Chromium"] as any }, }, { name: "chromium", use: { ...devices["Desktop Chromium"] }, }, ], }; export default config;
This example also includes projects for running your tests without recording using Chromium, imported from
@playwright/test
. Only the replay-chromium
projects will generate replays.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
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
- Ensure your project is configured with
replayio/playwright
- Configure Playwright to only use a single worker and increase the timeout if needed to allow for increased run time. (See config example below).
- Set
RECORD_REPLAY_API_KEY
as an environment variable locally
- Pass the
--project
flag, and your selected browser option: --project project-name
(replay-chromium
)
- Pass the
--reporter
flag like this: --reporter=@replayio/playwright/reporter,line
For example, to use Replay Chromium (macOS, Linux), the command is:
bashnpx playwright test --project replay-chromium --reporter=@replayio/playwright/reporter,line
If you don’t specify a project, all projects defined in your config will run.
Config example:
javascriptimport { PlaywrightTestConfig, devices } from "@playwright/test"; import { devices as replayDevices } from "@replayio/playwright"; const inCI = !!process.env.CI; const config: PlaywrightTestConfig = { timeout: !inCI ? 30 * 1000 : 10 * 1000, workers: !inCI ? 1 : undefined, use: { baseURL: !inCI ? "http://localhost:3000" : undefined, launchOptions: { slowMo: inCI ? 0 : 500, }, }, projects: [ { name: "replay-chromium", use: { ...replayDevices["Replay Chromium"] as any }, }, { name: "chromium", use: { ...devices["Desktop Chromium"] }, }, ], }; export default config;
We recommend using the options available in Playwright to only run certain tests as needed.
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
Once you’ve recorded, view test results and replays using the Test Suite Dashboard and Pull Request Comments.