Playwright locator strategy for beginners: stop inspecting HTML, start reading the accessibility tree

Five rungs and that is the entire ladder. The first one covers about 80% of what you will ever click in a test; the last one is your escape hatch for the elements that genuinely have no semantic identity. Everything in between exists because forms are a special case: inputs deserve their own locators because they often lack accessible names a screen reader would speak, and Playwright builds those locators on top of the <label> association the browser already knows about.

Why every beginner picks the wrong locator the first time

You open the page. You right-click the Sign In button. DevTools opens. You see a giant tree of div elements, two of which have classes that look like .btn-primary and .cta-submit. You pick one. You write a locator. It works. Then a week later it does not, and you do not know why.

The problem is the layer you are looking at. The DOM is for browsers and CSS. It changes whenever a designer reorganises a layout, a CSS-in-JS library rehashes a class name, or a developer wraps something in a new container. The accessibility tree is for assistive technology. It changes when the meaning of the page changes, not when the styling does. Locators that ride the accessibility tree survive layout refactors. Locators that ride the DOM do not.

The decision tree, in plain English

Walk this list from top to bottom. The first rule that matches is your locator. You do not need to memorise ARIA roles, and you do not need to know how Playwright resolves them internally. You just have to ask one question at a time about the element you are looking at.

The accessibility tree is the shortcut nobody tells beginners about

The decision tree above tells you which locator type to use. It does not tell you the exact role string or accessible name to pass into it. That is the part where beginners get stuck. The trick is to stop trying to derive the answer from the HTML and to ask the browser directly. Both Chrome DevTools and Playwright MCP will hand you a serialised tree where every node is already labelled with its role and accessible name. Copy them in.

Once you have done this five or six times, you stop needing the tree. The vocabulary becomes muscle memory: a clickable element with text on it is almost alwaysrole="button" with that text as its accessible name. A link is role="link". A toggle is role="switch". A tab strip is role="tab" inside role="tablist". The tree is the training wheels; once it has taught you what the page exposes, you do not need to call it for every locator.

What an AI test agent does (and why the algorithm matches the beginner advice)

The agent inside Assrt does exactly what the decision tree above prescribes, just on a tighter loop. It calls snapshot before every interaction, reads the accessibility tree, picks the node by role and accessible name, performs the action, and re-snapshots after. When the test is written back to disk, it serialises the locators as getByRole and getByLabel, the exact things this guide is asking you to write by hand. You can read the strategy verbatim:

That 5-step runbook is the load-bearing piece of the agent's system prompt. It is the same five steps you should run in your own head when you are picking a locator: look at the tree, find the element by what it is, use its identity, and re-look if it moves. The package is MIT-licensed and published on npm as @m13v/assrt, so you can clone the repo and verify line 206 yourself.

The thing to notice about this sequence is that you, the beginner, only ever say one thing: "click Sign In". The agent does the snapshot, the role lookup, and the click on your behalf, and the test file it commits to your repo is the same getByRole('button', { name: 'Sign In' }) you would have written by hand if you had read the tree yourself. There is no proprietary locator format hiding in the artifact; what is on disk is standard Playwright.

When one locator is not enough: chain, do not index

Sooner or later a page will have two Submit buttons. The instinct most beginners have is to reach for .first() or .nth(1). Do not. Both methods couple your test to the render order, which is fine until someone adds a third Submit button at the top of the page and your locator silently shifts targets.

The chain-rather-than-index pattern is in the Playwright docs and it goes like this:

Same idea for repeated list items. Use .filter({ hasText }) to pin a row by something a user can read, and then drill into it for the action. The test becomes self-documenting: the next person who reads it can see exactly which row was clicked, without running the test to find out.

What to commit to your repo (and what not to)

The accessibility-tree refs the agent uses at runtime are not selectors. They are snapshot-relative IDs that only mean something inside the snapshot they came from. They do not exist in the DOM and they would be useless in a committed test file two minutes later. So when an agent writes a test, or when you write it yourself, never put a ref in the file.

What you commit is the user-facing locator that resolved the same node, expressed in the form a teammate can read: getByRole, getByLabel, getByText, getByTestId. Two layers, two artifacts, one consistent vocabulary.