How to Fix Flaky Playwright Tests

📝 Draft stub. Outline is in place — full write-up with code samples coming soon. Structure below shows where the content will land.

A flaky test is one that passes and fails on the same code. It's the single fastest way to erode a team's trust in its test suite — once engineers start re-running the pipeline "just to be sure," the safety net is already gone. Playwright removes a whole class of flakiness with built-in auto-waiting, but flaky tests still slip in. Here's where they come from and how to shut them down.

Why Playwright tests go flaky

• Racing the app, not the framework. Auto-waiting handles the element — but not your data. Assertions that fire before an API response lands are the most common culprit.
• Manual waits. Hardcoded waitForTimeout calls paper over races and break the moment CI runs slower than your laptop.
• Shared state between tests. Tests that reuse a user, cart, or record pass alone and fail in parallel.
• Weak locators. Locators tied to text or DOM position break under localization, re-renders, or animation.
• Environment noise. Third-party scripts, animations, and time-of-day data introduce nondeterminism.

The fix — a repeatable playbook

1. Assert on state, use web-first assertions

Replace manual waits with expect(locator).toBeVisible() and friends — they retry until the condition holds or time out. Wait on the outcome you care about, not a fixed delay.

2. Isolate every test

Each test creates and tears down its own data. No shared users, no ordering assumptions. This is what makes parallel runs safe.

3. Use resilient, intent-based locators

Prefer role- and test-id-based locators (getByRole, data-testid) over brittle CSS or text selectors.

4. Control the network

Mock or wait for the specific requests a test depends on. Freeze time and stub randomness so results are deterministic.

5. Quarantine, then fix — don't just retry

Retries hide flakiness; they don't remove it. Tag flaky tests, track them, and treat each as a real defect until the root cause is gone.