> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.qa.army/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.qa.army/_mcp/server.

# Use QA.army with Coding Agents

> Author saved Tests from application requirements, run them, and inspect the evidence through the public API.

Start with the public [authentication contract](https://qa.army/auth.md),
[OpenAPI document](https://api.qa.army/v1/openapi.json), and
[test-writing skill](https://qa.army/skill.md). CLI and MCP use the same REST
operations and Workspace permissions.

For terminal use, [install the CLI](/interfaces/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:

```json
{
  "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](https://api.qa.army/v1/openapi.json) 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](/create-and-start-runs) and
[evidence guide](/results-and-evidence) 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](/interfaces/cli) and
[MCP guide](/interfaces/mcp) for supported adapter commands.