Debug Mode

Debug Mode launches Playwright with a visible browser and enhanced diagnostics, giving you direct visual feedback when investigating test failures.

Enabling Debug Mode

Toggle the Debug switch in the Runner toolbar before starting a run. This adds the following Playwright flags:

npx playwright test --headed --debug
# Equivalent environment variable:
PWDEBUG=1

Headed Browser

In Debug Mode, the browser window is visible on screen. You can watch the test interact with the page in real time — clicks, form fills, navigations all happen in front of you.

Window Placement

xyva positions the headed browser beside the console panel so you can see both simultaneously. Resize the split by dragging the divider.

Step-Through Execution

With PWDEBUG=1, Playwright pauses before each action. The Playwright Inspector opens alongside the browser showing:

• The current action about to execute (e.g. click('button.submit'))
• The selector it resolved to, highlighted on the page
• Resume / Step Over / Step Into controls

This lets you advance one action at a time and inspect the page state between steps.

Trace Viewer

Every Debug Mode run automatically generates a Playwright trace file. After the run completes, click Open Trace in the console to launch the Trace Viewer:

Trace Feature	Description
Timeline	Visual timeline of every action with duration
Snapshots	DOM snapshot before and after each action
Network	Request/response log with timing waterfall
Console	Browser console output captured per action

Trace saved: .xyva/traces/cart-spec-2026-03-21.zip
Open with: npx playwright show-trace .xyva/traces/cart-spec-2026-03-21.zip

Trace File Size

Trace files include DOM snapshots and can be large (10-50 MB per spec). They are stored in .xyva/traces/ and automatically pruned after 7 days.

Screenshot on Failure

Even outside Debug Mode, xyva captures a screenshot whenever a test fails. Screenshots are stored alongside the run results:

.xyva/screenshots/
  cart-spec-should-update-quantity-FAILED.png
  checkout-spec-should-apply-coupon-FAILED.png

In Debug Mode, screenshots are also taken before the failing action, giving you a before/after comparison.

Performance Considerations

Debug Mode is significantly slower than headless execution:

Factor	Headless	Debug Mode
Rendering	Offscreen (fast)	On-screen (GPU bound)
Pausing	None	Pauses per action
Trace capture	Optional	Always on
Typical overhead	Baseline	3-5x slower

Not for CI

Debug Mode is designed for local investigation only. In CI pipelines, use headless mode with --trace on to capture traces without the performance penalty of headed execution.