Tests will fail. That is their job -- to tell you something is wrong. The question is: how fast can you figure out WHY it failed? Playwright gives you four debugging tools. Each one is for a different situation.
This opens the Playwright Inspector -- a step-by-step debugger. The test pauses at each action. You click "Step Over" to move to the next action. You see the browser and the code side by side.
# Debug all tests
npx playwright test --debug
# Debug a specific test file
npx playwright test banking-login.spec.ts --debug
# Debug a specific test by name
npx playwright test --debug --grep "should login"Sometimes you do not want to debug the whole test. You want to pause at a specific point. Drop page.pause() in your test and it freezes right there. Like putting a chai break in the middle of your code.
import { test, expect } from '@playwright/test';
test('debug login flow', async ({ page }) => {
await page.goto('/banking');
await page.getByLabel('Username').fill('testuser');
await page.getByLabel('Password').fill('password123');
// Test pauses here -- browser stays open
// You can inspect elements, try locators, check console
await page.pause();
await page.getByRole('button', { name: 'Login' }).click();
await expect(page.getByRole('heading', { name: /dashboard/i })).toBeVisible();
});When you use --debug or page.pause(), the Playwright Inspector window opens. This is your debugging cockpit.
The trace viewer is for AFTER the test has already failed. Especially useful for CI failures where you cannot see the browser. We covered this in Chapter 1, but here is the practical workflow.
Ensure trace is configured: trace: 'on-first-retry' in playwright.config.ts
The test fails in CI and automatically retries with tracing enabled
Download the trace.zip file from CI artifacts
Run: npx playwright show-trace trace.zip
Click through each action to see screenshots, DOM state, and network calls
Find the action that failed. Check the screenshot. Check the DOM. Fix the issue.
When page.pause() is active, you can type Playwright commands directly in the Inspector console. Try page.getByRole('button').count() to see how many buttons are on the page. Great for testing locators before writing them in code.
Remove all page.pause() calls before committing your code. If you leave one in, your CI pipeline will hang forever waiting for someone to click Resume. Use --debug for CI-safe debugging instead.
Q: How do you debug a Playwright test that fails only in CI?
A: I configure trace: 'on-first-retry' in playwright.config.ts. When a test fails, Playwright records a trace on the retry attempt. The CI pipeline uploads the trace.zip as an artifact. I download it and open it with npx playwright show-trace. The trace shows me screenshots at every step, DOM snapshots I can inspect, network requests with payloads, and console logs. I find the exact action that failed, see what the page looked like at that moment, and identify the root cause -- usually a timing issue, missing element, or different data in the CI environment.
Key Point: Four tools: --debug for step-through, page.pause() for breakpoints, Trace Viewer for CI failures, and UI mode for exploration. Pick the right one for the situation.