# Replay Playwright

> Set up and run Playwright tests with Replay Browser to record test executions for debugging and performance analysis.

- Skill: `replayio/replay-playwright` (Agent Skill)
- Install (CLI): `npx skillmds@latest add replayio/replay-playwright`
- Raw SKILL.md: https://api.skillmd.com/api/skills/replayio/replay-playwright/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: replayio (https://skillmd.com/u/replayio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/replayio/replay-playwright

---


## replay-playwright

**Description:** Use when the user wants to set up Replay for Playwright tests, configure the Replay Playwright plugin, or run Playwright tests with the Replay Browser. Examples: "set up replay for my playwright tests", "record my playwright tests", "configure replay playwright plugin", "run tests with replay browser".

**Instructions:**

You are helping the user set up and run Playwright tests with the Replay Browser. Here is the complete reference:

### Installation

#### 1. Install the Replay Playwright plugin

```sh
npm install --save-dev @replayio/playwright
# or
yarn add --dev @replayio/playwright
# or
pnpm add --save-dev @replayio/playwright
# or
bun add --dev @replayio/playwright
```

#### 2. Install the Replay Browser

```sh
npx replayio install
```

### Authentication

Create a Test Suite Team at https://app.replay.io/team/new/tests to generate an API key.

Store the API key using one of these methods:

- **`.env` file** (recommended): Add `REPLAY_API_KEY=<your_api_key>` to your `.env` file and use the [dotenv](https://www.npmjs.com/package/dotenv) package to load it.
- **macOS/Linux**: `export REPLAY_API_KEY=<your_api_key>`
- **Windows**: `set REPLAY_API_KEY=<your_api_key>`

### Configuration

Update `playwright.config.ts` to use the Replay reporter and Replay Chromium browser:

```typescript
import { replayReporter, devices as replayDevices } from "@replayio/playwright";

const config: PlaywrightTestConfig = {
  reporter: [
    replayReporter({
      apiKey: process.env.REPLAY_API_KEY,
      upload: true,
    }),
    ["line"],
  ],
  projects: [
    {
      name: "replay-chromium",
      use: { ...replayDevices["Replay Chromium"] },
    },
  ],
};
```

Key configuration details:
- `replayReporter` handles uploading recordings after test runs
- `upload: true` automatically uploads recordings when tests finish
- The `replay-chromium` project uses the Replay Browser to capture recordings
- You can keep existing projects alongside `replay-chromium` for regular test runs

### Running Tests

Run Playwright tests with the Replay Browser:

```sh
npx playwright test --project replay-chromium
```

Recordings are automatically uploaded when `upload: true` is set in the reporter config.

## Core Workflow

**Set up Replay for an existing Playwright project:**

1. Install the plugin: `npm install --save-dev @replayio/playwright`
2. Install the browser: `npx replayio install`
3. Update `playwright.config.ts` with the Replay reporter and project
4. Set the `REPLAY_API_KEY` environment variable
5. Run tests: `npx playwright test --project replay-chromium`

**When modifying the user's `playwright.config.ts`:**

- Preserve existing projects and reporters — add the Replay project and reporter alongside them
- Import `replayReporter` and `devices as replayDevices` from `@replayio/playwright`
- If the config uses `defineConfig`, add the Replay project to the existing `projects` array
- If the config already has reporters, append `replayReporter` to the existing array

### Debugging your recorded application
**Run Replay MCP Server to debug your recored application**
to install the MCP server in Claude, run the following command:

```
claude --mcp-config "{
    "mcpServers": {
      "replay": {
        "type": "http",
        "url": "https://dispatch.replay.io/nut/mcp",
        "headers": {
          "Authorization": "${REPLAY_API_KEY}"
        }
      }
    }
  }"
```

## Troubleshooting: Recordings Not Being Created

If the Replay browser runs tests successfully but no recordings appear (`replayio list` shows nothing),
the recording driver likely failed to load.

### Diagnose

Run the Replay browser directly with recording enabled and check stderr:

```sh
RECORD_ALL_CONTENT=1 $(node -e "console.log(require('os').homedir() + '/.replay/runtimes/chrome-linux/chrome')") --headless https://google.com
```

If the recording driver loads correctly, you should see no `DoLoadDriverHandle` errors. There should be recordings available from `replayio list`

### Fix: Missing libcrypto.so.1.1

If you see:
```
DoLoadDriverHandle: dlopen failed ... libcrypto.so.1.1: cannot open shared object file
```

The Replay recording driver requires OpenSSL 1.1, but the system only has OpenSSL 3.
Download the Ubuntu 18.04 `libssl1.1` package and extract the libraries:

```sh
curl -sL -o /tmp/libssl1.1.deb \
  http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1-1ubuntu2.1~18.04.23_amd64.deb
dpkg-deb -x /tmp/libssl1.1.deb $HOME/.local/openssl11
rm /tmp/libssl1.1.deb
```

Then set `LD_LIBRARY_PATH` before launching the browser:

```sh
export LD_LIBRARY_PATH=$HOME/.local/openssl11/usr/lib/x86_64-linux-gnu
```

Verify the fix by running the diagnostic command again — the `DoLoadDriverHandle` error should be gone.

This should be set in `launchOptions.env` in your Playwright config, or globally via the Dockerfile.
```