How do you troubleshoot flaky tests in Playwright?

Start by reproducing the failure with a trace rather than guessing - enabling trace: 'on-first-retry' captures exactly what happened the moment a test first becomes unreliable, including DOM snapshots and network timing.

Next, check whether the flakiness comes from a race condition the test itself introduced - a manual wait, a raw page.click() on a selector without going through a retrying locator, or an assumption about ordering in async data. Auto-waiting removes most timing bugs, but it can't fix a locator that matches the wrong element intermittently (for example, one that matches multiple rows in a list that reorders).

Isolate whether the flake is environment-specific by running the exact same test repeatedly with --repeat-each, and check if it only fails under parallel execution, which can point to shared external state (like a shared test account) rather than a Playwright issue at all.

Finally, avoid masking the symptom by just adding retries in config without first confirming the root cause - retries hide a real bug just as easily as they mask genuine environmental flakiness.