How to test automation when the test is a paragraph of markdown

The shape every other guide teaches

Search the keyword and the top five results read like one article. They tell you to list the manual cases you already run, pick a framework (usually Selenium, occasionally Playwright or Cypress), install a runner, wire it into CI, and start writing code. Then they show a snippet in Java or Python with driver.findElement(By.id(...)) and an explicit wait. The sample test is a login form.

This pipeline works, but every step below the "pick a framework" line is a tax. You maintain selectors. You author waits. You translate what the user does into method calls. When the UI shifts slightly, the test breaks even though the behavior did not. The author loop gets long enough that tests become a separate engineering workstream from the feature work, which is the exact point where most teams decide automation is not worth it.

The thing missing from those guides is a shorter path: keep the real browser, drop the code. The rest of this page is what that path looks like in practice.

The scenario format the agent executes

The entire test language is one rule: a line that starts with #Case N: begins a new scenario. Everything under it, until the next #Case line, is the instruction set for that scenario in plain English. The parser is a regex in src/core/agent.ts of the open-source assrt-mcp repo (lines 259 and 568). There is no other grammar.

Here is a real three-case file a reader could drop into any Next.js or React app with a signup route.

What the runner actually does

When the agent calls assrt_test, it spawns a Playwright browser under the hood, loads your URL, and for each #Case it takes an accessibility-tree snapshot, then calls into a small set of internal tools (navigate, click, type, snapshot, wait, evaluate, assert, create_temp_email, wait_for_verification_code, complete_scenario). Elements are targeted by [ref=eN] ids pulled off the accessibility tree, not CSS selectors, so the tests are resilient to class-name and DOM-structure changes.

The three MCP tools your coding agent calls

Assrt is not a CLI you remember commands for; it is a Model Context Protocol server that exposes exactly three tools to whichever coding agent you already use (Claude Code, Cursor, any MCP-aware client). The three names are defined in src/mcp/server.ts of the assrt-mcp repo and they cover the whole loop.

The contract you program against

Whatever you chain onto the runner, the output is the same shape. Six top-level keys. Per-scenario children with a boolean pass, a steps array, and a summary. Every integration (CI gate, Slack bot, dashboard, PR comment) reads the same JSON.

A run, end to end, from the terminal the agent sees

Here is what the loop looks like from the agent's point of view. The agent commits a feature. A PostToolUse hook reminds it to verify. It calls assrt_test. If a case fails, the agent reads the JSON, watches the recording at 5x, calls assrt_diagnose, patches, and re-runs. The whole thing happens inside the same conversation that produced the change.

Where every file lands

The runner is deliberate about disk layout. Nothing is scattered across temp directories; everything lives under two roots so your editor, your hook scripts, and your eyes always know where to look.

How this compares to the traditional automation playbook

The row that matters most is "who writes the test." Every other difference follows from that choice.