# uip tm wait

> Syntax and options for `uip tm wait`, which polls a test execution until it reaches a terminal state and prints a one-line summary.

`uip tm wait` polls a test execution until it reaches a terminal state (`Passed`, `Failed`, `Cancelled`, etc.) and then prints a one-line summary. It turns the asynchronous `uip tm testsets run` into a blocking step in a CI pipeline.

`wait` is registered as a top-level verb under `tm`, not as a resource — invoke it as `uip tm wait`, not `uip tm executions wait`.

## Synopsis

```text
uip tm wait --execution-id <uuid> (--project-key <key> | --test-set-key <key>)
            [--timeout <ms>] [--poll-interval <ms>]
```

Honors the [global options](./global-options.md). See the Exit codes section below for the domain-specific behavior on timeout.

## uip tm wait

Block until the given execution reaches a terminal state, polling Test Manager at a configurable interval.

### Arguments

None.

### Options

- `--execution-id <uuid>` *(required)* — execution to wait on. Get it from `uip tm testsets run`.
- `--project-key <key>` — owning project. Either this or `--test-set-key` is required.
- `--test-set-key <key>` — test set key (for example, `DEMO:42`); the project key is derived from the prefix.
- `--timeout <ms>` — maximum time to wait, **in milliseconds**. Defaults to `1800000` (30 minutes). Pass `0` to wait indefinitely.
- `--poll-interval <ms>` — how often to poll the execution status, **in milliseconds**. Defaults to `60000` (60 seconds).
- `-t, --tenant <name>` — override the active session's tenant for this call.
- `--log-level <level>` — `debug`, `info`, `warn`, `error`. Defaults to `Information`.

### Example

```bash
# wait up to 15 minutes, polling every 30 seconds
uip tm wait \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO \
  --timeout 900000 \
  --poll-interval 30000
```

### Data shape — execution reached terminal state before timeout

```json
{
  "Code": "WaitComplete",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Passed",
    "EndTime": "2025-04-15T10:32:11Z",
    "Duration": "00:02:11"
  }
}
```

`Status` can be any terminal state Test Manager reports (including `Passed`, `Failed`, `Cancelled`). "Reached a terminal state" is the success signal for `wait` — the verb exits `0` regardless of whether tests inside the execution passed or failed. To branch on pass/fail, read the [`report get`](./uip-test-manager-report.md) output after `wait` returns.

## Exit codes

`wait` follows the standard [exit codes](./exit-codes.md) for `0`, `1`, and `3`, with one domain-specific reuse of `2`:

| Exit code | Meaning |
|---|---|
| `0` | Execution reached a terminal state within the timeout. |
| `1` | Polling failed (repeated API errors, interrupt, abort) — see the `Message` field for detail. |
| **`2`** | **Timed out.** The timeout elapsed before the execution reached a terminal state. |
| `3` | Validation error (bad flag value, missing required option). |

Exit code `2` is domain-specific. The shared CLI contract reserves `2` for `AuthenticationError`, but `wait` reuses it for timeout so that scripts can distinguish "took too long" from "polling genuinely failed" without parsing text. See [Exit-code behavior on `executions`](./uip-test-manager-executions.md#exit-codes) for the full pattern.

### Script pattern

```bash
if ! uip tm wait \
    --execution-id "$id" \
    --project-key DEMO \
    --timeout 1800000 \
    --poll-interval 30000; then
  case $? in
    2) echo "timed out" >&2; exit 2 ;;
    *) echo "wait failed" >&2; exit 1 ;;
  esac
fi
```

## Related

- [testsets run](./uip-test-manager-testsets.md#uip-tm-testsets-run) — produces the `ExecutionId` to wait on.
- [report](./uip-test-manager-report.md) — summary to read once `wait` returns `0`.
- [result](./uip-test-manager-result.md) — JUnit XML export.
- [executions retry](./uip-test-manager-executions.md#uip-tm-executions-retry) — re-run the failed cases of a finished execution.

## See also

- [Test Manager overview](./uip-test-manager.md)
- [Exit codes](./exit-codes.md) — shared contract.
- [Scripting patterns](./scripting-patterns.md) — the launch-wait-verify pipeline.