Playwright Debugging

Debugging Toolkit

Run npx playwright test --debug to open Playwright Inspector — step through actions, see locators, and live-edit selectors.

Set PWDEBUG=1 or use VS Code extension 'Debug Test' for breakpoint debugging in TypeScript test code.

npx playwright test failing.spec.ts --debug
DEBUG=pw:api npx playwright test
use: { launchOptions: { slowMo: 500 } }

slowMo slows actions for visual observation — not for CI.

Debug Commands

--debug          Playwright Inspector
--headed         Visible browser
--ui             UI Mode
PWDEBUG=console  Inspector with console
page.pause()     Pause mid-test in Inspector

• page.pause() opens Inspector at that line when headed/debug.
• Console: page.on('console', msg => console.log(msg.text())).
• Trace: configure trace: 'retain-on-failure' in config.
• Screenshot on failure automatic with screenshot: 'only-on-failure'.

Debugging Reference

Pick the right debug tool.

Logging Console and Network

page.on('console', m => console.log('browser:', m.text()));
page.on('requestfailed', r => console.log('failed:', r.url()));

slowMo for Local Observation

launchOptions: { slowMo: 500 } slows actions locally so you can watch transitions — never enable in CI.

Common Mistakes

• Adding waitForTimeout instead of opening trace.
• Debugging headless without --headed once.
• Not enabling trace in CI for intermittent failures.
• Ignoring browser console errors logged during test.

Key Takeaways

• Inspector and UI Mode are primary local debug tools.
• Traces explain CI failures without reproduction.
• page.pause and slowMo help observe timing issues.
• Log console and failed requests for context.