Playwright Debugging

A doctor does not guess a diagnosis without examining a patient closely first. A tester should not guess why a test failed without examining the actual failure closely either. Playwright provides several tools built specifically for this kind of close examination, turning a confusing failure into a clear, understandable cause.

The Debugging Path

Test Fails Unexpectedly
        |
        v
Open a Debugging Tool
        |
        v
Inspect the Page State at the Moment of Failure
        |
        v
Identify the Real Cause
        |
        v
Fix the Test or the Application

Running a Test in Debug Mode

npx playwright test login.spec.js --debug

This opens a special inspector window alongside the browser. It pauses before every single action, letting a tester step through the test one command at a time and watch exactly what happens.

Using the Trace Viewer

module.exports = {
  use: {
    trace: 'on-first-retry',
  },
};

This setting saves a detailed trace file whenever a test fails and gets retried. A trace records every action, every network call, and a screenshot at each step throughout the entire test run.

npx playwright show-trace trace.zip

Opening a trace file replays the whole test visually, similar to watching a recorded video with the ability to pause and inspect any single moment.

Saving a Screenshot Automatically on Failure

module.exports = {
  use: {
    screenshot: 'only-on-failure',
  },
};

This captures exactly what the page looked like the instant a test failed, often revealing an unexpected popup, a missing element, or an error message a tester never anticipated.

Recording a Video of the Test Run

module.exports = {
  use: {
    video: 'retain-on-failure',
  },
};

This saves a full video recording only for failed tests, useful when a single screenshot does not fully explain a problem that unfolded over several seconds.

Printing Values During a Test

const text = await page.locator('h1').textContent();
console.log('Heading text found:', text);

Printing a value directly confirms exactly what the script actually read from the page at that moment, a quick and simple check before reaching for heavier debugging tools.

Pausing a Test at a Specific Line

await page.pause();

Placing this line anywhere inside a test freezes execution at that exact point, opening an interactive browser window where a tester can manually explore the page's current state.

A Real-World Debugging Scenario

A test clicking "Add to Cart" fails intermittently, passing most of the time but failing occasionally. Enabling trace recording reveals that a cookie consent banner sometimes covers the button for a split second, something a single screenshot alone would likely miss entirely.

Quick Practice Task

Take a test that currently passes, temporarily break it on purpose, then use debug mode to step through and watch exactly where it fails.

Key Takeaways

• Debug mode pauses a test for step-by-step manual inspection.
• Trace files replay a complete, detailed recording of a test run.
• Screenshots and videos capture the exact page state during a failure.
• console.log offers a fast, simple way to confirm values mid-test.