Readable scenarios are reviewed — raw code is not
In most engineering teams, Playwright test files receive almost no meaningful code review. The reviewer sees a page of locators, async/await calls, and expect statements and either approves it quickly or skips reviewing it at all — because reading it carefully would take longer than the feature took to build.
A readable scenario changes that dynamic. A product manager can confirm that the test actually covers the right behavior. A QA lead can spot a missing edge case. An engineer who did not write the test can update it confidently because the intent is clear. Review quality improves when the artifact being reviewed is understandable.
This compounds over time. A test suite where intent is always legible is a test suite that gets properly reviewed, properly updated, and properly trusted. A test suite of opaque automation code tends to accumulate technical debt until someone deletes it and starts over.
Repo-native files create ownership and history
Test definitions that live in a tool, a dashboard, or a third-party platform are test definitions that will eventually fall out of sync with the product. They do not go through code review. They are not in the git history. Nobody knows who last changed them or why.
A Markdown scenario file in the repo gets all of that for free. When the test changes, the change goes through a pull request. When something breaks, git blame tells you when it last changed and what changed alongside it. When a new engineer joins the team, the test files are right there in the codebase where they expect them to be.
Separation of intent from execution
The core architectural benefit of a Markdown scenario is that it separates what the test is protecting from how the test runs. The 'what' — user intent — is stable and human-authored. The 'how' — the Playwright code that executes against a browser — is a generated implementation detail.
When the UI changes, you update the intent. The execution layer regenerates. You never have to manually rewrite browser automation code unless something genuinely novel is required.
This is especially valuable with AI in the loop. An AI agent writing to a Markdown scenario file is creating a reviewable, durable artifact. An AI agent writing raw Playwright code is creating something that looks useful today but will be opaque and hard to maintain next quarter.
How Assert uses Markdown in practice
Assert scenarios are plain-text files that live in the repo alongside the code they protect. They define a URL, a scenario name, a sequence of user actions, and an expected outcome. Assert's execution layer reads those files, generates the Playwright test, runs it against the live application, and returns step-level results, screenshots, and pass/fail status to the dashboard.
The scenario file does not change when Assert's internal execution logic changes. It does not change when Playwright releases a new version. It only changes when the product behavior it is protecting changes — and when it does change, that change is a readable, reviewable diff.
URL: https://app.example.com/tickets SCENARIO: Create a support ticket PROCESS: - Click "New Ticket" - Wait for "Create New Ticket" in dialog - Fill "subject" with "Example issue" - Fill "body" with "Repro steps go here" EXPECT: Create New Ticket dialog with subject and body filled
FAQ
Is Markdown just a wrapper around the same brittle selectors?
No. A well-authored Markdown scenario does not contain selectors at all. It contains user-level actions — 'Click Sign in', 'Fill email', 'Expect Dashboard' — and the execution framework resolves those to the appropriate selectors. That resolution can be updated without touching the scenario file.
Why not just keep Playwright test files in the repo directly?
You can, and many teams do. The practical problem is that raw Playwright files are hard to review across disciplines, hard to update confidently without understanding the full selector context, and hard to regenerate when the UI changes significantly. Markdown scenarios solve all three of those problems by keeping the intent separate from the execution.
What happens to the Markdown scenario in CI?
The scenario file is committed to the repo and read by the Assert CLI during the CI run. The CLI generates the Playwright test from the scenario, executes it, and reports pass/fail status and step-level detail back to the Assert dashboard. The scenario file is the source of truth; the generated test is a build artifact.
Put the workflow in your repo, not in a chat transcript
Assert is strongest when scenarios become durable project assets: readable Markdown in the repo, generated execution underneath, and result inspection in the dashboard.