Advanced18 min read

Debugging & Troubleshooting

Debug with Inspector, traces, screenshots, and videos.

Playwright Inspector

PWDEBUG=1 or --debug opens Inspector stepping through test line by line. Pick locator, explore DOM, view action log.

UI Mode (npx playwright test --ui) provides time travel, watch mode, and locator picker in integrated environment.

PWDEBUG=1 npx playwright test tests/login.spec.ts

Screenshots and Snapshots

screenshot: "only-on-failure" in config captures PNG on fail. page.screenshot manual capture. expect(locator).toHaveScreenshot() visual comparison with maxDiffPixels threshold.

Store baseline screenshots in repo; review diff in PR when UI intentionally changes.

await expect(page).toHaveScreenshot("homepage.png", {
  maxDiffPixelRatio: 0.01,
});

Video Recording

video: "on-first-retry" or "retain-on-failure" balances storage vs debug value. Videos saved in test output folder referenced from html report.

Large CI artifacts—configure retention policy.

use: {
  video: "retain-on-failure",
  trace: "on-first-retry",
}

Traces

trace records screencast, snapshots, network, console, source maps. npx playwright show-trace trace.zip opens Trace Viewer—best CI failure debug tool.

trace: "on-first-retry" or on-failure recommended for CI. Local use trace on any failure during flake hunt.

Trace shows action-before/after DOM snapshots
Network tab in trace reveals failed API mock
Share trace zip in bug reports for reproducibility

npx playwright show-trace test-results/.../trace.zip

Common Failure Patterns

Strict mode violation: locator matched multiple elements—narrow scope. Timeout: element never reached state—increase timeout or fix app bug. Target closed: navigation race.

Enable DEBUG=pw:api for verbose protocol logs sparingly—very noisy.