Roadmap
Selector Foundations Beginner
Playwright locators inherit CSS awareness and layer on
modern pseudo selectors such as :has(),
:text(), and :nth-match(). Start with
deterministic hooks whenever you can.
Static locator checklist
- Prefer semantic IDs (
#static-username). -
Use
data-testordata-testidattributes for automation. -
Scope by component (
.login-form input[name='static-password']). - Add a short assertion so the selector fails loudly.
// Playwright static selectors demo (from
PlaywrightSelectorTest)
Locator usernameField = page.locator("#static-username"); Locator passwordField = page.locator("input[name='static-password']"); Locator rememberMe = page.locator("label.login-toggle input"); Locator primaryCta = page.locator("[data-test='primary-cta']"); usernameField.fill("qa.analyst@acme.dev"); passwordField.fill("SuperSecret!");
rememberMe.check(); primaryCta.click(); expect(page.locator("#cta-result")).toHaveText("CTA clicked via static selectors");
Pro tip:
locator() auto-waits for the
element to be actionable. Avoid page.waitForTimeout -
let locators synchronize the UI for you.
Intermediate Patterns Skilled
Once the DOM becomes noisy, compose locators by combining attribute wildcards, structural filters, and scoping.
| Pattern | When to use | Example |
|---|---|---|
[data-row-id^='user-'] |
ID prefixes (server-generated handles). |
page.locator("[data-row-id^='user-']").first()
|
.feed-card:has-text('Pinned') |
Cards or rows with unique copy. |
page.locator("li.feed-card:has-text('Pinned')")
|
:nth-match(locator, index) |
Multiple identical CTAs. | page.locator("button.promote-btn").nth(1) |
// Scoped dynamic selection
Locator newestRow = page.locator("[data-row-id^='user-']").last(); Locator promoteButton = newestRow.locator("button.promote-btn"); promoteButton.click(); Locator designCard = page.locator(
"li.feed-card:has(.content-pill:has-text('Pinned'))"
); expect(designCard.locator("p")).toContainText("Design System");
Advanced Dynamic Targeting Advanced
Complex enterprise apps often generate GUID-based IDs and nested components. Combine Playwright-only capabilities with fallback XPath for the rare edge case.
Hook element
⟶
Filter (has-text, nth-match)
⟶
Fallback XPath
// Pattern 1: :has-text chaining
Locator onboardingTile = page.locator(
"section.dashboard-tile:has-text('Onboarding Checklist')"
); onboardingTile.locator("button:has-text('Start now')").click();
// Pattern 2: Text-first dynamic tables
Locator statusChip = page.locator(
"tr:has(td:has-text('CRM Sync')) td.status span"
); expect(statusChip).toHaveText("Healthy");
// Pattern 3: XPath fallback when DOM lacks hooks
Locator xpathFallback = page.locator(
"xpath=(//div[@data-row-id])[last()]"
); expect(xpathFallback).toContainText("@dynamic");
Remember: XPath is still valuable for relationship
queries, but keep it as the exception. A readable CSS+has-text
locator is easier to debug.
Debugging & Anti-Flake Expert
Bad selectors usually manifest as flaky tests. Instrument your locators the same way you observe API calls.
-
Use
locator.highlight()in headed mode: Keep a helper that callspage.pause()and highlights the selector so you can visually confirm the match. -
Leverage trace viewer:
npx playwright show-tracedisplays animations, DOM snapshots, and the exact selector Playwright attempted. -
Record custom data hooks: Ask frontend teams to
add
data-qa/data-testidattributes as part of their definition of done to guarantee future proof selectors.
Fast safety net: The repository now includes
PlaywrightSelectorTest so you can iterate on selectors
in isolation without touching production UIs.