> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.tester.army/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tester.army/_mcp/server. # Writing Test Steps Good TesterArmy steps read like instructions you would give to a teammate sitting next to you. Write what a user is trying to do, not how an automation script should do it. The agent observes the app, clicks real UI, recovers from normal UI friction, and verifies the result. Your job is to give it a clear intent and a clean stopping point. ## The short version * Write steps in plain language. * Give each step one job. * Split actions and checks into separate steps. * Use labels users can see in the UI. * Avoid selectors, internal component names, and implementation details. * Tell the agent what must be true before the step can pass. ## Write Like You Talk Best: ```txt Open the Pricing page from the header. ``` Also good: ```txt Create a new project named "Website smoke test". ``` Avoid: ```txt Click the button with class .nav-item:nth-child(3), wait 500ms, then assert URL contains /pricing. ``` TesterArmy is not trying to replay selectors. It is trying to act like a user. User-visible labels like **Pricing**, **New Project**, **Save**, **Invite teammate**, and **Run test** are the most useful anchors. ## One Step, One Intent The agent focuses on the current step and gets only a small preview of what comes next. When a step mixes too many actions, the agent has to decide where the step ends. That creates ambiguity and wastes run time. Instead of: ```txt Log in, create a project, invite a teammate, run a test, and verify the result. ``` Use: ```txt Log in with the saved admin account. Create a new project named "Checkout QA". Invite qa@example.com to the project. Run the "Checkout smoke test" test. Verify the run result is shown as passed. ``` Each step now has a clear beginning, a clear end, and a clear pass condition. ## Split Actions From Assertions Use action steps for doing something. Use assertion steps for checking that something is true. Good split: ```txt Add the Pro plan to the cart. Verify the cart shows the Pro plan with the correct monthly price. ``` Weaker: ```txt Add the Pro plan to the cart and make sure the cart is correct. ``` The split matters because assertion steps are treated as focused verification. The agent can still navigate or scroll if needed, but it should not start changing data, uploading files, or doing unrelated setup during an assertion. ## Use The Right Step Type TesterArmy supports different step types. Pick the type that matches the job. | Type | Use it for | Good example | | ------------ | ------------------------- | ------------------------------------------------------ | | `act` | User actions | `Open the billing settings page.` | | `assert` | Verifying state | `Verify the billing page shows the current plan.` | | `login` | Authentication | `Log in with the saved admin account.` | | `files` | Uploading attached files | `Upload the sample invoice PDF.` | | `screenshot` | Capturing visual evidence | `Capture a screenshot of the completed checkout page.` | Do not hide login inside a broad action step. If the flow needs authentication, make it a `login` step. Do not ask for screenshots inside normal action or assertion steps; use a dedicated `screenshot` step. ## Add Context, Not A Script Good steps include the important business context: ```txt Create a new project named "PR preview smoke test". ``` ```txt Verify the invite list contains qa@example.com with the "Pending" status. ``` They do not need browser-level instructions unless the exact route or label matters: ```txt Go to /dashboard/projects and open the "PR preview smoke test" project. ``` Avoid micromanaging timing and mechanics: ```txt Click the create button, wait 2 seconds, reload, then inspect the third table row. ``` The agent already waits for page changes, checks fresh page state after important actions, handles transient toasts, and retries normal UI targeting problems. Tell it the goal, not every low-level click. ## Be Specific Vague checks are harder to evaluate. Weak: ```txt Verify the dashboard looks good. ``` Better: ```txt Verify the dashboard shows a Projects card, a Recent Runs card, and no visible error banner. ``` Weak: ```txt Check that checkout works. ``` Better: ```txt Verify the order confirmation page shows an order number and the customer email. ``` For copy checks, quote exact text only when exact copy matters. If the intent is looser, say so: ```txt Verify a success message appears after saving the profile. ``` ## Keep Tests Focused A good test usually covers one user flow. Many useful tests are 3-10 steps. Split a test when it crosses product areas like signup, onboarding, project creation, invites, billing, or running a QA test. Long end-to-end flows are sometimes useful, but they are slower to debug. ## Common Rewrites | Instead of | Write | | ---------------------------------------------- | -------------------------------------------------------------------------------------- | | `Click the blue button in the top right.` | `Click New Project.` | | `Use selector #email and type the test email.` | `Enter the saved test account email.` | | `Check the page.` | `Verify the page shows the empty project state.` | | `Do the full checkout flow.` | `Add the Pro plan to the cart.` | | `Make sure it worked.` | `Verify the confirmation page shows an order number.` | | `Wait for AI to finish and check the output.` | `Wait for the generated summary to finish and verify it contains three bullet points.` | ## Review Checklist Before running a test, scan the steps and ask: * Could a teammate follow this without seeing the code? * Does each step have one clear intent? * Are actions and assertions split? * Are user-visible labels included where useful? * Are credentials handled by a login step or saved project credentials? * Is the expected result specific enough to pass or fail confidently? If the answer is yes, the agent has a much better chance of producing stable, useful results.