# uip tm perf-scenario

> Syntax and options for `uip tm perf-scenario`, which creates and runs Test Manager performance scenarios, inspects execution data, and generates reports.

`uip tm perf-scenario` manages Test Manager performance scenarios: create a scenario, bind test cases to it as load groups with a load profile (virtual users, ramp-up/peak/ramp-down timing, SLO thresholds), run it as a fast dry run or a full load test, then inspect the resulting execution data and render reports.

:::important
This page documents a real, fully shipped command group — it is registered unconditionally alongside every other `uip tm` command, not behind a feature flag. If you've been told this surface doesn't exist or is pre-release, verify directly with `uip tm perf-scenario --help`.
:::

This resource spans four pages:

- **This page** — concepts, and the scenario lifecycle: `create`, `get`, `list`, `execute`, `stop`, `list-dry-run-reports`.
- [Load groups](./uip-test-manager-perf-scenario-load-groups.md) — `load-groups add`/`update`/`remove`/`list`, the test-case-to-scenario binding and its load profile.
- [Execution data](./uip-test-manager-perf-scenario-execution-data.md) — `executions list`, `results get`, `http-errors list`, `automation-errors list`, `transaction-metrics list`.
- [Reports](./uip-test-manager-perf-scenario-report.md) — `report generate`, `report compare`.

## Concepts

- **Scenario** — the top-level performance test definition (`--scenario-key`, for example `SP1:7`). Created with `create`, inspected with `get`, run with `execute`.
- **Load group** — one test case bound to a scenario with a load profile (virtual users, timing, SLO thresholds, robot type). A scenario can have multiple load groups. See [Load groups](./uip-test-manager-perf-scenario-load-groups.md).
- **Execution** — one run of a scenario, either a `dryRun` (fast smoke run) or `performanceTesting` (full load run honoring each load group's load profile). Started with `execute`, inspected via [Execution data](./uip-test-manager-perf-scenario-execution-data.md), and stopped early with `stop`.
- **Dry-run report** — the Performance Service records a report after a passing dry run. A full `performanceTesting` run requires at least one passing dry-run report to already exist; check with `list-dry-run-reports` before running a full load test.

Most read verbs across all four pages accept `--query <expr>`, a jq-style filter applied client-side to the output `Data` before it's printed — use it to narrow a large payload (see the `list` example below).

## Synopsis

```text
uip tm perf-scenario create --project-key <key> --name <name> [--description <text>] [--version <version>] [--app-type <type>] [--perf-test-type <type>] [--responsiveness <level>]
uip tm perf-scenario get --scenario-key <key> [--project-key <key>]
uip tm perf-scenario list --project-key <key> [--search <text>] [--limit <n>] [--offset <n>] [--query <expr>]
uip tm perf-scenario execute --scenario-key <key> [--project-key <key>] [--execution-type <dryRun|performanceTesting>] [--wait [--full] [--poll-interval-sec <n>] [--timeout-sec <n>]]
uip tm perf-scenario stop --execution-id <uuid> --project-key <key>
uip tm perf-scenario list-dry-run-reports --scenario-key <key> [--project-key <key>]
```

All verbs honor the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). Every verb across all four `perf-scenario` pages accepts `--log-level <level>` (default `Information`).

:::note
`--project-key` is only a `.requiredOption()` on `create` and `stop` on this page (and on `load-groups update`/`remove`/`list` — see [Load groups](./uip-test-manager-perf-scenario-load-groups.md)). On `get`, `execute`, and `list-dry-run-reports` it's optional — the project is derived from the prefix of `--scenario-key` (for example, `SP1:7` → project `SP1`) when omitted, and `--project-key` overrides that derivation if passed. The verbs on the [Execution data](./uip-test-manager-perf-scenario-execution-data.md) and [Reports](./uip-test-manager-perf-scenario-report.md) pages don't take `--project-key` at all (except optionally on the two `report` verbs, where it only affects whether the returned link opens the in-app report page) — those verbs call the Performance Service directly rather than resolving a Test Manager project.
:::

## uip tm perf-scenario create

Create a performance scenario in a Test Manager project.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--name <name>` | **Required.** Scenario name. |
| `--description <text>` | Scenario description. Defaults to empty. Capped at 5120 characters. |
| `--version <version>` | Scenario version string. Defaults to `1.0`. Capped at 255 characters. |
| `--app-type <type>` | Application type: `web`, `apiService`, `ecommerce`, `gaming`, `financial`, `healthcare`, `saaS`, `streaming`, `messaging`, `enterprise`. Defaults to `web`. |
| `--perf-test-type <type>` | Performance test type: `loadTesting`, `stressTesting`, `enduranceTesting`, `spikeTesting`. Defaults to `loadTesting`. |
| `--responsiveness <level>` | Expected responsiveness: `instant`, `fast`, `moderate`, `slow`, `verySlow`. Defaults to `fast`. |

### Example

```bash
uip tm perf-scenario create \
  --project-key SP1 \
  --name "Checkout load" \
  --app-type web \
  --perf-test-type loadTesting \
  --responsiveness fast
