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:

Open the Pricing page from the header.

Also good:

Create a new project named "Website smoke test".

Avoid:

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:

Log in, create a project, invite a teammate, run a test, and verify the result.

Use:

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:

Add the Pro plan to the cart.
Verify the cart shows the Pro plan with the correct monthly price.

Weaker:

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.

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:

Create a new project named "PR preview smoke test".

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:

Go to /dashboard/projects and open the "PR preview smoke test" project.

Avoid micromanaging timing and mechanics:

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:

Verify the dashboard looks good.

Better:

Verify the dashboard shows a Projects card, a Recent Runs card, and no visible error banner.

Weak:

Check that checkout works.

Better:

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:

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

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.