Playwright Debugging

Guide for writing, running, and debugging Playwright E2E tests.

Core Principles

1. Failing tests indicate real bugs. The tests interact with the real app. If a test fails, the app is broken — investigate the app, not the test.
2. Debug locally first. Read error messages, check screenshots/video, check browser console logs. Most issues are obvious once you look at the artifacts.
3. Fix the app, not the test. If the test exposes a real bug, fix the production code. Only change the test if the test itself is wrong (wrong selector, wrong expectation, race condition in the test).
4. Tests must be independent. Each test should manage its own state. Never depend on state from another test.

Debugging Approach

When a test fails, follow this sequence:

1. Read the Error Message

Playwright error messages are descriptive. They tell you exactly what selector failed and why. Start there.