Playwright Frontend (Authoring Locatable Markup)

Audience: frontend engineers writing the app — the counterpart to the test-author guides in core/. Your job here is to expose a small, stable, machine-readable contract on the DOM so tests and AI agents can locate elements deterministically, without flakiness.

A data-testid is a public API for your UI's automation layer: once a test or agent depends on it, renaming it is a breaking change. Build accessible markup first, then add deliberate, well-named, unique, stable test IDs where automation needs a durable handle.

Guide Index

Golden Rules

1. Semantic HTML first — give elements a real role/label/accessible name so getByRole/getByLabel work; then add test IDs.
2. Add data-testid only where role, label and text fall short — no-role custom widgets, scope containers, list rows, and dynamic or localized regions. A control getByRole already finds uniquely needs none.
3. Name for global uniqueness — feature-component-element[-variant], kebab-case.
4. In lists, suffix with a stable domain key, never the array index — user-row-${user.id} ✅ / user-row-${index} ❌.
5. Decouple the value from text, locale, styling, and DOM position — those change; the test ID must not.
6. Standardize on one attribute — data-testid is Playwright's default testIdAttribute; don't mix data-test/data-qa.

Related

• core/locators.md / core/locator-strategy.md — the consumer side: choosing locators when writing tests.
• Playwright official docs: Locators, Best Practices.