# uip tm executions

> `uip tm executions` inspects and manipulates test executions — the objects produced by [`uip tm testsets run`](./uip-test-manager-testsets.md#uip-tm-testsets-run). Use these verbs to list executions for a test set, enumerate the test case logs of a finished run, and retry only the failed cases in place.

`uip tm executions` inspects and manipulates test executions — the objects produced by [`uip tm testsets run`](./uip-test-manager-testsets.md#uip-tm-testsets-run). Use these verbs to list executions for a test set, enumerate the test case logs of a finished run, and retry only the failed cases in place.

The command that *starts* an execution is `uip tm testsets run`, which returns an `ExecutionId`. Every verb on this page takes that ID (or derives it from context).

## Synopsis

```
uip tm executions list --project-key <key> --test-set-id <uuid> [filters…]
uip tm executions testcaselogs list --execution-id <uuid> --project-key <key> [filters…]
uip tm executions retry --execution-id <uuid> (--project-key <key> | --test-set-key <key>) [--execution-type <type>]
```

All verbs honor the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). Every verb accepts `-t, --tenant <name>` and `--log-level <level>` (default `Information`).

## uip tm executions list

List the executions associated with a test set. Filters are applied server-side; the CLI returns one page per call, sized by `--top` / `--skip`.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--test-set-id <uuid>` *(required)* — test set UUID (the `Id` field from `testsets list`, **not** `TestSetKey`).
- `--filter <text>` — search executions by name.
- `--status <status>` — filter by execution status. Accepted values come from the SDK `TestExecutionStatus` enum.
- `--execution-type <type>` — filter by execution type. Accepted values come from the SDK `ExecutionType` enum (`automated`, `manual`, `mixed`, `none`).
- `--execution-finished-interval <interval>` — filter by how recently the execution finished. Accepted values come from the SDK `TestExecutionFinishedInterval` enum.
- `--top <number>` — page size. Defaults to `50`.
- `--skip <number>` — results to skip. Defaults to `0`.

:::note
The exact enum values accepted by `--status`, `--execution-type`, and `--execution-finished-interval` are generated from the Test Manager SDK at runtime. Run `uip tm executions list --help` to see the current set for your installed tool version.
:::

### Example

```bash
uip tm executions list \
  --project-key DEMO \
  --test-set-id a1b2c3d4-0000-0000-0000-000000000001 \
  --top 2
```

### Data shape

```json
{
  "Code": "ExecutionsList",
  "Data": [
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000001",
      "Name": "Nightly Run 2025-04-15",
      "Status": "Passed"
    },
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000002",
      "Name": "Nightly Run 2025-04-14",
      "Status": "Failed"
    }
  ]
}
```

## uip tm executions testcaselogs list

List the test case logs produced by a single execution. Each log is one run of one test case, carrying result, status, and timing.

### Arguments

None.

### Options

- `--execution-id <uuid>` *(required)* — execution to inspect.
- `--project-key <key>` *(required)* — owning project.
- `--only-failed` — shortcut for "show only failed logs".
- `--filter <text>` — search logs by name.
- `--results <results...>` — space-separated results to include. Accepted values come from the SDK `Result` enum.
- `--statuses <statuses...>` — space-separated execution statuses. Accepted values come from the SDK `TestCaseLogExecutionStatus` enum.
- `--duration-period <period>` — filter by duration bucket. Accepted values come from the SDK `DurationPeriod` enum.
- `--top <number>` — page size. Defaults to `50`.
- `--skip <number>` — results to skip. Defaults to `0`.

### Example

```bash
uip tm executions testcaselogs list \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO \
  --only-failed
