# uip tm run

> Syntax and options for `uip tm run`, which runs every test in a package already uploaded to Orchestrator, waits for the results, writes a report, and exits non-zero when a test fails.

`uip tm run` runs tests in Test Manager, waits for the results, and writes a report in one command built for CI. With `--type package`, it runs every test in a package already uploaded to Orchestrator. The exit code carries the verdict, so a pipeline step needs no extra parsing.

The command waits up to 5 minutes for Test Manager to index the uploaded package, then runs its tests through a hidden test set. Test Manager creates and links a test case for any test in the package that does not have one yet. Failed test cases are re-run up to `--max-retries` times within the same execution, so the report holds the last result of every test case.

## Synopsis

```text
uip tm run --type package (--project-key <key> | --project-id <id>) --package-name <name> --package-version <version> (--folder-path <path> | --folder-key <uuid>) [--input-path <file>] [--max-retries <count>] [--format <format>] [--result-path <path>] [--include-passed-assertions] [--timeout <seconds>] [--poll-interval <seconds>]
```

Honors the [global options](./global-options.md). See [Exit codes](#exit-codes) for the codes this command uses.

## uip tm run

Run every test in an uploaded package, wait for the execution to finish, and write a JUnit XML or UiPath JSON report.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--type <type>` | **Required.** What to run. Only `package` (a package already uploaded to Orchestrator) is accepted. |
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--package-name <name>` | **Required.** Package ID as uploaded to Orchestrator (for example, `MyTests`). |
| `--package-version <version>` | **Required.** An app version (for example, `1.0`) runs its latest uploaded patch. An exact version (for example, `1.0.244878764`) must already be uploaded and must be the latest patch of its app version; older patches are refused. The command waits up to 5 minutes for Test Manager to index a version Orchestrator already has. |
| `--folder-path <path>` | Orchestrator folder to run the tests in (for example, `Shared` or `Shared/CI`). Exactly one of `--folder-path` or `--folder-key` is required. |
| `--folder-key <uuid>` | Orchestrator folder key, instead of `--folder-path`. |
| `--input-path <file>` | JSON file with parameter overrides, for example `[{"name":"Param","type":"String","value":"v"}]`. The file is read before anything is created. Names that no test declares are not applied; the output lists them under `IgnoredInputs`. |
| `--max-retries <count>` | Re-run failed test cases up to this many times, from `0` to `100`. Defaults to `0`. |
| `--format <format>` | Report format: `junit` (XML) or `uipath` (JSON). Defaults to `junit`. |
| `--result-path <path>` | Report file or directory. Defaults to the current working directory. A directory, or a new path with no extension, gets a file named after the run's test set. |
| `--include-passed-assertions` | Also read the assertions of passed tests for the report, one more request per passed test. By default only tests that did not pass get their assertions. |
| `--timeout <seconds>` | Maximum seconds for the whole run, retries included; `0` means no timeout. Defaults to `7200`, at most `604800` (one week). |
| `--poll-interval <seconds>` | Seconds between execution status checks, from `1` to `3600`. Defaults to `60`. |

### Examples

```bash
# run every test in MyTests 1.0.3 and write a JUnit report
uip tm run \
  --type package \
  --project-key DEMO \
  --package-name MyTests \
  --package-version 1.0.3 \
  --folder-path Shared \
  --result-path ./results/junit.xml

# run the latest 1.0.x patch with input overrides, retry failed tests twice, write the UiPath JSON report
uip tm run \
  --type package \
  --project-key DEMO \
  --package-name MyTests \
  --package-version 1.0 \
  --folder-path Shared \
  --input-path ./inputs.json \
  --max-retries 2 \
  --format uipath
```

### Data shape (every test passed)

```json
{
  "Result": "Success",
  "Code": "RunPackage",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ExecutionUrl": "https://cloud.uipath.com/org/tenant/testmanager_/DEMO/testexecutions/a1b2c3d4-0000-0000-0000-000000000001",
    "PackageName": "MyTests",
    "PackageVersion": "1.0.3",
    "FolderPath": "Shared",
    "Status": "Finished",
    "TotalTests": 12,
    "Passed": 12,
    "Failed": 0,
    "Cancelled": 0,
    "Format": "junit",
    "OutputPath": "./results/junit.xml",
    "Retries": 0
  }
}
```

| Field | Meaning |
|---|---|
| `PackageVersion` | The exact version that ran, resolved from `--package-version`. |
| `Retries` | How many re-runs of failed test cases took place. |
| `OutputPath` | Where the report was written. |
| `IgnoredInputs`, `DeclaredInputs` | Present only when `--input-path` names inputs that no test declares: the ignored names, and the names the tests do declare. |
| `MissingResults` | Present only when Test Manager counts more tests than reported a result. |
| `AssertionsNotRead` | Present only when the assertions of some tests could not be read; the report has no failure details for them. |

When the tests pass but inputs were ignored or assertions could not be read, the success envelope also carries a `Warning`.

### Data shape (a test failed)

```json
{
  "Result": "Failure",
  "Code": "RunPackageTestsFailed",
  "ErrorCode": "execution_failed",
  "Message": "2 of 12 tests did not pass (2 failed).",
  "Instructions": "See the report at ./results/junit.xml or open https://cloud.uipath.com/org/tenant/testmanager_/DEMO/testexecutions/a1b2c3d4-0000-0000-0000-000000000001.",
  "Retry": "RetryWillNotFix",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Finished",
    "TotalTests": 12,
    "Passed": 10,
    "Failed": 2,
    "Cancelled": 0,
    "Format": "junit",
    "OutputPath": "./results/junit.xml",
    "Retries": 0
  }
}
```

`Data` holds the full run summary, the same fields as on success; the example shows a subset. A cancelled execution returns `Code: "RunPackageCancelled"` instead. The report is written in both cases.

### Data shape (timeout)

```json
{
  "Result": "TimeoutError",
  "ErrorCode": "timeout",
  "Message": "Timed out while waiting for the tests.",
  "Instructions": "The tests may still be running. Check execution a1b2c3d4-0000-0000-0000-000000000001 in Test Manager, or run again with a larger --timeout. A report of the tests that finished is at ./results/junit.xml.",
  "Retry": "RetryLater",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Retries": 0,
    "OutputPath": "./results/junit.xml"
  }
}
```

`Data` is present only when the execution had started before the time ran out. `OutputPath` is present only when a partial report of the tests that finished could be written.

## Exit codes

| Exit code | Meaning |
|---|---|
| `0` | Every test passed. |
| `1` | A test failed or reported no result, the run was cancelled, no test ran, or a service call failed. |
| `2` | Login or permission problem after the run starts. A missing login or no access to the project exits `1` before the run starts. |
| `3` | Bad option or input, for example no project, no folder or both folder flags, an invalid `--package-version`, or a malformed `--input-path` file. |
| `4` | `--timeout` elapsed. |

Exit code `1` covers several outcomes. To tell them apart, read the envelope: `Code` is `RunPackageCancelled` for a cancelled run and `RunPackageTestsFailed` otherwise, `Data.TotalTests` is `0` when no test ran (for example, an empty or mis-specified package), and `Data.MissingResults` counts tests that reported no result. The missing-login case differs from the CLI-wide rule that authentication errors exit `2`; see [Exit codes](./exit-codes.md).

Unlike [`uip tm wait`](./uip-test-manager-wait.md), which exits `0` once an execution finishes whatever its results, `uip tm run` fails the step itself when a test does not pass.

## Related

- [uip or packages](./uip-or-packages.md) — `packages upload` publishes the package this command runs.
- [pack](./uip-test-manager-pack.md) — build a `.nupkg` from an external Playwright test project.
- [testsets run](./uip-test-manager-testsets.md#uip-tm-testsets-run) — start a run of an existing test set instead.
- [executions](./uip-test-manager-executions.md) — inspect, retry, or cancel the execution this command starts.
- [result](./uip-test-manager-result.md) — download JUnit XML for any execution.

## See also

- [Test Manager overview](./uip-test-manager.md)
- [Exit codes](./exit-codes.md)
- [Scripting patterns](./scripting-patterns.md)
