Use QA.army with Coding Agents

Start with the public authentication contract, OpenAPI document, and test-writing skill. CLI and MCP use the same REST operations and Workspace permissions.

For terminal use, install the CLI, complete qa-army auth agent-register --email you@example.com, then discover the intended Workspace, Project, and saved Tests. qa-army capabilities --json describes installed commands; it does not grant permission to use them. Ask the user to choose a target when several Projects match rather than guessing.

Author a Test directly

Your coding agent can use application requirements and code to write ordered steps. POST /v1/projects/{projectId}/tests saves those steps directly; it does not depend on backend AI generation and does not start a Run.

Send an authorized bearer and an Idempotency-Key, with a JSON body such as:

{
  "name": "Open signup",
  "enabled": true,
  "allow_web_search": false,
  "deep_thinking": false,
  "steps": [
    {
      "type": "act",
      "instruction": "Open the Project homepage",
      "enabled": true,
      "verification": {
        "expectation": "The homepage is visible",
        "timeout_ms": 30000
      }
    },
    {
      "type": "assert",
      "instruction": "Verify the Get started link is visible",
      "enabled": true
    }
  ]
}

Boolean settings and each step’s enabled flag are required. Nullable settings such as description, group, viewport, location, and device can be omitted. Steps execute in array order. ACT verification describes the expected outcome of an action; explicit assert steps define independently checked conditions. Keep instructions specific to visible controls and observable behavior.

A Test can contain 1–50 steps and at most one enabled login step. An enabled login step needs a same-Project account_id; never embed a password or token in an instruction. Account metadata lookup requires a signed-in QA.army user session. Your claimed agent identity can update saved Tests and manage Test Groups within its Workspace access; no second API key is needed. It cannot read Test Account metadata or credentials, access Live View, or perform account administration. QA.army authorization does not establish a signed-in session in the application being tested.

Run and inspect

Saving returns test.id and test.version. When the user authorizes execution:

1. Call POST /v1/runs with the saved Test ID in the request body defined by the OpenAPI document and a new Idempotency-Key. This creates a READY Run without starting execution.
2. Call POST /v1/runs/{runId}/start with an Idempotency-Key.
3. Poll GET /v1/runs/{runId} or read its normalized /events feed with the returned cursor until terminal status. Bound polling and preserve the receipt if the client times out; a timeout does not establish server failure.
4. Read GET /v1/runs/{runId}/evidence for finalized evidence and use the authorized evidence-opening operation. Return the Run URL and actual verdict.

PASSED is verified success, FAILED is a failed product assertion, ERROR means a trustworthy result could not be established, and CANCELLED means the Run stopped before completion. A saved Test is not proof of success. Read the Run guide and evidence guide for result details.

Correct a definition safely

Using the same claimed agent identity, fetch the Test and send its complete editable definition to PUT /v1/tests/{testId}. Set If-Match to its current positive integer version, for example If-Match: 3. Omit returned IDs, timestamps, positions, and other response-only fields from the request.

Updates replace ordered steps and settings; omitted nullable settings become null. Existing journey metadata is retained when omitted, while journey: null explicitly removes it after binding references are removed. On a version conflict, reload and reconcile changes before retrying; do not overwrite another editor’s changes. A new Run is required to verify the updated Test.

Organize related journeys through the Project’s /v1/projects/{projectId}/test-groups endpoint: GET lists Groups and POST creates one. Use GET and PATCH on /v1/test-groups/{groupId} to read and update a Group. Read its current version before updating it. Set the Test’s group_id in its complete update payload to move it. Keep enabled: false while credentials or other prerequisites are missing; do not remove assertions to make a blocked journey appear to pass.

For HTTP 400, inspect the validation_error code and explanatory title, correct the payload, and retry. Errors currently do not contain a field-errors array. For an ambiguous create response, reuse the original idempotency key and payload; changing the payload under the same key returns 409. Never silently start a second Run after a timeout.

CLI Test and Run commands generate their own request keys. Repeating qa-army tests run or qa-army setup creates a new Run; it does not resume the previous one. Use runs get, runs wait, or Test Run history to recover. The same claimed agent identity can cancel an authorized Run through POST /v1/runs/{runId}/cancel. Read its state again to confirm cancellation.

Return a useful handoff

Report the saved Test ID and version, Run ID and URL, target, actual terminal status, and the assertion or error that needs attention. Link to the authorized Run page and describe the evidence available there. Keep credentials and temporary evidence URLs out of shared messages.

If execution was not requested, report that the Test was saved and remains unverified. If a request is still active or its outcome is unknown, say so. Creating a Test, accepting a Run, and passing its assertions are distinct outcomes.

Keep credentials out of prompts and logs, use only authorized Project targets, and preserve server result meanings. See the CLI guide and MCP guide for supported adapter commands.