Skip to content
agent-skills

Playwright Locators Assertions And User Visible Contracts

Pack: playwright Source: playwright/playwright-locators-assertions-and-user-visible-contracts/SKILL.md Use this skill when test fragility is mostly about how the test finds things and what it asserts.

Scope

Section titled “Scope”
  • locator strategy
  • web-first assertions
  • actionability expectations
  • accessible roles, labels, and visible text
  • stable contracts for end-to-end tests

Routing cues

Section titled “Routing cues”
  • locator choice, flaky selectors, getByRole, getByLabel, locator(), text assertions, expect(locator), actionability, auto-waiting, or stable UI contracts -> use this skill
  • suite architecture, fixtures, or config shape -> use playwright-default-test-architecture
  • auth setup or storage state reuse -> use playwright-auth-projects-and-isolation
  • network mocking or request synchronization -> use playwright-network-control-and-api-synchronization
  • trace-based debugging or codegen cleanup -> use playwright-debugging-traces-and-flake-reduction

Default path

Section titled “Default path”
  1. Use user-visible locators first: role, label, placeholder, text, alt text, or title.
  2. Prefer expect(locator) web-first assertions over manual polling or arbitrary waits.
  3. Let Playwright actionability checks do their job before adding more synchronization.
  4. Use test IDs only where user-visible semantics are genuinely unstable or absent.
  5. Assert meaningful UI outcomes, not incidental DOM structure.

When to deviate

Section titled “When to deviate”
  • Use test IDs when the surface is intentionally non-semantic or the text is too unstable.
  • Use lower-level CSS or DOM selectors only for targeted edge cases where semantic contracts are impossible.
  • Use text assertions narrowly when the product copy is part of the contract, not when content churn is expected.

Guardrails

Section titled “Guardrails”
  • accessible roles and labels are the preferred contract
  • assertions should wait on the UI state you actually care about
  • test IDs are a fallback, not the default locator system
  • one stable locator is better than several chained brittle ones

Avoid

Section titled “Avoid”
  • brittle CSS selectors tied to nesting or styling classes
  • waitForTimeout as synchronization
  • asserting implementation details like hidden wrappers or internal DOM counts
  • mixing several locator strategies in one test without a reason

Verification checklist

Section titled “Verification checklist”
  • the primary locators match user-visible semantics where possible
  • assertions use Playwright’s web-first model
  • no arbitrary timeout is carrying the test
  • any test IDs are intentional and limited
  • the test would survive a presentational refactor that keeps behavior intact

Quick example

Section titled “Quick example”
await page.getByRole("button", { name: "Save" }).click();
await expect(page.getByRole("status")).toHaveText("Saved");

Current snapshot

Section titled “Current snapshot”
  • Checked against official docs on 2026-04-03
  • Current npm line verified live on 2026-04-03: @playwright/test@1.59.1
  • Docs in scope: locators, actionability, auto-waiting, and assertions

Official references

Section titled “Official references”

References

Section titled “References”