Skip to main content

Script compatibility

Watcher classifies every package.json script so it can run Playwright scripts directly and safely. A script is Playwright-aware only when Watcher can interpret it exactly. Anything else runs in Generic mode, unchanged, through npm.

Generic mode is not an error: Generic scripts run exactly as before. They do not get Run options, a planned test count or structured progress.

Playwright-aware scripts​

A script is Playwright-aware when all of the following are true:

  1. It starts with playwright test or npx playwright test.
  2. It is a single command, with no shell chaining, pipes, redirects, variable expansion, command substitution or environment assignments.
  3. Every option is in the supported list below, written with literal values.
  4. Any --config path resolves inside the project.
  5. The script has no npm pre<name> or post<name> lifecycle hook.

Positional arguments, such as file filters, are allowed.

Supported options​

KindOptions
Flags--fail-on-flaky-tests, --forbid-only, --fully-parallel, --headed, --ignore-snapshots, --no-deps, --pass-with-no-tests, --quiet
With a value--config / -c, --grep / -g, --grep-invert / -G, --project, --repeat-each, --retries, --shard, --timeout, --workers / -j

Values can be passed as --option value or --option=value. Flags must not have an assigned value.

Examples​

package.json
{
  "scripts": {
    "test": "playwright test",
    "test:chromium": "npx playwright test --project=chromium",
    "test:smoke": "playwright test --grep @smoke --workers=2",
    "test:ci": "npm run lint && playwright test",
    "test:debug": "PWDEBUG=1 playwright test"
  }
}
ScriptModeReason
testPlaywright-aware
test:chromiumPlaywright-aware
test:smokePlaywright-aware
test:ciGenericShell chaining, pipes, and redirects are not supported.
test:debugGenericShell-specific environment assignments are not supported.

These results are the same on Windows and Linux.

Reasons Watcher shows​

When a script that looks like Playwright runs in Generic mode, the dashboard explains why. Common reasons:

ReasonWhat to do
Shell chaining, pipes, and redirects are not supported.Move the extra steps into a separate script, or run in Generic mode.
Shell expansion, substitution, or unsupported quoting/escaping requires Generic execution.Use literal values.
Shell-specific environment assignments are not supported.Set the variable before starting Watcher.
Playwright option "…" is not supported for safe collection.Remove the option or use Generic mode.
Only direct npx playwright invocations are supported.Use npx playwright test ….
Playwright is invoked through a custom or nested wrapper.Call playwright test directly in the script.
Nested npm script chains are not supported for Playwright collection.Point the dashboard at the script that calls Playwright directly.
npm lifecycle hooks (…) require Generic execution to preserve script behavior.Expected: your hooks still run in Generic mode.
The Playwright --config path must resolve inside the project.Keep the config inside the project root.
Windows doubled quotes require Generic execution to preserve npm argument semantics.Avoid "" inside quoted arguments, or use Generic mode.

Quoting rules​

Watcher follows the quoting rules of the shell npm uses on your platform: cmd.exe on Windows and sh on Linux. Quoted literal arguments, including empty ones, are supported. A script using Windows command wrappers such as playwright.cmd runs in Generic mode on Linux.