In the previous article, we explored some advanced Playwright capabilities like tracing, fixtures, and parallel execution. These tools help prevent problems, but what happens when things still go wrong?
Let’s be honest — debugging automation tests can feel like detective work, especially when failures don’t make sense. I’ve had test scripts that pass locally and fail in CI.
Today, I’m going to show you how I debug Playwright tests in real projects, with techniques that saved me countless hours.
*1. Start With --debug Mode *
When something breaks, my first step is to slow down the test and watch it happen. Playwright makes this incredibly simple.
bash
npx playwright test --debug
This opens the Playwright Inspector — a live GUI where you can step through tests, interact with elements, and inspect selectors. It's like putting your test in slow motion.
You can pause at any step.
You see real-time element highlights.
It instantly shows why that click() didn’t click.
2. Use video and screenshot for Postmortem Debugging
Let’s say the failure only happens in CI and not locally. That’s painful — but also where recordings become life-saving.
In your playwright.config.ts, enable video and screenshot:
ts
use: {
video: 'on-first-retry',
screenshot: 'only-on-failure',
}
Now, when a test fails in GitHub Actions or Azure DevOps, I can grab the video and watch what went wrong — like a security camera replay of a test crash.
3. Check the Trace
If you read Day 4, you know tracing is amazing. But here’s how I actually use it in production:
ts
import { test } from '@playwright/test';
test('Trace Example', async ({ context, page }) => {
await context.tracing.start({ screenshots: true, snapshots: true });
await page.goto('https://yourapp.com');
// test steps
await context.tracing.stop({ path: 'trace.zip' });
});
Then run:
4. Log Strategically
While tools help, sometimes I fall back to good old logging:
ts
console.log('Navigating to dashboard...');
await page.goto('/dashboard');
This helps confirm where your test is getting stuck. Just don’t spam logs — too much noise makes debugging harder.
I’ve found it helpful to log:
Navigation steps
Critical actions
Assertion checkpoints
Tips From the Field
Use page.pause() to interact manually during a test run. Perfect for tweaking selectors.
Check CI environment logs — sometimes failures are environmental (wrong base URL, server down, etc.).
Run failed tests with --grep or --project to isolate faster.
Add tags or metadata to group tests, especially when debugging large suites.
Debugging is where test engineers prove their value. Anyone can write a passing test — but investigating failures, communicating root causes, and improving stability is what sets great testers apart.
Playwright gives us some of the best debugging tools I’ve seen in any automation framework — the trick is knowing how to use them.
Debug Smarter, Not Harder
Use --debug and page.pause() to step through tests live.
Record video and screenshots to analyze CI failures.
Inspect failures visually with Playwright Tracing.
Add smart logging for key checkpoints.
Top comments (0)