What Will You Read in This Blog?
- Why “flaky” is almost never the framework’s fault and how to prove it in five minutes.
- The locator priority ladder: the exact order Playwright’s own docs tell you to follow.
- Why
expect(await locator.isVisible())is the single worst line in your test suite. - The three things auto-waiting does not wait for (and the hard-coded timeouts hiding in your code).
beforeEachdone correctly and the one place it silently recreates the problem.- A copy-paste locator cheat sheet.

The Two-Minute Diagnosis
Open your test suite. Search for three things:
waitForTimeout OR
.isVisible()ORpage.locator('.
If any of those return results, you don’t have a flaky test problem. You have a locator problem that occasionally manifests as a timeout. Those are different problems with different fixes, and treating the first as the second is why teams spend months “stabilizing” a suite that was never unstable.
Here’s the uncomfortable version: most Playwright suites don’t need better infrastructure. They need better selectors. No amount of retries, parallelization, or CI tuning fixes a test that clicks .btn-primary.submit.
The Locator Priority Ladder
Playwright’s locator documentation is unusually blunt about this: prioritize user-facing attributes and explicit contracts. The order, most to least resilient:
getByRole– ARIA role + accessible name. How assistive tech and humans find elements.getByLabel– form fields tied to a<label>.getByPlaceholder,getByText,getByAltText,getByTitle– semantic fallbacks.getByTestId– an explicit contract with your developers.- CSS / XPath – last resort. Binds tests to implementation details.
// ❌ Breaks on any class rename, any refactor, any CSS module migration
await page.locator('.btn-primary.submit').click();
// ✅ Breaks only if the actual button changes
await page.getByRole('button', { name: 'Submit order' }).click();
The CSS locator survives nothing. The role locator survives redesigns, class renaming, and CSS-in-JS migrations because it’s tied to what the user sees, not how it’s built.
One nuance: getByRole is strict by default. Two matches throws. That’s a feature it forces unambiguous selectors. If it throws, your test was about to click the wrong element.
The Worst Line in Your Suite
// ❌ No retry. Races the browser. Fails at random.
expect(await page.locator('.toast').isVisible()).toBe(true);
// ✅ Auto-retries until timeout.
await expect(page.locator('.toast')).toBeVisible();
The manual version samples state at one instant. If the toast renders 50ms later, you fail. The web-first assertion retries the assertion until it passes or times out.
This is the distinction: web-first assertions auto-retry. expect(await locator.isVisible()) does not. That single line of misunderstanding accounts for more “random” CI failures than any other cause.
toBeVisible, toHaveText, toHaveURL, toHaveCount, toContainText – learn these and manual waits mostly disappear.
What Auto-Waiting Actually Waits For
Before clicking, Playwright checks the element is attached, visible, stable, enabled, and receives events. Before typing, that it’s editable.
It does not wait for:
- Network responses – use
waitForResponse, or better, assert on the UI the response produces. - Animations finishing – moving elements can fail the stability check. Assert the end state.
- Your business logic – if “logged in” means a redirect, assert
toHaveURL.
The mental model: Playwright waits for the browser, not your backend. That boundary explains most of the hard-coded waits in your codebase.
If This Feels Like Too Much
It isn’t. You don’t need to rewrite the suite.
Pick one spec. Replace its CSS selectors with getByRole. Swap its .isVisible() checks for toBeVisible(). Delete one waitForTimeout. Run it twenty times. That’s the whole exercise-and it usually takes under an hour.
Do that before you touch anything else. Most teams find it fixes more than the “big refactor” plan would have.
Hooks, Done Right
test.beforeEach(async ({ page }) => {
await page.goto('/dashboard');
});
beforeEach runs in a fresh browser context per test, so navigation state can’t leak between specs. Reserve afterEach for data cleanup never for “reset” logic that hides a real test dependency.
The one place this backfires: if your beforeEach performs a login flow, you’ve made every test slower and added a single point of failure to all of them. Move auth to a reusable storage state instead and let hooks stay fast.
Frequently Asked Questions
Should I use data-testid or role locators?
Role locators for anything a user interacts with. data-testid for elements with no accessible role. Never CSS classes.
Why does getByRole throw a strict mode violation?
It matched multiple elements. Narrow with { exact: true } or scope it: page.getByRole('dialog').getByRole(...).
Can I still use waitForTimeout?
Treat every occurrence as a bug ticket. Replace with a web-first assertion or explicit waitForResponse.
Read more like this at: Blogs
