Find elements the way people do

Find elements by their role, label or visible text. Never by CSS classes or page structure that change with the design.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Use queries such as getByRole, getByLabel and getByText in Playwright or Testing Library. When nothing visible fits, add a data-testid on purpose. These queries also prove that buttons and fields have accessible names.

Example

// Bad: breaks when the design changes
await page.locator('div.card > .btn-primary:nth-child(2)').click();

// Good: survives a redesign and checks the accessible name
await page.getByRole('button', { name: 'Add to cart' }).click();

# Playwright for Python
page.get_by_role("button", name="Add to cart").click()

// Playwright for Java
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Add to cart")).click();

How to check

Search the browser tests for CSS and XPath selectors, such as locator('., locator('#, locator('// or xpath=. There are none, or each has a comment explaining why.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers testing playbook: https://agentwranglers.se/playbook/testing/end-to-end-and-browser-tests/stable-selectors.