Getting started

Watchwright runs as one long-lived server on your machine. You start it once, and it serves its web page and its HTTP API on http://127.0.0.1:7420/.

Requirements

• Node.js 22 or newer
• Windows, macOS or Linux. Windows is the first platform the run engine is checked on.

Install and start

Watchwright is the watchwright package on npm. Run it with npx, or install it in your project (npm install --save-dev watchwright) or globally (npm install --global watchwright):

npx playwright install chromium firefox
npx watchwright serve     # starts the server at http://127.0.0.1:7420/ and opens it

The first line downloads the browsers Playwright drives.

Every version on npm is published by the repository's release workflow and carries a provenance statement that ties it to the commit it was built from; npm audit signatures checks it.

Try the demo

To see a run before writing a pack, start one of the TodoMVC example pack:

npx watchwright demo

It downloads Playwright's Chromium if it's missing, starts the server, adds the example pack and starts a run against Playwright's public TodoMVC demo app. The run's page opens in your browser, with the browser live. The pack's copy sits in the data folder under demo/todomvc; open it in Packs to read its tests. See watchwright demo.

From a clone

To work on Watchwright itself, run it from a clone of the repository (with pnpm 9; corepack enable sets it up from package.json):

pnpm install
pnpm --filter watchwright exec playwright install chromium firefox
pnpm serve            # builds, starts the server and opens it

A first run

1. On the web page, open Packs and add a test pack: type its folder (the field completes folders as you type), or press Browse… and pick it (its Find packs here searches a folder and the ones below it). You can also name pack folders when you start the server: watchwright serve path/to/pack. See Adding a pack.
2. Press New run. It opens on the pack of your latest run, filled with that run's choices (Use pack defaults starts over; Settings can make it always start from the defaults). Search or pick tests by section and tag, set the parameter values and the options (attempts per test, trace, video of every attempt or only of those with problems, a video of the whole run, pausing on a broken test), give the run a label if you like, and start it with the button or Ctrl+Enter (Cmd+Enter on a Mac). Choices you use often can be saved as a preset with the menu beside the preset list, and picked again later; agents can start a preset by name. The Planned panel shows every attempt in the order it will run, and which tests join because a chosen one needs them.
3. The run page shows the browser live with the current test and step, and has the controls to pause, retry, skip and stop. While it runs you can skip attempts that haven't started, move tests up and down the queue, or add tests to the end of it. Rewind under the live view goes back through the last 30 seconds, with the steps that ran then, and plays them like a video: play and pause, speed (0.5× to 4×), one frame back or forward and 5-second jumps (Space or K, the arrow keys, comma and period). Playback that catches up with the run goes back to live by itself. Mark saves what the live view shows (or the rewound moment) to the current attempt with a note. The log keeps the newest lines at the bottom and follows them as they come in (scroll up and it stops; Follow or scrolling back to the end starts it again). Search it (Enter and Shift+Enter go from match to match), show or hide info, warning and error lines with their counts, filter by test, and wrap long lines.

Looking at results

Click an attempt in the queue to open its page. It shows the error (with In your code, the line of your test it broke on), the flags (robot problems apart from findings), metrics and notes. When the test names its steps (h.step), a Steps timeline shows when each ran and how long it took, with warnings from the log as marks; picking a step jumps the video there. When the attempt has a video, a filmstrip of its frames sits under the timeline: hover a frame to see it larger, click it to move the playhead there. The Before and after button beside a step compares the page just before the step started with the page a moment after it ended, side by side, as a wipe or as an overlay of the changed pixels. The same timeline sits under the video and follows it as it plays, and dragging either one moves the video. When steps are too short for their names, the timeline opens zoomed in far enough for most of them to show in full and scrolls sideways with the playhead (also while you drag the playhead against an edge); zoom with its buttons, + and -, or Ctrl (Cmd on a Mac) with the mouse wheel. Hovering shows the time, the step and any warning under the pointer above the timeline, and warnings too close together show as one mark with their count. Attempts recorded before steps were kept read their steps from the log's Step: lines (without outcomes). Then come tabs for:

• the screenshots, with a full-size viewer (scroll shots show as one strip),
• kept texts,
• the log, with the same search, level toggles and wrapping as the run page; a line's number copies a link that opens the attempt at that line,
• collector records in a table,
• the video,
• the trace, which opens in Playwright's trace viewer served by Watchwright.

J and K step to the next and previous attempt. Beside the results, the Review panel scores the attempt on the pack's rubric (see Reviewing results).

A finished run's page shows every test's attempts and scores as a grid, with Compare and Export (Markdown, or a zip with the screenshots). Compare in the top bar lines up runs of one pack side by side; it opens on the latest finished run's pack with its two latest finished runs.

Runs, the home page, lists the runs that are going and every earlier one, with a search (words in the label, id, pack name, values or status; lang=de finds a value) and filters by pack and status. From there you can open a run, Run again (the same pack, tests, values and options, started at once), start a new one from its choices with New run like this…, or delete it. The Size column says how much room each run takes on the drive; a run's page says it beside who started it. A run's page has the same buttons, and the pencil beside its title gives it a name that shows in the lists, Compare and exports.

