How to Debug Test in Playwright – 5 Ways

Learning how to debug test in Playwright is essential for creating reliable automation scripts. Even well-planned tests can fail due to application changes, timing issues, or inaccurate selectors. Relying solely on terminal error messages often provides limited insight, making it harder to identify and fix problems efficiently.

Playwright offers powerful tools to make debugging easier and faster. From debug mode and Playwright Inspector to VS Code integration and the Trace Viewer, each method lets you pause execution, inspect actions, and analyze test behavior step-by-step.

In this guide, you’ll learn how to use these debugging tools step-by-step so you can resolve issues faster.

What is a Debug Test in Playwright?

Playwright debug is the process of using built-in tools and techniques to find the exact cause of a test failure. Instead of relying solely on error messages, debugging lets you interact with the test as it runs, observe the browser’s state, and understand each action in detail.

With Playwright’s debugging features, you can:

• Pause test execution at any point
• Inspect elements directly in the browser
• Step through code one action at a time
• Visually review how the browser responds to each step

This approach makes identifying and fixing issues far easier than reading logs alone.

Four Ways to Debug Test in Playwright

Imagine you have a sample Playwright test script(playwrightdemo.spec.js) and need to debug it. The question is, what is the best way to begin?

You can use the test code given below to practice and learn debugging in Playwright.

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

