Readable Playwright test code starts by deleting the selector line

Before every interaction, the agent calls the snapshot tool. Snapshot returns the page's accessibility tree with a [ref=eN] ID tagged on each interactive element. Your plan says "Click the Sign In button"; the agent reads the tree, finds the element whose role is button and whose accessible name is "Sign In", and passes ref=e5 (or whatever the current ID is) to the click tool. This is enforced as the first rule in the SYSTEM_PROMPT at agent.ts line 207: "ALWAYS call snapshot FIRST to get the accessibility tree with element refs." The click tool is defined at agent.ts lines 32 to 42 and accepts exactly two inputs: element (human description) and ref (a11y tree ID). No CSS, no XPath, no data-testid string lives in your plan.

Two things. First, getByRole is still source code you write, version, and maintain. page.getByRole('button', { name: /sign in/i }) is a locator expression that lives in your .spec.ts and breaks when someone renames the button. In Assrt the English step "Click the Sign In button" has no expression attached to it. Second, the resolution to ref is live. A getByRole call is evaluated the instant Playwright asks for it; if the element shifts mid-flow (modal opens, DOM re-renders), the cached handle goes stale. Assrt's agent re-snapshots on failure and finds the fresh ref (agent.ts SYSTEM_PROMPT lines 220-226). The developer never owns a selector, so they never have to fix one.

They are defined in /Users/matthewdi/assrt-mcp/src/core/agent.ts lines 16 to 196 as the TOOLS constant. The eighteen: navigate, snapshot, click, type_text, select_option, scroll, press_key, wait, screenshot, evaluate, create_temp_email, wait_for_verification_code, check_email_inbox, assert, complete_scenario, suggest_improvement, http_request, wait_for_stable. Interaction tools (click, type_text, select_option) take an element string plus a ref; data tools (navigate, http_request) take URLs; observational tools (snapshot, screenshot, wait_for_stable) take no arguments. The only tool that can run arbitrary code is evaluate, and its input is a JavaScript expression, not a locator. There is no parameter anywhere in the schema that expects a CSS selector. It is structurally impossible to write one.

Official, pinned. Look at /Users/matthewdi/assrt/src/core/freestyle.ts line 586: the base image setup string literally runs npm install -g @playwright/mcp@0.0.70 ws @agentclientprotocol/claude-agent-acp@0.25.0. That is the @playwright/mcp package from the Microsoft Playwright organization on npm, version 0.0.70, frozen. The Assrt agent then speaks MCP to that binary; every click ends up as Playwright's own click inside a real Chromium process. No fork, no custom wrapper, no in-house automation library. If Playwright ships a fix, you bump the pin.

Three things a Page Object cannot give you. One: zero locator maintenance. Even a good Page Object has a private locator map at the top of the file, which is still code that drifts when the UI changes. Assrt's plan has no locator layer at all. Two: reviewable by non-engineers. A PM can read "Click the Sign In button, assert the URL becomes /app" and sign off; they cannot meaningfully review loginButton.click() because the click is named, not described. Three: no imports, no fixtures, no beforeEach boilerplate. The plan is only the behavior. For a team with 5 critical flows the signal-to-noise ratio of scenario.md versus tests/login.spec.ts with a page object, fixture, and helper is roughly 4 to 1 by line count. I measured our own signup flow: 8 lines in scenario.md, 34 lines in the equivalent .spec.ts once you include the Page Object and fixtures.

Run grep over a saved plan and the matching execution log. scenario.md is at /tmp/assrt/scenario.md; the log is at /tmp/assrt/<runId>/execution.log. Try grep -E '\.|#|\[|>|="|xpath' /tmp/assrt/scenario.md — should return empty (English does not use those characters the way a selector does). Then grep ref /tmp/assrt/<runId>/execution.log — every click/type line has a ref=eN argument. The plan says what, the log shows which ref the agent picked. You can see the full log event shape in the emit() callback at /Users/matthewdi/assrt-mcp/src/mcp/server.ts line 443.

Use the evaluate tool. It accepts an arbitrary JavaScript expression and returns the result, so if you need to assert that .cart-total has textContent === "$42.99" at a pixel-specific level, you write that JavaScript inline in the plan: "Call evaluate with the expression document.querySelector('.cart-total').textContent and assert the result is $42.99." It is the one escape hatch. Most tests do not need it; the 90 percent case (did the button click, did the page change, did the message appear) is handled by role + name lookups. The evaluate schema is at agent.ts lines 105 to 112.

Plain markdown with #Case headers. The format is enforced by the regex in the ingest path: /(?:#?\s*(?:Scenario|Test|Case))\s*\d*[:.]\s*/gi. A minimum viable plan is two lines: #Case 1: Homepage loads / Navigate to the URL and verify the page title contains the product name. A real signup plan is 8 to 12 lines. You save it at /tmp/assrt/scenario.md (hard-coded in scenario-files.ts lines 16-20) or pass --plan-file any/path.md to the CLI. fs.watch monitors scenario.md; any save triggers a 1000ms debounce then pushes to the cloud so a teammate can rerun the same plan from their machine.

Free and MIT-licensed. Install with npx @assrt-ai/assrt setup. The commercial tools in this bracket (major AI-driven QA SaaS platforms charging $5K to $10K per month per team) bundle three things you do not need: a hosted recorder that emits proprietary YAML, a cloud runner that gates your tests behind a dashboard, and a selector-healing product that tries to repair the brittle locators you never had to write in the first place. Assrt removes the premise. The recorder is optional, your runner is your laptop or your CI, and the selector-healing product is irrelevant because there are no selectors.

Yes, they compose. Run your existing npx playwright test in CI for the deep low-level assertions (network payloads, trace viewer diffs, pixel regression). Run npx assrt run --plan-file tests/smoke.md for the readable smoke layer that covers the three or four flows you genuinely care about shipping. The two do not share state; they do not conflict. Teams I have watched adopt Assrt usually delete about 40 percent of their existing .spec.ts files within a quarter because those files were covering exactly the flows that the plan covers more cheaply and more readably. The other 60 percent stays as .spec.ts.