Debugging Playwright tests effectively

Using the Playwright Inspector

The Playwright Inspector is the foundational tool for interactive debugging, allowing developers to step through test execution line by line. When you execute your test with the inspector enabled, the browser launches in a persistent state, pausing execution at specific commands. This allows you to inspect the Document Object Model (DOM) and verify selectors precisely as the test engine sees them at that exact millisecond. The reason this works effectively is that it synchronizes the test runner with the browser's internal event loop, preventing the race conditions that occur during high-speed automated runs. By using 'pause()' within your test script, you gain the ability to manually trigger actions or examine the state of complex web components. This creates a bridge between your test logic and the actual browser execution, ensuring that you can validate locators and state transitions visually before finalizing your test assertions.

import { test } from '@playwright/test';

test('inspecting state', async ({ page }) => {
  await page.goto('https://example.com');
  // Pause execution to open the Inspector
  await page.pause(); 
  await page.getByRole('button').click();
});

Visual Tracing and Artifacts

Tracing is an essential post-mortem debugging feature that captures every action, network request, and console log during a test run. Unlike a simple screenshot, a trace provides a complete timeline of the test execution, including the DOM snapshot at every step. This works by serializing the state of the browser at each event and storing it in a structured file format that can be viewed later. When a test fails in a CI environment, retrieving the trace file allows you to 'time travel' through the test execution. You can examine why an action failed, view the specific network responses that occurred leading up to the failure, and see how the UI changed. By analyzing the trace, you identify the root cause by comparing the recorded state against the expected application behavior, effectively eliminating guesswork regarding environmental timing or configuration issues.

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    // Capture traces on first retry for debugging
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

Network Request Interception

Debugging complex application logic often requires inspecting network traffic to verify that frontend interactions correctly communicate with backend services. Playwright provides a mechanism to intercept, log, and even mock network requests in real-time. By monitoring 'request' and 'response' events, you can confirm that your application sends the expected payload with the correct authorization headers. The reason this is powerful for debugging is that many test failures are caused by silent failures in network calls that do not trigger visual errors in the UI. Intercepting these requests allows you to verify the contract between your code and the server. If a test fails because a button click doesn't trigger a navigation, intercepting the request tells you immediately if the network request was actually fired, rejected by a server error, or never initiated due to a logic gate error in your client-side code.

test('monitoring network activity', async ({ page }) => {
  // Listen for all network requests
  page.on('request', request => console.log('>>', request.method(), request.url()));
  await page.goto('https://api.example.com');
});

Headful Execution and Console Logging

While headless execution is standard for CI, running tests in 'headful' mode is often the first step in troubleshooting visual regressions or complex interactions. Headful mode forces the browser to open a visible window, allowing you to observe the execution rhythm and witness rendering issues that are hidden in headless environments. Furthermore, integrating console logging directly from the browser context into your terminal provides immediate feedback on hidden exceptions. The reason this is highly effective is that it surfaces errors within the browser's JavaScript environment that the test runner might otherwise treat as generic timeouts. By routing browser console logs into your terminal, you can correlate specific test failures with uncaught exceptions or warnings thrown by the application logic. This transparency makes debugging significantly faster because you can pinpoint the exact line of client-side code failing simultaneously with your test command.

test('logging console messages', async ({ page }) => {
  // Forward browser logs to the console
  page.on('console', msg => console.log(`Browser log: ${msg.text()}`));
  await page.goto('https://example.com');
});

Debugging with Timeouts and Retries

Flaky tests often stem from subtle timing issues or resource contention that only appear sporadically. To debug these effectively, you must understand how Playwright handles timeouts and how retries can be used to gather more diagnostic data. By intentionally slowing down specific actions or extending test timeouts, you can observe whether a test eventually passes, which indicates an underlying synchronization issue. However, relying solely on arbitrary timeouts is a 'code smell'; instead, you should use retries combined with trace artifacts. When a test is configured to retry, Playwright automatically attempts the action again, potentially providing a cleaner execution trace if the flake was due to an external service hiccup. This strategy helps differentiate between genuine logic bugs—which fail consistently—and environmental instability, which can be mitigated through smarter polling and better handling of asynchronous data states.

test('debug with custom timeout', async ({ page }) => {
  // Increase timeout for a slow operation
  await page.goto('https://slow-load.com', { timeout: 30000 });
  await page.waitForSelector('.ready-state', { timeout: 10000 });
});

Interview questions

All Playwright interview questions →

Check yourself

Take the full Playwright quiz →