Nine e2e testing best practices, one root cause, and the rule every SERP misses.

The universal rule is 'use stable selectors, preferably data-testid.' It is not wrong in a classical suite, but it is treating a symptom. The disease is that a selector is persisted in your test file at all: once persisted, any app change can break it and now you own the drift. Assrt's system prompt at assrt-mcp/src/core/agent.ts:213 tells the agent to call the snapshot tool before every interaction, read ref IDs like ref="e5" from the accessibility tree at that moment, and then use those refs to click. No data-testid is needed in the app and no selector is written into the plan file. When the UI refactors, the accessibility tree still exposes a button with role=button and name="Get started", and the same plan still clicks it. Stable selectors solve drift by picking better-typed drift; runtime-resolved refs eliminate the drift surface.

Hard-coded waits are forbidden for the same reason hard-coded selectors are: you pick one number and live with it. Even the 'explicit wait' substitute (waitForSelector with a timeout) still requires you to pick a timeout. wait_for_stable in Assrt (see agent.ts tool definition lines 186-194) injects a MutationObserver into the page, counts DOM mutations, and returns as soon as there have been zero mutations for stable_seconds (default 2, max 10) or the outer timeout_seconds (default 30, max 60). The agent calls it after any action that kicks off async work. Pages that finish in 200ms return in 200ms; pages that finish in 4 seconds block for 4 seconds. You never pick a number.

Nowhere. The reason POM exists is that locators are written in multiple test files and you want one place to change them when the UI changes. If no locators are written anywhere, there is nothing to share. Instead, steps are English sentences in scenario.md; if three #Cases all 'open the cart', that English repetition is fine because the agent re-resolves the ref from the live DOM on each run. When an app refactors the cart icon, the classical POM needs an update; the Markdown plan does not.

Eighteen, defined in assrt-mcp/src/core/agent.ts starting at line 16: 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. That closed set caps what any test can do. For best-practice reasoning this matters: classical suites cover 'isolate your tests', 'avoid hard-coded waits', 'fix flakes' as rules in docs, but the tools the test has access to are unbounded. Here they are bounded, so the rules are enforceable by inspection.

Each #Case block is independent of the others within a file, and each file is independent of other files. So parallel execution is run as many processes of npx assrt run as you have CPUs, each with its own plan. Because the runner is self-hosted and open source (no SaaS connection required), there is no account-level worker cap. Browsers are per-process, so there is no cross-test state leakage unless you opt into shared auth with --no-isolated. The one tradeoff: agent-picked tool calls add a model-inference round trip per step, so a compiled Playwright spec is faster per run. In most product test suites the model latency is dominated by page latency anyway.

In a classical suite, most 'best practices' are flakiness-shaped: explicit waits, stable selectors, isolated fixtures, retry on failure. Each one fixes a specific flake mode. But the rules do not stack cleanly; an app that adds a new async animation breaks a test that used waitForLoadState('networkidle'), and now you need a new rule. Runtime-resolved refs and MutationObserver stability cover most of those flake modes at once, because the primitives themselves adapt to the page. The remaining flake surface is genuine: flakes from actual race conditions in the app, which you want to see because they are real bugs.

Yes. Assrt runs on real Playwright via Playwright MCP over stdio (see assrt-mcp/src/core/browser.ts for the launch path). Your existing spec files keep running the way they always did. The suggested adoption path is: keep stable legacy specs as-is, write new user flows as Markdown #Cases, and let the two coexist in the same repo. You can also graduate a high-value #Case into a deterministic spec when you need repeatable per-millisecond behavior. The only thing that changes is the default unit of work above the Playwright runtime: English instead of TypeScript.

Standard guidance is 5-10% of your test suite should be e2e, focused on revenue-impacting journeys: signup, checkout, upgrade, core CRUD. That guidance still applies. What changes under Assrt is the cost per journey: instead of 150 lines of TypeScript plus fixtures, a journey is 5 lines of Markdown. The 5-10% budget becomes a line-count budget not a maintenance budget, so teams can cover more journeys without the traditional ceiling. The things that stay in unit tests: pure functions, reducer logic, date math, parsing, anything where there is no browser surface to observe.

Three files on the local filesystem. /tmp/assrt/scenario.md is the plan, watched for edits and auto-synced to cloud storage after a 1-second debounce (see scenario-files.ts lines 96-103). /tmp/assrt/results/latest.json holds the TestReport with scenarios, passedCount, failedCount, per-assertion evidence, and per-step timings. /tmp/assrt/results/<runId>.json is the immutable per-run copy. If --video is passed, a WebM plus a player.html with 1x through 10x playback speed live next to the run. Nothing leaves your machine unless you opt into cloud sync. CI integrations typically read --json stdout and skip the files.