test('Playwright debug test demo', async ({ page }) => {

  await page.goto('https://playwright.dev/');

  // Click the Docs link.
  await page.getByRole('link', { name: 'Docs' }).click();

  //Verify page title.
  await expect(page).toHaveTitle(/Installation/);

  // Expects page to have a heading with the name of Installation.
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

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

test('Playwright debug test demo', async ({ page }) => {

  await page.goto('https://playwright.dev/');

  // Click the Docs link.
  await page.getByRole('link', { name: 'Docs' }).click();

  //Verify page title.
  await expect(page).toHaveTitle(/Installation/);

  // Expects page to have a heading with the name of Installation.
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Playwright provides four effective methods to start debugging tests:

1. Enabling Playwright’s debug mode
2. Using Playwright Test for VS Code extension
3. Using the page.pause() Method

Let’s learn all these methods one by one for debugging tests in Playwright.

#1: Debug Test in Playwright by Enabling Debug Mode

One of the simplest ways to debug test in Playwright is by running it in debug mode. This mode launches your test in a visual browser, opens the Playwright Inspector, and allows you to step through each action interactively. It’s ideal when you want to carefully observe what happens during execution without rushing through the steps.

To run a specific test file(playwrightdemo.spec.js) in debug mode, use the following command:

npx playwright test tests/playwrightdemo.spec.js --debug

npx playwright test tests/playwrightdemo.spec.js --debug

This tells Playwright to start your specified test file in debug mode.

Here’s what happens when you run this command:

• Visual browser launch: Instead of running in headless mode, Playwright opens the browser so you can watch each action happen in real time.
• Playwright Inspector opens: This interactive panel allows you to step through each line of the test, pause execution, or resume steps as needed.
  • Step Over: Click the Step Over button to execute your script line by line, moving to the next statement without diving into function calls.
  • Pause: Use the Pause button if you want to halt the test execution at any point during debugging.
  • Resume: Click the Resume button to continue running your test from where it was paused.

• Detailed logs available: The terminal displays rich logs of Playwright API calls, helping you understand exactly what’s happening.
• Locator verification: You can hover over elements in the browser to confirm selectors before the test proceeds.
• Pick Locator: You can also pick a locator directly from the page while debugging your test. This allows you to capture the exact selector for an element and use it in your script without manually inspecting the HTML.

#2: Debug Playwright Tests Using the Playwright Test for VS Code Extension

This debugging method is recommended by Playwright’s official documentation. The Playwright Test for VS Code extension makes debugging tests easier by integrating Playwright’s debugging features directly into the editor. This allows you to set breakpoints, step through code, inspect variables, and control execution without switching tools.

Configure Debugging Environment

Here’s how you can debug your test

• Install Playwright and VS Code:
  • Here is a step-by-step guideline on Playwright installation in VS Code.
• Install the Playwright Test for VS Code Extension:
  • Open VS Code and go to the Extensions Marketplace (Ctrl + Shift + X).
  • Search for Playwright Test for VS Code and click Install.

• Open Your Playwright Project:
  • Make sure your project has Playwright installed and a playwright.config file set up.
• Set Breakpoints:
  • Open the test file you want to debug.
  • Click in the left margin (gutter) next to the line numbers to add a breakpoint where you want the execution to pause.

Start Debugging

• Run the Test in Debug Mode:
  • Open your test file in VS Code.
  • Right-click on the Run icon that displays beside the test method.
  • Select the Debug test option from the context menu.

• It will launch the browser, and the test will start running in debug mode. Test execution will stop at your first breakpoint.

• Use Debug Controls:
  • Continue (F5): Resumes the test execution until the next breakpoint is hit or the test finishes.
  • Step Over (F10): Executes the current line of code without stepping into any function calls.
  • Step In (F11): Moves into the function being called on the current line to debug it step-by-step.
  • Step Out (Shift + F11): Finishes the current function’s execution and returns to the calling function.
  • Restart (Shift + Ctrl + F5): Stops the current debugging session and restarts the test from the beginning.
  • Stop (Shift + F5): Immediately ends the debugging session and stops test execution.
• Inspect Variables and Elements:
  • Hover over variables in the code to see their current values.
  • Use the Debug Console to evaluate expressions or run Playwright commands interactively.
• Debug test in Different Browsers:
  • You can select the browser for debugging by going to the Playwright section in VS Code and choosing your preferred browser — Chromium, Firefox, or WebKit — all of which are supported by Playwright.

#3: Start Playwright Debugging Using the page.pause() Method

The page.pause() method in Playwright is a powerful feature that lets you pause your test execution at any point. This is especially helpful when you want to inspect the browser state, check elements, or run Playwright commands interactively in the Playwright Inspector.

Here’s how you can debug your test using page.pause() in VS Code:

• Open Your Test File in VS Code:
  • Navigate to the test file you want to debug.
  • Make sure your Playwright project is already set up in VS Code.
• Insert the page.pause() Method:
  • Inside your test, decide where you want the execution to stop.
  • Add the following line at that point:

await page.pause();

await page.pause();

• This will pause the execution when the test reaches this line.
• Run the Test in Debug Mode:
  • In the VS Code terminal, run the following command to execute the test in debug mode.
  • It will start executing the test in Visual Browser.

npx playwright test tests/playwrightdemo.spec.js --headed

npx playwright test tests/playwrightdemo.spec.js --headed

• Choose a specific browser for Debugging:
  • Make sure all supported browsers are configured in the playwright.config.js file.
  • You can use flag –project chromium –headed to debug test in chromium, –project firefox –headed for firefox, and –project webkit –headed for webkit browser.
• Wait for Playwright Inspector to Open:
  • Once the test hits the page.pause(), the Playwright Inspector will appear.
  • Here, you can:
    • Hover over elements to see selectors
    • Execute Playwright commands directly
    • Step through the remaining code

#4: Debug Playwright Tests with the Trace Viewer

Trace Viewer in Playwright is a powerful tool that lets you debug your automated tests step by step. It records every action your test performs, along with screenshots, network logs, console messages, and DOM snapshots. This way, you can easily see what happened before, during, and after a failure. By opening the trace file in Trace Viewer, you can visually inspect each step, understand the test flow, and quickly identify the root cause of issues.

Steps to Debug Using Trace Viewer

• Enable Trace Recording in Your Test:
  • Add the trace: ‘on’ or trace: ‘retain-on-failure’ option in your Playwright configuration or test file.
  • This ensures Playwright records the trace while running your test.

test.use({ trace: 'on' });

test.use({ trace: 'on' });

• Run Your Test:
  • Execute your Playwright test as usual (e.g., run command: npx playwright test tests/playwrightdemo.spec.js in terminal). A .zip trace file will be generated inside the test-results folder.
• Open the Trace Viewer:
  • Use the following command in your terminal to open the recorded trace:
  • Replace your-folder-path with your actual path.

npx playwright show-trace test-results/your-folder-path/trace.zip

npx playwright show-trace test-results/your-folder-path/trace.zip

• Inspect the Timeline:
  • The Trace Viewer will open in your browser, showing a timeline of each test step along with actions, network requests, console logs, and screenshots.

• Click on Each Step:
  • Select individual steps to view details like:
    • Action log (what Playwright did)
    • DOM snapshot (page state at that moment)
    • Network activity
    • Screenshots
• Identify the Issue:
  • Follow the recorded actions and snapshots to see exactly where and why your test failed. This makes debugging faster and more accurate.

#5: Start Playwright Debugging Using $env:PWDEBUG=1 Command

Playwright provides an environment variable called PWDEBUG that allows you to run your tests in debug mode without modifying your test code. This method is especially useful when you want to pause execution at each step and inspect elements, network calls, and console logs in real time.

In VS Code, you can open the integrated terminal and set the environment variable before running your test command. On Windows PowerShell, you can use:

$env:PWDEBUG=1; npx playwright test tests/playwrightdemo.spec.js

$env:PWDEBUG=1; npx playwright test tests/playwrightdemo.spec.js

When this is enabled:

• The browser will launch in visual mode (so you can see the UI).
• Playwright Inspector will open automatically, allowing step-by-step debugging.
• You can pause, resume, and interact with the page while the test runs.

This method is quick and does not require adding extra code, such as page.pause() or modifying the Playwright config file, making it ideal for temporary debugging in any Playwright project.

Common Challenges When You Debug Tests in Playwright

While Playwright offers powerful tools for debugging, you might face some common challenges:

• Intermittent test failures: Sometimes, tests pass locally but fail in CI due to timing or environment differences.
• Slow test execution in debug mode: When using tools like page.pause() or the Inspector, tests can run slower than usual.
• Difficulty replicating browser-specific issues: Certain bugs only appear in Chromium, Firefox, or WebKit, making them harder to reproduce.
• Handling async code: Debugging can be tricky if promises or async operations aren’t handled correctly.
• Overhead of trace files: Continuous tracing can generate large files, impacting storage and test performance.

Key Benefits of Effective Playwright Debugging and Tracing

There are several advantages of debugging and tracing in Playwright:

• Faster issue resolution: Quickly identify and fix test failures without endless trial and error.
• Better test stability: Debugging ensures flaky tests are addressed and optimized.
• Improved test coverage: By finding hidden edge cases during debugging, you write more reliable tests.
• Detailed insight into browser actions: Tools like Trace Viewer reveal the DOM state, network calls, and console logs at each step.
• Efficient collaboration: Trace files and debug logs can be shared with team members for quick troubleshooting.

Proven Tips for Running and Debugging Tests in Playwright

To make the most of Playwright’s debugging features, keep these tips in mind:

• Run tests in visual mode to see exactly what happens in the browser.
• Use the page.pause() strategically to inspect the DOM at specific points.
• Enable trace only when needed to avoid unnecessary file sizes.
• Leverage Playwright Inspector to step through actions interactively.
• Combine debugging methods, for example, run in debug mode with trace enabled for complex issues.
• Test across multiple browsers early to catch browser-specific bugs.
• Integrate debugging into CI so you can capture logs and traces automatically on failures.

Final Words

Debugging is a vital part of writing stable and reliable Playwright tests. By using methods like debug mode, VS Code extension, page.pause(), Trace Viewer, and $env:PWDEBUG=1, you can identify and fix issues faster.

Moreover, effective debugging combined with tracing doesn’t just solve immediate problems—it improves your overall test quality, reduces flakiness, and boosts team productivity.

If you want to master Playwright debugging, start experimenting with each method and see which works best for your workflow. Over time, these skills will make your automated tests far more robust and trustworthy.

Aravind

Hi, I’m Aravind — a seasoned Automation Test Engineer with over 17 years of hands-on experience in the software testing industry. I specialize in tech troubleshooting and tools like Selenium, Playwright, Appium, JMeter, and Excel automation. Through this blog, I share practical tutorials, expert tips, and real-world insights to help testers and developers improve their automation skills.In addition to software testing, I also explore tech trends and user-focused topics, including Snapchat guides, codeless test automation, and more.