Project discovery and health
Purpose: understand what Watcher reads from your project and what the Project Summary panel tells you.
Watcher has no configuration file of its own. It discovers everything from your project when it starts.
What Watcher reads
All discovery happens relative to the directory where you ran npx watcher start, the project root.
| Item | How it is found |
|---|---|
package.json | In the project root. Watcher refuses to start without one. |
| Package scripts | The string entries of scripts in package.json. |
| Playwright config | playwright.config.ts, .js, .mjs or .cjs in the project root. |
| Test directories | tests/, e2e/ or specs/ in the project root. |
| Test files | Files ending in .spec.ts, .spec.js, .test.ts or .test.js. |
| Playwright installation | The project-local @playwright/test and its version. |
Test file inventory
Watcher searches the discovered test directories for test files. If none of tests/, e2e/ or specs/ exists, it searches the whole project instead. In both cases it skips node_modules, dist, .watcher, playwright-report, test-results, coverage and .git.
The inventory is a file count shown in Project Summary. It does not replace Playwright's own test collection; the number of tests a run will execute comes from Playwright itself (see Run Planner).
Health checks
Health summarizes these checks:
| Check | Healthy when | Otherwise |
|---|---|---|
| package.json | Found and readable | Error |
| Playwright config | A root config file exists | Warning |
| Test directory | tests/, e2e/ or specs/ exists | Warning |
| Package scripts | At least one script is defined | Warning |
| Playwright installation | @playwright/test resolves from the project | Warning: Playwright-aware runs and Playwright Tools are unavailable |
The overall status is error if any check is an error, warning if any check is a warning, and healthy otherwise. Watcher lists the reason for every check that is not healthy, both in the terminal at startup and under Health in the dashboard.
A warning does not stop you from using Watcher. For example, a project without a root Playwright config can still run package scripts in Generic mode.
Startup snapshot
Discovery runs once, when Watcher starts. If you add or change package scripts, or edit the Playwright config, restart Watcher to refresh the summary and script list.
Starting a run is always revalidated against the current project state, so a script that was removed after startup will not run from a stale list.
Related
- Script compatibility: how each script is classified.
- Troubleshooting