How to Write Test Cases in Plain English

When tests were code, "writing test cases" meant two artifacts: a human-readable case in a spreadsheet, and the automation someone later wrote from it, which promptly drifted apart. Agent-based testing collapses the two: the plain-English description is the executable test. That makes the writing itself a skill worth twenty minutes of theory, because a well-written flow runs reliably and reads like documentation, while a sloppy one produces the same ambiguity a confused new hire would face. These principles come from watching thousands of flows run through TesterArmy's agent; the product-specific reference lives in our writing-test-steps docs.

Describe what a user does, in what order, and what success looks like

A complete flow has three parts: a starting point, actions in sequence, and an observable outcome. The most common failure is omitting the third: "sign up and complete onboarding" tells the agent what to do and never says what should be true afterward. Compare:

Weak: "Test the signup flow."

Strong: "Go to the signup page, create an account with a new email, complete the onboarding steps, and verify the dashboard shows the welcome message with the account's name."

The strong version is not longer for ceremony; every added clause is something the agent can act on or check. If a colleague could perform the flow from your description alone and know whether it worked, the agent can too.

Name things the way the screen names them

The agent looks at the rendered page, so refer to what is visible: "click Upgrade to Pro" beats "click the CTA", and "open Settings from the avatar menu" beats "navigate to the settings module". You never need selectors or internal component names, and using them makes flows worse, since the agent resolves your words against what a user would see. When two elements share a label, disambiguate the way you would for a person: "the Delete button inside the billing section".

One flow, one journey

Resist the mega-flow that signs up, configures a workspace, invites a teammate, upgrades, and cancels, in one run. When it fails at step 19, you learn little, and every earlier step is a dependency risk for the later assertions. Split by user intent: "invite a teammate and verify they appear as pending" is one journey with one verdict. Short flows also parallelize, which keeps runs fast, and they map cleanly to the groups you will schedule differently anyway (smoke versus regression is exactly this split).

Write outcomes as observations, and calibrate their strictness

Assertions in plain English are things a user could verify by looking: "the order confirmation shows the correct total", "an email with a reset link arrives in the inbox", "the item no longer appears in the list". Two calibration rules keep them honest. Be strict about meaning ("the total is $29") where the value matters, and tolerant about presentation ("a success message appears") where design changes often; over-specifying decor is how flows generate noise on every copy tweak. And prefer positive observations to absences where possible, since "the error banner does not appear" passes for many wrong reasons.

Handle variability by stating the rule

Real apps have A/B tests, cookie banners, and rotating promos. Tell the flow how to behave, once: "dismiss the cookie banner if it appears", "if a promo modal opens, close it before continuing". Stating conditionals like this is what keeps unattended runs (especially nightly ones) quiet without weakening the real assertions.

Where the data comes from

Flows that create things should bring their own materials or use managed ones. "Sign up with a new email" works unattended in TesterArmy because the agent has managed inboxes; it can register with a fresh address and retrieve the verification code itself, and the same applies to SMS. For flows that need existing state ("log in as an admin"), name the role and keep the credentials in the project's auth settings rather than in the flow text.

A worked example

Weak: "Test checkout."

Strong: "Starting logged out on the home page, search for 'desk lamp', open the first result, add it to the cart, and check out as a guest with the test card. Verify the confirmation page shows one item, the correct price, and an order number, and that a confirmation email arrives."

That flow is executable by an agent, reviewable by a PM, and stable across redesigns, because everything in it is stated at the level of user meaning. Which is the deeper point of the plain-English model: your tests end up written in the language your team already uses to discuss the product, and the gap between "what we said it should do" and "what we test" closes to zero. Why that model holds up as the product changes is the story of agentic testing more broadly.

FAQ

Is plain-English testing the same as BDD/Gherkin? Gherkin is structured syntax (Given/When/Then) that engineers then implement in code; the English is a label for the automation. In agent-based testing the English is the automation, with no implementation layer to write or drift.

How precise do I need to be? As precise as you would be with a capable colleague: name what is visible, state the outcome, disambiguate where two things look alike. The agent asks for nothing more exotic.

Can non-engineers write these? Yes, and that is much of the point. The people who know what must work (PMs, support, founders) can put those flows under test directly.