Introduction
Learning how to debug Playwright test failures is one of the most valuable skills for QA Automation Engineers, SDETs, Selenium engineers transitioning to Playwright, software testing students, QA engineers, and developers. Even well-designed automation frameworks occasionally encounter issues such as missing elements, synchronization problems, flaky tests, authentication failures, or unexpected application behavior.
Playwright includes powerful built-in debugging tools that make diagnosing failures significantly easier than traditional automation frameworks. Features like Playwright Inspector, Trace Viewer, screenshots, video recording, debug mode, and VS Code integration help identify the exact cause of a failed test.
In this how to debug Playwright test failures tutorial, you’ll learn:
- What debugging is in Playwright
- How to use Playwright Inspector
- How to enable Trace Viewer
- How to capture screenshots and videos
- How to debug using VS Code
- Real-world debugging examples
- Best practices
- CI/CD integration
- Interview questions
What Is Debugging in Playwright?
Debugging is the process of identifying, analyzing, and fixing issues that cause automated tests to fail.
Common Playwright test failures include:
- Element not found
- Timeout errors
- Incorrect locators
- Authentication failures
- Network issues
- Flaky tests
- Unexpected page navigation
- Assertion failures
Playwright provides several built-in debugging tools that reduce the time required to identify these issues.
Benefits of Debugging Playwright Test Failures
Understanding how to debug Playwright test failures provides several advantages:
- Faster root cause analysis
- Reduced flaky tests
- Improved framework reliability
- Easier maintenance
- Better CI/CD visibility
- Faster issue resolution
- Higher automation stability
- Improved developer and tester productivity
Step-by-Step Tutorial: How to Debug Playwright Test Failures
Step 1: Run Tests in Debug Mode
Use the following command:
npx playwright test –debug
What Happens?
- Playwright Inspector
- Browser in headed mode
- Pauses before every action
This allows you to inspect locators and execute actions step by step.
Practical use case: Debugging element interaction problems.
Step 2: Use Playwright Inspector
Playwright Inspector is an interactive debugging tool.
import { test, expect } from ‘@playwright/test’;
test(‘Login’, async ({ page }) => {
await page.goto(‘https://example.com’);
await page.getByLabel(‘Username’).fill(‘admin’);
await page.getByLabel(‘Password’).fill(‘admin123’);
await page.getByRole(‘button’, {
name: ‘Login’
}).click();
await expect(page).toHaveURL(/dashboard/);
});
Run:
npx playwright test login.spec.ts –debug
Why Inspector Is Useful
You can:
- Pause execution
- View locators
- Resume execution
- Step through commands
- Inspect page elements
Step 3: Enable Trace Viewer
Update playwright.config.ts.
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
use: {
trace: ‘on-first-retry’
}
});
npx playwright test
Open the trace:
npx playwright show-trace trace.zip
Benefits of Trace Viewer
Trace Viewer records:
- Every click
- Every locator
- Network requests
- Console logs
- Screenshots
- DOM snapshots
It provides a timeline that helps you understand exactly what happened before the failure.
Step 4: Capture Screenshots
Automatically capture screenshots on failures.
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
use: {
screenshot: ‘only-on-failure’
}
});
Practical Use Case
If a login button is hidden by a modal dialog, the screenshot clearly shows the issue.
Step 5: Record Videos
Enable video recording.
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
use: {
video: ‘retain-on-failure’
}
});
Why Record Videos?
Videos allow you to watch the exact sequence of browser actions leading to the failure.
Step 6: Add Console Logs
test(‘Debug Login’, async ({ page }) => {
console.log(‘Opening Login Page’);
await page.goto(‘https://example.com’);
console.log(‘Entering Username’);
await page.fill(‘#username’, ‘admin’);
});
Explanation
Strategic logging helps identify where the execution stops.
Step 7: Use Breakpoints
await page.goto(‘https://example.com’);
debugger;
await page.click(‘#login’);
Run with:
PWDEBUG=1 npx playwright test
Execution pauses at the debugger statement, allowing inspection of variables and page state.
Step 8: Debug in VS Code
Create a .vscode/launch.json configuration.
{
“version”: “0.2.0”,
“configurations”: [
{
“type”: “node”,
“request”: “launch”,
“name”: “Playwright Debug”,
“program”: “${workspaceFolder}/node_modules/@playwright/test/cli.js”,
“args”: [
“test”
]
}
]
}
Benefits
- Step over
- Step into
- Watch variables
- Evaluate expressions
- Set conditional breakpoints
Real-World Debugging Examples
1. Element Not Found
await page.locator(‘#login’).click();
Problem: Locator does not exist.
Solution:
- Verify selector
- Use getByRole() or getByLabel()
- Inspect the page using Playwright Inspector
2. Timeout Errors
await expect(page.locator(‘.success’))
.toBeVisible();
Problem: Element loads slowly.
Solution:
Use Playwright’s built-in auto-waiting and verify the application’s response rather than adding arbitrary delays.
3. Flaky Tests
- Dynamic content
- Slow network
- Race conditions
Recommendation:
- Prefer resilient locators
- Wait for meaningful conditions
- Eliminate fixed waits
4. Network Failures
Enable tracing to inspect:
- Failed API requests
- Response codes
- Request timing
This helps determine whether the issue is in the frontend, backend, or test itself.
5. Authentication Issues
Common symptoms:
- Redirected back to login
- Session expires unexpectedly
- Unauthorized (401) responses
Debugging Tips:
- Verify storageState
- Inspect cookies in Trace Viewer
- Check authentication tokens
6. Locator Problems
Instead of:
await page.locator(‘div:nth-child(4)’).click();
Use:
await page.getByRole(‘button’, {
name: ‘Submit’
}).click();
Stable, accessibility-based locators reduce failures and make debugging easier.
Playwright Debugging vs Selenium Debugging
| Feature | Playwright | Selenium |
| Playwright Inspector | ✅ Built-in | ❌ No |
| Trace Viewer | ✅ Built-in | ❌ External tools |
| Screenshots | Native | Manual configuration |
| Video recording | Native | Third-party tools |
| Auto waiting | Built-in | Mostly manual |
| Debug mode | –debug | IDE dependent |
| Network inspection | Built-in tracing | Browser DevTools or proxies |
Why Playwright Is Easier to Debug
Playwright integrates debugging capabilities directly into the framework, reducing the need for external tools and making failure analysis much faster.
CI/CD Integration
Debugging should be part of every CI/CD pipeline.
Typical workflow:
Developer Commit
│
▼
│
▼
Capture Trace
│
▼
Capture Screenshot
│
▼
Record Video
│
▼
Publish HTML Report
Enterprise recommendations:
- Enable traces on retries.
- Retain screenshots and videos for failed tests.
- Publish Playwright HTML reports as pipeline artifacts.
- Configure notifications for recurring failures.
Best Practices for Debugging Playwright Tests
Follow these recommendations:
- Use Playwright Inspector during local debugging.
- Enable Trace Viewer for failed or retried tests.
- Capture screenshots only on failures.
- Record videos for difficult issues.
- Prefer accessibility-based locators.
- Add meaningful assertions after critical actions.
- Avoid hard-coded waits such as waitForTimeout().
- Investigate flaky tests instead of masking them with retries.
Common Issues & Troubleshooting Tips
| Problem | Solution |
| Locator not found | Inspect the DOM and use stable locators like getByRole() or getByLabel(). |
| Test timeout | Verify application performance and rely on Playwright’s auto-waiting. |
| Authentication failure | Validate storageState, cookies, and authentication tokens. |
| Flaky test | Remove fixed waits, improve locators, and inspect traces. |
| CI/CD-only failure | Compare environment differences, browser versions, and network access. |
Playwright Debugging Interview Questions with Answers
1. What is Playwright Inspector?
It is a built-in debugging tool that allows step-by-step execution, locator inspection, and interaction with the browser during test execution.
2. What is Trace Viewer?
Trace Viewer is a visual debugging tool that records actions, screenshots, network requests, console logs, and DOM snapshots to help analyze test failures.
3. Which command starts Playwright in debug mode?
npx playwright test –debug
4. How do you capture screenshots only for failed tests?
Configure:
screenshot: ‘only-on-failure’
in playwright.config.ts.
5. How do you reduce flaky Playwright tests?
Use stable locators, rely on Playwright’s auto-waiting, review traces, remove unnecessary fixed waits, and investigate timing issues instead of simply increasing timeouts.
FAQs
What is how to debug Playwright test failures?
It is the process of identifying and resolving issues in Playwright tests using tools such as Playwright Inspector, Trace Viewer, screenshots, videos, logs, and breakpoints.
How do I get started with how to debug Playwright test failures?
Install Playwright, run tests with the –debug flag, enable Trace Viewer, capture screenshots and videos for failures, and use VS Code or Playwright Inspector to investigate problems.
Is how to debug Playwright test failures suitable for beginners?
Yes. Playwright provides beginner-friendly debugging tools with visual interfaces and automatic waiting, making it easier to diagnose issues than many traditional automation frameworks.