Most Browser QA Workflows Fail at the Authoring Layer
Teams usually frame browser QA as an execution problem: pick a tool, write selectors, run the suite. In practice, the authoring model is what breaks first. The people who understand the release surface best — product, QA, support, founders, and sometimes even customers — do not want to maintain selector-heavy code. They want to describe behavior in plain language.
That is why markdown is such a strong interface for browser QA agents. It keeps the test legible, reviewable, and portable while still giving the runtime enough structure to turn steps and expectations into executable tasks.
What a Markdown-Native QA System Buys You
In our QA Agent work, each spec can encode:
- Title — a human-readable description of the scenario
- Persona — unauthenticated, free user, pro user, or any saved auth state
- Priority — useful for sorting sweeps under time pressure
- Tags — smoke, regression, release category, device profile, and more
- Steps — explicit ordered actions the agent must follow
- Expected outcomes — the contract the run is graded against
That structure is powerful because it is still plain text. It can be reviewed in PRs, synced from a release CSV, generated from another system, or edited by someone who never wants to touch a test runner.
The Operational Proof
As of April 16, 2026, the same markdown-driven pattern was being used in two different product codebases:
- TheBlueOne — 338 markdown specs across 9 suite folders, with 178 archived report directories
- InterviewLM — 142 markdown specs across 17 suite folders, with 111 archived result directories
Combined, that is 480 specs and 289 archived runs. That scale matters because it shows markdown is not just a cute authoring trick for three smoke tests. It holds up when the surface area expands into auth, onboarding, voice flows, dashboards, pricing, PMF pages, UAT, and release sweeps.
2026-04-16T21-27-46, which passed 4 of 4 checks across the marketing site.
2026-04-16T21-31-57.Why This Ages Better Than Brittle Scripts
Selector-heavy test code couples the test to the implementation details of the UI. Markdown specs couple the test to the behavior the team actually cares about. That does not eliminate maintenance, but it shifts maintenance toward intent instead of mechanics.
When the UI changes, you often only need to update the instructions or expected outcomes. The browser agent can adapt to new layouts in a way a brittle selector chain cannot.
Artifact Capture Is the Other Half of the Pattern
Readable specs alone are not enough. The system also needs to generate evidence that engineers can work with. Our pattern couples markdown execution with:
- Screenshots at major steps
- GIFs and videos for replay
- Conversation traces from the agent
- HTML summaries and machine-readable JSON
- Optional issue creation in Linear and Sentry correlation
This is the difference between “the suite failed” and “here is the exact state the agent saw, what it concluded, and what broke.”
Where Markdown Fits Best
Markdown-native QA is strongest when your team has a lot of UI change, mixed ownership, and release checklists that already exist outside code. It is especially useful for products where the hardest failures are experiential — broken flows, redirects, missing content, loading states, and regressions that a human would catch quickly.
If your system demands pixel-perfect selector assertions on a frozen UI, code-first tests may still be the right tool. But for fast-moving product QA, markdown is often the missing interface that makes browser agents operationally viable.
The agent we use for this is open source: github.com/frenxt/qa-agent.