playwright/docs/src/debug.md

id	title
debug	Debugging tools

Playwright scripts work with existing debugging tools, like Node.js debuggers and browser developer tools. Playwright also introduces new debugging features for browser automation.

Playwright Inspector

Playwright Inspector is a GUI tool that helps authoring and debugging Playwright scripts. That's our default recommended tool for scripts troubleshooting.

Playwright Trace Viewer

Playwright Trace Viewer is a GUI tool that helps troubleshooting test runs in a post-mortem manner.

Run in headed mode

Playwright runs browsers in headless mode by default. To change this behavior, use headless: false as a launch option. You can also use the [option: slowMo] option to slow down execution and follow along while debugging.

await chromium.launch({ headless: false, slowMo: 100 }); // or firefox, webkit

chromium.launch(new BrowserType.LaunchOptions() // or firefox, webkit
  .setHeadless(false)
  .setSlowMo(100));

await chromium.launch(headless=False, slow_mo=100) # or firefox, webkit

chromium.launch(headless=False, slow_mo=100) # or firefox, webkit

// Chromium, Firefox, or Webkit
await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions
{
    Headless = false,
    SlowMo = 100
});

Browser Developer Tools

You can use browser developer tools in Chromium, Firefox and WebKit while running a Playwright script in headed mode. Developer tools help to:

• Inspect the DOM tree and find element selectors
• See console logs during execution (or learn how to read logs via API)
• Check network activity and other developer tools features

Using a [method: Page.pause] method is an easy way to pause the Playwright script execution and inspect the page in Developer tools. It will also open Playwright Inspector to help with debugging.

For Chromium: you can also open developer tools through a launch option.

await chromium.launch({ devtools: true });

chromium.launch(new BrowserType.LaunchOptions().setDevtools(true));

await chromium.launch(devtools=True)

chromium.launch(devtools=True)

await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions
{
    Devtools: true
});

:::note For WebKit: launching WebKit Inspector during the execution will prevent the Playwright script from executing any further. :::

Run in Debug Mode

Set the PWDEBUG environment variable to run your scripts in debug mode. Using PWDEBUG=1 will open Playwright Inspector.

Using PWDEBUG=console will configure the browser for debugging in Developer tools console:

• Runs headed: Browsers always launch in headed mode
• Disables timeout: Sets default timeout to 0 (= no timeout)
• Console helper: Configures a playwright object in the browser to generate and highlight Playwright selectors. This can be used to verify text or composite selectors.

PWDEBUG=console npm run test

set PWDEBUG=console
npm run test

env:PWDEBUG="console"
npm run test

PWDEBUG=console mvn test

set PWDEBUG=console
mvn test

$env:PWDEBUG="console"
mvn test

PWDEBUG=console pytest -s

set PWDEBUG=console
pytest -s

$env:PWDEBUG="console"
pytest -s

Selectors in Developer Tools Console

When running in Debug Mode with PWDEBUG=console, a playwright object is available in Developer tools console.

1. Run with PWDEBUG=console
2. Setup a breakpoint to pause the execution
3. Open the console panel in browser developer tools
4. Use the playwright API
   • playwright.$(selector): Highlight the first occurrence of the selector. This reflects how page.$ would see the page.
   • playwright.$$(selector): Highlight all occurrences of the selector. This reflects how page.$$ would see the page.
   • playwright.inspect(selector): Inspect the selector in the Elements panel.
   • playwright.locator(selector): Highlight the first occurrence of the locator.
   • playwright.clear(): Clear existing highlights.
   • playwright.selector(element): Generate a selector that points to the element.

Visual Studio Code debugger (Node.js)

The VS Code debugger can be used to pause and resume execution of Playwright scripts with breakpoints. The debugger can be configured in two ways.

Use launch config

Setup launch.json configuration for your Node.js project. Once configured launch the scripts with F5 and use breakpoints.

Use the JavaScript Debug Terminal

1. Open JavaScript Debug Terminal
2. Set a breakpoint in VS Code
   • Use the debugger keyword or set a breakpoint in the VS Code UI
3. Run your Node.js script from the terminal

Verbose API logs

Playwright supports verbose logging with the DEBUG environment variable.

DEBUG=pw:api npm run test

set DEBUG=pw:api
npm run test

$env:DEBUG="pw:api"
npm run test

DEBUG=pw:api mvn test

set DEBUG=pw:api
mvn test

$env:DEBUG="pw:api"
mvn test

DEBUG=pw:api pytest -s

set DEBUG=pw:api
pytest -s

$env:DEBUG="pw:api"
pytest -s

DEBUG=pw:api dotnet run

set DEBUG=pw:api
dotnet run

$env:DEBUG="pw:api"
dotnet run