Structural locators are not the right primitive for AI Playwright tests. The accessibility-tree ref is.

The two-layer model

Most arguments online collapse the runtime layer and the disk layer into one decision. They are not the same decision.

The runtime layer is what the AI agent does in the moment it is about to click something. It needs an unambiguous handle on the element it just looked at. The disk layer is what gets committed to tests/checkout.spec.ts and read by a human three months later, or by a different agent on the next run.

A structural locator like div.app > div:nth-child(2) > button.btn.cta is a string. It survives between layers, which sounds convenient, but that survival is exactly what makes it brittle. The string was captured against one DOM at one moment. The DOM is constantly drifting. By the time the test runs again, the string is a fossil.

The two-layer model fixes this by refusing to ship the string between layers at all. At runtime, the handle is a ref pinned to a fresh snapshot. At rest, the handle is a semantic description (role plus accessible name) the agent re-resolves against the current tree on the next run. Neither side persists a coupling to render order.

What the agent actually clicks

The Assrt agent has a system prompt that names this directly. It is worth reading in full because the warning at the bottom is the part that competing pages miss:

The last line is the load-bearing one. A new contributor reading the agent's tool calls might guess that ref="e5" is some kind of attribute on a button ([ref="e5"], surely?). It is not. It is an opaque ID Playwright MCP minted when it serialized the accessibility tree. The browser does not know it exists. Trying to query it with a CSS selector returns nothing.

What goes wrong when an LLM ships a structural locator

The fastest way for an AI test generator to ship structural locators is to read the rendered HTML, find a path, and emit it. It happens when the model treats the DOM as the source of truth rather than the accessibility tree. Here is the failure mode in code:

Side by side: what gets shipped to your repo

The output side of an AI testing tool is where structural locators either show up in your codebase or do not. This is also the dimension on which most closed-source tools punt: they emit YAML or a proprietary scenario format, so the question of whether the underlying handle is a CSS chain or a role-based locator never surfaces in your repo at all. You cannot review what you cannot see.

// what AI-generated Playwright tests sometimes ship,
// because the model copied a Chrome DevTools "copy selector"
await page
  .locator(
    "#root > div.app > div:nth-child(2) > main > section.checkout > "
    + "div.summary > button.btn.btn-primary.cta-checkout"
  )
  .click();

await page
  .locator("xpath=//div[@id='order']/div[3]/div[1]/span[2]")
  .innerText();

await page
  .locator(".promo-apply")  // class will be hashed at next build
  .click();

The right column is two things at once. The first half is the runtime: the agent calling Assrt's tools with refs from a snapshot it just took. The second half is the durable artifact: the Playwright code Assrt writes to disk, in standard page.getByRole form. A reviewer can read it without running it. A new agent on the next CI run can re-resolve it without knowing what the page looked like last week.

The runtime sequence in one diagram

Here is what actually happens when the Assrt agent decides to click the Checkout button. Note that no string selector ever travels from the agent to the browser:

Step 6 is where the architectural break happens. The agent never sees, holds, or sends a CSS string. It sees ref=e42 and a human-readable element description for logging. The ref is only valid against this snapshot. If the next click fails, step 1 repeats and a fresh ref is minted. There is no cached selector to go stale.

The honest counterargument: when do CSS selectors still earn a place?

A guide that pretends CSS never has a role is dishonest. Three places structural selectors still earn their keep:

What none of those three justify is using a CSS chain to find and click a thing the agent could have located by role and name. The interaction primitive is the place to be strict. Everything else is a downstream choice.

Resolution: rules a team can actually adopt

1. Forbid CSS chains and XPath in the interaction layer. If a test file in your repo contains .locator("div > div > ...") for a click or a type, treat it as a lint failure.
2. Allow getByTestId as an escape hatch when the surface has no accessible name. Pair it with a code-owner rule that catches abuse.
3. When you adopt an AI testing tool, ask which layer the tool emits into your repo. If the answer is “a YAML file in our cloud”, you cannot lint the locator strategy at all because the strings are not in your repo.
4. Inspect what the agent does at runtime. If it sends string selectors over the wire, every selector is a candidate for staleness. If it works against snapshot refs, the runtime is structurally immune to that class of failure.
5. Treat the question “does the test still pass for the right reason?” as primary, and the question “is the test green?” as secondary. Structural locators fail this on every DOM tree-shake; ref-plus-getByRole survives it.

Try it on a real page

The fastest way to see the two-layer split for yourself is to run Assrt against an app you already have. The agent will print every tool call, including the ref it picked from the snapshot. The generated .spec.ts file lands in your repo with getByRole-style locators you can read line by line.

npx @m13v/assrt discover https://your-app.com

Open github.com/assrt-ai/assrt-mcp and read the agent prompt at src/core/agent.ts to verify the runtime contract before you run it.

Frequently asked questions