```

### Data shape

```json
{
  "Code": "ScenarioCreate",
  "Data": {
    "ScenarioKey": "SP1:7",
    "Name": "Checkout load",
    "Version": "1.0",
    "AppType": "web",
    "PerfTestType": "loadTesting",
    "Responsiveness": "fast"
  }
}
```

## uip tm perf-scenario get

Get a scenario's metadata and the load groups bound to it.

### Options

| Flag | Description |
|---|---|
| `--scenario-key <key>` | **Required.** Scenario object key (for example, `SP1:7`). |
| `--project-key <key>` | Owning project. Optional — derived from the `--scenario-key` prefix when omitted. |

### Example

```bash
uip tm perf-scenario get --scenario-key SP1:7
```

### Data shape

```json
{
  "Code": "ScenarioGet",
  "Data": {
    "ScenarioKey": "SP1:7",
    "Name": "Checkout load",
    "Version": "1.0",
    "Description": "",
    "AppType": "web",
    "PerfTestType": "loadTesting",
    "Responsiveness": "fast",
    "LoadGroups": [
      {
        "LoadGroupId": "8e322581-0a25-0000-738b-0b49fd936ca1",
        "TestCaseKey": "SP1:602",
        "Name": "Checkout flow",
        "PackageName": "Checkout_Tests",
        "PackageVersion": "1.0.2",
        "FolderKey": "94821c49-ab85-49cb-94e1-f82c6d8973be",
        "VirtualUsers": 20,
        "Enabled": true
      }
    ]
  }
}
```

`LoadGroupId` here is the scenario's load group id — the identifier `load-groups update` and `load-groups remove` expect (see [Load groups](./uip-test-manager-perf-scenario-load-groups.md)). This is a different id from the per-execution rows returned by `load-groups list`.

## uip tm perf-scenario list

List the performance scenarios in a project.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--search <text>` | Filter scenarios by name or key. |
| `--limit <n>` | Max results to return. Defaults to the service's own page size when omitted. |
| `--offset <n>` | Results to skip, for paging. Defaults to `0`. |
| `--query <expr>` | jq-style filter applied to the output data. |

### Examples

```bash
uip tm perf-scenario list --project-key DEMO
```

```bash
# search by name, narrowing the output to just the scenario rows
uip tm perf-scenario list --project-key DEMO --search checkout --query .Scenarios
```

### Data shape

```json
{
  "Code": "PerfScenariosList",
  "Data": {
    "Total": 2,
    "Count": 2,
    "Scenarios": [
      {
        "ScenarioKey": "DEMO:7",
        "Name": "Checkout load",
        "Version": "1.0",
        "AppType": "web",
        "PerfTestType": "loadTesting",
        "Responsiveness": "fast",
        "VirtualUsers": 20,
        "DurationMinutes": 0,
        "Updated": "2025-04-15T10:30:00Z",
        "UpdatedBy": "alice@example.com"
      },
      {
        "ScenarioKey": "DEMO:9",
        "Name": "Search stress",
        "Version": "1.0",
        "AppType": "web",
        "PerfTestType": "stressTesting",
        "Responsiveness": "fast",
        "VirtualUsers": 100,
        "DurationMinutes": 0,
        "Updated": "2025-04-15T10:30:00Z",
        "UpdatedBy": "alice@example.com"
      }
    ]
  }
}
```

`Total` is the server-reported total match count, which can exceed `Count` (the number of rows actually returned) when `--limit` truncates the page.

## uip tm perf-scenario execute

Execute a scenario and return its execution id. Default mode is `dryRun` (fast smoke run); pass `--execution-type performanceTesting` for a full load run honoring the load-profile flags on each load group. A full run requires at least one passing dry-run report to already exist — check with `list-dry-run-reports` first.

### Options

| Flag | Description |
|---|---|
| `--scenario-key <key>` | **Required.** Scenario object key (for example, `SP1:7`). |
| `--project-key <key>` | Owning project. Optional — derived from the `--scenario-key` prefix when omitted. |
| `--execution-type <type>` | `dryRun` or `performanceTesting`. Defaults to `dryRun`. |
| `--wait` | Poll until the run reaches a terminal state (`Finished` or `Cancelled`), then emit the same shape as `results get` (see [Execution data](./uip-test-manager-perf-scenario-execution-data.md)). Exits non-zero if the run is `Cancelled`, an automation config failed, or an SLO was violated. |
| `--full` | With `--wait`, include the per-second time series (`AggregatedData` + `AggregatedDataWithTransaction`) in the output. Errors if passed without `--wait`. |
| `--poll-interval-sec <n>` | With `--wait`, seconds between status checks. Defaults to `12`. Errors if passed without `--wait`. |
| `--timeout-sec <n>` | With `--wait`, maximum seconds to wait (`0` = no timeout). Defaults to `1800`. Errors if passed without `--wait`. Elapsing exits `4` — the run keeps going, so re-check it with `results get`. |