```

### Data shape

```json
{
  "Code": "ExecutionTestCaseLogs",
  "Data": [
    {
      "Id": "c3d4e5f6-0000-0000-0000-000000000001",
      "TestCaseName": "Login flow",
      "Status": "Finished",
      "Result": "Failed"
    }
  ]
}
```

Each `Id` in the output is a test case log UUID. Feed it to [`uip tm testcaselogs list-assertions`](./uip-test-manager-testcases.md#uip-tm-testcaselogs-list-assertions) to see why a test case log was marked `Failed`.

## uip tm executions retry

Retry only the failed test cases of a completed execution, **in place**. The command:

1. Fetches the execution's stats and refuses to proceed unless the run is in a terminal state (otherwise it exits `1` with a guidance message).
2. If there are zero failed cases, prints a `Message` envelope and exits `0` — this is intentionally not an error.
3. Otherwise collects every failed test case log ID (paged) and kicks off a retry that targets only those logs.

The retry reuses the same execution ID; it does not create a new one.

### Arguments

None.

### Options

- `--execution-id <uuid>` *(required)* — execution to retry.
- `--project-key <key>` — owning project. Either this or `--test-set-key` is required.
- `--test-set-key <key>` — test set key (e.g. `DEMO:42`); the project key is derived from the prefix.
- `--execution-type <type>` — execution type for the retry: `automated` *(default)*, `manual`, `mixed`, or `none`.

### Example

```bash
uip tm executions retry \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO
```

**Data shape** — when there are failures to retry:

```json
{
  "Code": "ExecutionRetry",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Running",
    "StartTime": "2025-04-15T10:30:00Z",
    "RetriedCount": 3
  }
}
```

When there are no failures to retry:

```json
{
  "Code": "ExecutionRetry",
  "Data": {
    "Message": "Execution 'a1b2c3d4-0000-0000-0000-000000000001' has no failed test cases to retry."
  }
}
```

## Exit codes

All `uip tm executions …` verbs follow the standard [exit codes](./exit-codes.md) — `0` on success (even when `retry` finds nothing to retry), `1` on generic failure, `2` on authentication failure, `3` on validation error.

The Test Manager run lifecycle adds one behavior worth calling out explicitly, and it lives on `wait`, not on the execution verbs themselves:

### Distinguishing "timed out" from "finished with failures"

There is no single `tm` verb that exits non-zero *because* tests failed. The standard CI pattern is a three-step pipeline:

1. **Launch** — `uip tm testsets run` returns an `ExecutionId` and exits `0` as soon as the run is queued.
2. **Block** — `uip tm wait --execution-id <id> --timeout <seconds>` polls until the execution reaches a terminal state.
   - Exits `0` when the execution finished (regardless of pass/fail — "finished" is the success signal here).
   - Exits **`2`** on `--timeout` expiry. This is domain-specific: the shared contract reserves `2` for `AuthenticationError`, but `wait` reuses it for `TimeoutError` so scripts can branch on "took too long" without parsing text. See the note on this under [`uip tm wait` exit codes](./uip-test-manager-wait.md#exit-codes).
   - Exits `1` on API failure, interrupt, or abort.
3. **Verdict** — `uip tm report get --execution-id <id>` reads `Passed` / `Failed` / `Skipped` / `PassRate`. Your script decides what a pass looks like and fails the build explicitly (e.g. `exit 1` when `Failed > 0`). `report get` itself exits `0` whenever it successfully produces the summary, regardless of the outcome of the run it is summarizing.

```bash
# Start the run
id=$(uip tm testsets run --test-set-key DEMO:10 --output-filter .Data.ExecutionId)

# Block with a timeout; branch on the outcome
if ! uip tm wait --execution-id "$id" --timeout 1800; then
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "timed out" >&2
    exit 2
  fi
  echo "wait failed ($code)" >&2
  exit "$code"
fi

# Decide pass/fail from the summary
failed=$(uip tm report get --execution-id "$id" --project-key DEMO --output-filter .Data.Failed)
if [ "$failed" -gt 0 ]; then
  echo "$failed test case(s) failed" >&2
  exit 1
fi
echo "all passed"
```

## Related

- [testsets run](./uip-test-manager-testsets.md#uip-tm-testsets-run) — start an execution.
- [wait](./uip-test-manager-wait.md) — block until an execution reaches a terminal state.
- [report](./uip-test-manager-report.md), [result](./uip-test-manager-result.md), [attachment](./uip-test-manager-attachment.md) — post-run artifacts.
- [testcases](./uip-test-manager-testcases.md#uip-tm-testcaselogs-list-assertions) — `testcaselogs list-assertions` turns a failed log into per-assertion detail.

## See also

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