Smart Locators
Target roles, labels, text, and test ids with typed locators. Each action resolves the current page and waits for the conditions it needs.
- Auto-wait The action waits for its preconditions
- Semantic first Address the page the way a person reads it
- Narrowing Chain and filter instead of writing selectors
- Strict by default Two matches is an error, not a coin toss
Auto-wait
The action waits for its preconditions
A locator is a description, not a cached element. It resolves when you use it, and Playwright applies the actionability checks relevant to that action.
Timeouts and retries →// no sleep, no retry loop, no wait helper
$page->getByRole('button', ['name' => 'Sign in'])->click();
Semantic first
Address the page the way a person reads it
Role, label, placeholder, text, test id. These describe the page through user-facing meaning, so tests are less coupled to class names and DOM structure.
Locators reference →
Narrowing
Chain and filter instead of writing selectors
Locators compose. Start from a region, filter by text, take the row you need. The chain reads as a sentence and each link stays independently readable.
Read a table row →$row = $page->getByRole('row')
->filter(['hasText' => 'ada@example.com']);
$row->getByRole('button', ['name' => 'Delete'])->click();
Strict by default
Two matches is an error, not a coin toss
A locator that resolves to several elements raises instead of silently picking the first. The failure points to the ambiguous target where it is used.
Core concepts →
Next step
Move from the tour to working code.
Choose the explanation, recipe, or runnable example that matches what you need next.
Common questions
Before you wire it into a suite.
Should I still write CSS selectors?
Use role, label, text, placeholder, and test id locators first. Keep CSS selectors for structural cases where the page has no user-facing hook yet.
Why do locators fail when several elements match?
Strict matching is deliberate. If a locator can point to two elements, the test should narrow the target instead of clicking whichever one happens to come first.
Do locators wait automatically?
Yes. A locator resolves when you act or assert on it, and Playwright waits for the element to be actionable before performing the operation.