Skip to main content

Quickstart

Purpose: go from an installed package to your first completed run in Watcher.

Prerequisites:

  • Watcher is installed in your project.
  • Your project has @playwright/test installed locally and at least one package script that runs Playwright, such as:
package.json
{
  "scripts": {
    "test": "playwright test"
  }
}

1. Start Watcher​

From the directory containing your package.json:

npx watcher start

Expected result: Watcher prints what it discovered, followed by the dashboard address:

Starting Watcher…
Watcher project root: /path/to/your-project
Discovery: package.json found, 1 Playwright config(s), 1 test directory, 5 package script(s)
Test inventory: 2 spec file(s) across 1 directory
Project health: healthy (0 error(s), 0 warning(s))
Dashboard: http://127.0.0.1:5050
Press Ctrl+C to stop Watcher.

The counts reflect your project. If any health check is not healthy, Watcher prints its reason underneath the health line.

Port already in use?

Start on another port with npx watcher start --port 5051.

2. Open the dashboard​

Open the printed address, by default http://127.0.0.1:5050, in your browser. http://localhost:5050 also works.

The Project Summary panel shows the project name, health, number of test files and number of package scripts. The header shows a Live connection active indicator.

3. Plan the run​

In Run Control:

  1. Choose your script from Package script, for example test — playwright test.
  2. Optionally expand Run options to override projects, browser mode, workers or retries. Leave them as As configured for your first run.
  3. Review Effective run. It shows the settings that will apply, where each one comes from, and the number of Planned Tests. Expand Command preview to see the exact command.

Run Control with Run options expanded, showing the Effective run summary and the command preview

4. Run and watch​

Select Run. The Current Run panel shows the run status, mode and duration. On Playwright 1.63 or newer you also see Integration: Enhanced, a progress bar, counters and the tests currently executing. Live Output streams the console output.

Current Run panel during an Enhanced run, showing 5 of 8 tests completed and one active test

To end a run early, select Stop Run.

5. Review the result​

When the run finishes, it appears in Recent Runs. Select the script name to open Run Detail, which shows how the run was requested, its outcome and the final result of each test, failed tests first.

From Run Detail you can also select Repeat run… to load the same settings into the Run Planner.

6. Stop Watcher​

Press Ctrl+C in the terminal. This also stops any active managed run or tool session.

What you have now​

  • A .watcher/watcher.db file in your project containing the completed run's history.
  • Playwright's normal outputs, such as playwright-report/ or test-results/, written exactly as your configuration specifies.

Next steps​

Troubleshooting​

SymptomFix
No package.json found in <folder>.Run the command from your project root, not a subfolder.
Port 5050 is already in use.Use --port with a free port.
Health shows a warning for @playwright/testInstall Playwright in the project: npm install --save-dev @playwright/test. Generic scripts still run.
No progress counters, only logsThe script runs in Generic mode or Basic integration. See Playwright integration.
New scripts do not appearWatcher reads scripts at startup. Restart it after editing package.json or the Playwright config.