🐞 Debugging Playwright Tests: Best Practices

✅ 1. Run Tests in Headed Mode

Headless mode can make debugging harder. Use headed mode to see the browser in action:

bash

Copy

Edit

npx playwright test --headed

This helps you visually understand what’s happening during test execution.

🧭 2. Use Playwright Inspector with --debug

To step through your test code:

bash

Copy

Edit

npx playwright test --debug

Pauses the test and opens the Playwright Inspector

Lets you step, resume, and inspect the browser state interactively

⏸️ 3. Insert page.pause() to Interactively Debug

Add this in your test script where you want to pause:

ts

Copy

Edit

await page.pause();

This opens an interactive session where you can:

Inspect the DOM

Try out selectors

Step through remaining actions

🐛 4. Use debugger Statement with PWDEBUG=1

Add a JavaScript debugger statement in your test:

ts

Copy

Edit

debugger;

Then run the test like this:

bash

Copy

Edit

PWDEBUG=1 npx playwright test

This lets you use breakpoints and inspect variables in your editor (e.g., VS Code).

🧪 5. Enable Tracing for In-Depth Analysis

In your Playwright config or test file, enable tracing:

ts

Copy

Edit

use: {

  trace: 'on-first-retry', // or 'always' / 'retain-on-failure'

}

After a test run, use:

bash

Copy

Edit

npx playwright show-trace trace.zip

This opens a visual trace viewer with:

DOM snapshots

Action timelines

Network logs

Console messages

📸 6. Capture Screenshots and Videos

Update your playwright.config.ts:

ts

Copy

Edit

use: {

  screenshot: 'only-on-failure',

  video: 'retain-on-failure',

}

Manually capture screenshots as needed:

ts

Copy

Edit

await page.screenshot({ path: 'error.png' });

📝 7. Print Console and Network Logs

Log browser console messages:

ts

Copy

Edit

page.on('console', msg => console.log(msg.type(), msg.text()));

Track network requests:

ts

Copy

Edit

page.on('request', request => console.log('Request:', request.url()));

This is useful for debugging API calls or frontend errors.

🔍 8. Use .only to Isolate Failing Tests

Narrow your focus by running just one test:

ts

Copy

Edit

test.only('My failing test', async ({ page }) => {

  // debug here

});

Or use a grep filter:

bash

Copy

Edit

npx playwright test --grep "Login Test"

🧹 9. Reset State with beforeEach and afterEach

Ensure tests don’t interfere with each other:

ts

Copy

Edit

test.beforeEach(async ({ page }) => {

  await page.goto('https://example.com');

});

test.afterEach(async ({ context }) => {

  await context.clearCookies();

});

🛠️ 10. Use Playwright Codegen to Generate and Test Selectors

Launch Playwright Codegen to record steps and extract working selectors:

bash

Copy

Edit

npx playwright codegen https://example.com

You can click through the app, and Playwright will generate the test code live.

🧠 Summary Table

Practice Benefit

--headed, --debug Visual debugging and step-through execution

page.pause() Interactive browser inspection

debugger + PWDEBUG=1 Breakpoint-style debugging

Tracing Post-mortem analysis with timeline & snapshots

Screenshots/Videos Understand UI issues and failures

Console & network logs Debug app logic and API behavior

.only, --grep Focus on a specific test

Fixtures (beforeEach) Isolate test environments

Codegen Validate selectors and interactions

Would you like an example project or config file for setting up Playwright with debugging tools pre-configured?

Learn Playwright Training Course in Hyderabad

Visit Our IHUB Talent Training Institute in Hyderabad

Get Directions