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
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
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=
to your
.env
file and use the
dotenv
package to load it.
macOS/Linux
:
export REPLAY_API_KEY=
Windows
:
set REPLAY_API_KEY=
Configuration
Update
playwright.config.ts
to use the Replay reporter and Replay Chromium browser:
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:
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:
Install the plugin:
npm install --save-dev @replayio/playwright
Install the browser:
npx replayio install
Update
playwright.config.ts
with the Replay reporter and project
Set the
REPLAY_API_KEY
environment variable
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:
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:
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:
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.