### Examples

```bash
# start a dry run and return immediately
uip tm perf-scenario execute --scenario-key SP1:7
```

```bash
# run a full performance test and wait for the results bundle
uip tm perf-scenario execute \
  --scenario-key SP1:7 \
  --execution-type performanceTesting \
  --wait
```

### Data shape — without `--wait`

```json
{
  "Code": "ScenarioExecute",
  "Data": {
    "ScenarioKey": "SP1:7",
    "ExecutionId": "80694766-5a44-0000-0985-0b49fd93832d",
    "ExecutionType": "dryRun",
    "Status": "Pending"
  }
}
```

### Data shape — with `--wait`

```json
{
  "Code": "ScenarioExecutionResults",
  "Data": {
    "ExecutionId": "80694766-5a44-0000-0985-0b49fd93832d",
    "LoadGroupCount": 1,
    "LoadGroups": [
      {
        "LoadGroupId": "8e322581-0a25-0000-738b-0b49fd936ca1",
        "StartedAt": "2025-04-15T10:30:00Z",
        "CumulativeResponseTimeMs": 120,
        "MaxResponseTimeMs": 450,
        "SuccessfulWorkflowCount": 98,
        "FailedWorkflowCount": 2,
        "HttpErrorCount": 0,
        "HttpErrorRate": 0,
        "AutomationErrorCount": 2,
        "AutomationErrorRate": 0.02,
        "SloViolationReasons": []
      }
    ],
    "LogCount": 12,
    "ApplicationLogs": [
      {
        "CreatedAt": "2025-04-15T10:31:00Z",
        "LogLevel": "Information",
        "ExecutionId": "80694766-5a44-0000-0985-0b49fd93832d",
        "Message": "Execution finished"
      }
    ]
  }
}
```

`--wait` polls `results get` internally, so this is the same payload shape `results get` returns for a finished run — `execute --wait` just saves a second command. A non-empty `SloViolationReasons` array on any load group, or an application log matching "configuration execution has ended with the status 'failed'", makes the command exit non-zero even though the run reached a terminal state.

## uip tm perf-scenario stop

Cancel a running scenario execution.

### Options

| Flag | Description |
|---|---|
| `--execution-id <uuid>` | **Required.** Scenario execution UUID (the `ExecutionId` from `execute`). |
| `--project-key <key>` | **Required.** Owning project. |

### Example

```bash
uip tm perf-scenario stop --execution-id 80694766-5a44-0000-0985-0b49fd93832d --project-key SP1
```

### Data shape

```json
{
  "Code": "ScenarioStop",
  "Data": {
    "ExecutionId": "80694766-5a44-0000-0985-0b49fd93832d",
    "Result": "Stopping",
    "Note": "Server has accepted the cancel request. Run 'perf-scenario results get --execution-id <ID>' to confirm terminal status (will be 'Cancelled')."
  }
}
```

`Result: "Stopping"` reflects that the server accepted the cancel request, not that the execution has actually stopped yet — cancellation is asynchronous.

## uip tm perf-scenario list-dry-run-reports

List successful dry-run reports for a scenario. Run this **before** submitting a full `performanceTesting` run — a full run requires a passing dry-run report to already exist for each load group's automation.

### Options

| Flag | Description |
|---|---|
| `--scenario-key <key>` | **Required.** Scenario object key (for example, `SP1:7`). |
| `--project-key <key>` | Owning project. Optional — derived from the `--scenario-key` prefix when omitted. |

### Example

```bash
uip tm perf-scenario list-dry-run-reports --scenario-key SP1:7
```

### Data shape

```json
{
  "Code": "ScenarioDryRunReports",
  "Data": {
    "ScenarioKey": "SP1:7",
    "ScenarioId": "756e8ebf-c227-0000-8a9f-0b49fd934bef",
    "HasPassingDryRun": true,
    "ReportCount": 1,
    "Reports": [
      {
        "AutomationId": "auto-1",
        "RuntimeType": 4,
        "RecommendedMultiplexingFactor": 3,
        "ApplicationType": null
      }
    ]
  }
}
```

An empty `Reports` array (and `HasPassingDryRun: false`) means no load group has a passing dry run yet — run `execute` (default `dryRun` mode) first. This command errors instead of returning an empty result if the scenario has no load groups, or if none of its load groups' test cases carry a linked automation.

## Related

- [Load groups](./uip-test-manager-perf-scenario-load-groups.md) — bind test cases to a scenario and tune their load profile.
- [Execution data](./uip-test-manager-perf-scenario-execution-data.md) — inspect a finished or in-progress execution.
- [Reports](./uip-test-manager-perf-scenario-report.md) — render authored reports for an execution or a comparison.
- [testcases](./uip-test-manager-testcases.md) — `link-automation` is what gives a test case the `automationId` that `load-groups add` and `list-dry-run-reports` depend on.
- [project](./uip-test-manager-project.md) — scope that owns every scenario.

## See also

- [Test Manager overview](./uip-test-manager.md)