Write Reliable Test Steps

Reliable steps describe user intent, name the expected outcome, and avoid implementation details that change frequently.

Prefer intent

Write “Open Billing from Settings” instead of a CSS selector or page structure. This keeps the Test readable and resilient when the interface changes.

Choose the right primitive

An Act step performs an interaction, observes the result, and verifies its expected outcome internally. A completed click alone does not establish success. You can specify an expected outcome in the editor; otherwise QA.army infers and freezes it before execution. Ambiguous expectations produce an error before the action.

An Assert / Verify step independently evaluates an explicit expectation. Keep these for independent checks and the final journey result. Screenshot captures evidence; screenshot-only Tests remain valid, and passing means the requested captures completed. You control the steps and their order.

Act: Add the annual Pro plan to the cart.
Expected outcome: The cart contains Pro Annual.
Assert: The order summary shows Pro Annual and the expected total.

ACT uses up to three fresh observations within its verification window (30 seconds by default) and the Run deadline. It does not repeat an ambiguous action to obtain a pass. Use Timing and exact values to set an explicit window or compare a visible text, number, or boolean value.

Through REST, CLI, or MCP, an ACT step can include:

{
  "type": "act",
  "instruction": "Select Yearly billing",
  "enabled": true,
  "verification": {
    "expectation": "Yearly billing is selected",
    "timeout_ms": 30000,
    "checks": [{ "query": "Selected billing period", "equals": "Yearly" }]
  }
}

Run details show the expected and observed outcome, whether it was inferred, and its evidence. FAILED means the observation contradicts the expectation after settling; ERROR means a trustworthy result could not be established. Earlier Runs retain the interpretation of their original execution contract.

Make failures diagnosable

Assert visible text, state, navigation, or another durable product effect. Capture screenshots at important checkpoints when screenshot evidence is available.

Keep permissions explicit

Enable JavaScript, Web Search, files, credentials, microphone use, viewport, and location only when the journey requires them. Keep permissions as narrow as possible.

Generate a complete journey

When journey discovery is enabled, describe the goal in the Project’s focused generation flow—for example, “test the favorites feature in a profile.” QA.army can discover a favoriting step in one Test and profile navigation in another, add the transitions needed to connect them, and save one ordinary Test. You do not need to maintain a separate reusable-step library.

Review Journey sources and identities in the Test editor. It shows the source Test versions, inferred connections, identity queries, and prerequisites that must be resolved. Documented source steps can be reused before they have been run; their presence does not establish that the behavior works.

For the favorites example, the Test should select an eligible unfavorited game, observe the game and account identities, favorite the game with ACT verification, navigate to profile favorites, and independently Verify that the same game appears for the same account. Add Screenshot when you want a capture. Identity references such as {{binding.game}} are filled from observations during the Run, not invented during generation.

You can edit the ordinary steps and their order. Keep identity captures before their uses and maintain the final Verify checks. When editing through REST, CLI, or MCP, preserve the optional journey object; the server validates its source versions and bindings.

A missing or ambiguous identity produces ERROR; a different observed identity produces FAILED. If a source changes during preparation, generate again. If discovery is unavailable or QA.army cannot establish a complete journey, no unrelated substitute Test is saved. Past evidence can inform later generation, but every new Run requires fresh verification. Existing manually authored Tests and ACT verification work independently of journey generation.