Above the list, At a glance shows the last 7, 14 or 30 days: how many runs, the pass rate (passed out of passed, failed and broken), broken attempts and the median attempt time, each with its change against the same number of days before and a small trend line. Show chart opens a chart of attempts per day by outcome (point at a day for its numbers); it stays open or closed the way you left it. Days are your computer's calendar days. Picking one pack in the filter shows that pack's dashboard here instead, the same as on its page.

Long pages have a way around them. An attempt's page, a run's page and a pack's page list their parts under On this page: in the right margin when the window is wide enough, like this site, else behind the list button at the bottom right. Picking a part scrolls to it; on an attempt's page, picking Log, Files or another saved tab also opens it. Every long page gets Back to top and To the bottom beside it.

Press Ctrl+K (Cmd+K on a Mac) anywhere, or the search button at the top, to find a pack, a run (by pack, label, id, values or status) or a test, or to run a command: run the latest run again, start a new run of a pack, add a pack, go to a page, or switch the look and mode.

Watching a run

While a run goes, the browser tab's title says how it's going (Running 4/12, Paused: S1 broke, Done 12/12) and the tab's icon gets a dot in the state's color, so a tab in the background still tells you. On the run's page these keys work the run (press ? for the list):

Key	What it does
Space	Pause, or resume a pause you made
R	Retry the broken attempt the run paused on
S	Skip it: keep its result and go on
M	Mark: save the live view to the running attempt, with a note
Shift+S	Stop after this test

Settings on a going run's page changes what the run started with: whether it pauses when a test breaks and how long it waits before it skips, a time limit for every test, the trace, the videos of attempts and the video of the whole run. A finished run's page plays its run video; turned off and on during the run, it has parts. Changes apply from the next test and stay with the run. A new wait applies at once to a pause that is going, counted from when it began. While the run is paused on a broken test, More time gives it 10 more minutes before it skips. The CLI does the same with watchwright runs settings <run> --pause-limit-minutes 60.

Watchwright can also send a desktop notification when a run finishes, pauses on a broken test (with the minutes left before it skips the test by itself) or fails to start, while its tab is in the background; clicking one opens the run. Switch them on under Notifications in Settings, or answer the offer that shows the first time you start a run. The choice is kept by each browser. While the tab is in front, the same news shows as a short message in the corner, except on that run's own page.

File names of your tests, build errors and the line a test broke on are links that open in your editor at that line. Pick the editor (VS Code, Cursor, Windsurf, IntelliJ IDEA, WebStorm, or none) on the Settings page (the gear at the top).

Settings, Admin and your account

Three pages hold Watchwright's settings. Each has a list of its sections down the side (above them on a narrow screen) that jumps to each.

• Settings (the gear) is yours: the look and mode and notifications, kept by this browser; the editor file links open in and what a new run starts from, kept by the server for you (with login off, for the machine); and connecting your agents.
• Admin (the shield next to the gear, for admins) is the server's, one value for everyone: users and single sign-on with login on, and the Defaults for people who haven't picked their own editor or New run; secrets, saved sign-ins, runners, whether runs Watchwright's stop interrupted resume when it starts again, sharing, alerts; Storage (how full the drive with the data folder is, what runs take, the largest runs, Videos (a Video quality for the videos of runs that start from now: High, sharp text at 30 frames a second for videos people watch, Full, as Playwright records them, Compact, about 80% smaller with text still sharp, or Small, 3/4 of the size at 10 frames a second, about 94% smaller; and Compress kept videos, which encodes the videos runs already kept again at that quality (High videos excepted), in the background, and stops by itself when a run starts), the free space below which runs warn and then stop recording videos, and Clean up old runs: keep runs for some days, or the newest few of each pack, with a sweep once a day and Clean up now; both are off until you set them, and named runs are always kept); the list of recent folders; and Server: start at sign-in, updates and Stop Watchwright, which stops the server as Ctrl+C in its terminal does. Runs going at the time can be resumed after it starts again.
• Your account (the user menu, with login on): your password and your API tokens.

With login on, people who aren't admins see the server sections they may use (secret names, saved sign-ins, runners, their share links, storage and recent folders) on their Settings page, under On this server.

Options

watchwright serve [pack folder…] adds the pack folders you name (or reloads them when they are already added). When Watchwright is already running on the port, it adds them there, opens the page and exits; when another program has the port, it says so. It takes these options:

Option	Default	What it does
--port	7420	Port for the web page and the API.
--host	127.0.0.1	Address to bind. Only loopback addresses are allowed until token auth is built.
--data	see below	Folder for the database and everything runs save.
--no-open	off	Don't open the web page in your browser on start.

Data folder

Watchwright keeps its SQLite database and everything runs save in one folder. It picks the first of:

1. the --data option,
2. the WATCHWRIGHT_DATA environment variable,
3. the usual app data folder: %LOCALAPPDATA%\Watchwright on Windows, ~/Library/Application Support/Watchwright on macOS, ~/.local/share/watchwright on Linux.

Next steps

• How it works explains runs, attempts and plugins.
• Writing a test pack shows how to write a pack.
• HTTP and WebSocket API lists every route, event and the live WebSocket.