UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

uip tm perf-scenario

Syntax and options for `uip tm perf-scenario`, which creates, runs, and deletes Test Manager performance scenarios, checks the remaining performance testing license units, 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, the scenario lifecycle (create, get, list, delete, execute, stop, list-dry-run-reports), and licenses get.
  • Load groups — load-groups add/update/remove/list/get, the test-case-to-scenario binding and its load profile.
  • Execution data — executions list, results get, http-errors list, automation-errors list, transaction-metrics list, jobs list, robot-logs list.
  • Reports — 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, removed with delete.
  • 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.
  • 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, 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.
  • Virtual-user units — the tenant's performance testing license budget. A full run consumes units; a dry run consumes none. Check what is left with licenses get.

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​

uip tm perf-scenario create (--project-id <id> | --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>
uip tm perf-scenario list (--project-id <id> | --project-key <key>) [--search <text>] [--limit <n>] [--offset <n>] [--query <expr>]
uip tm perf-scenario delete --scenario-key <key> --yes
uip tm perf-scenario execute --scenario-key <key> [--execution-type <dryRun|performanceTesting>] [--wait [--full] [--poll-interval-sec <n>] [--timeout-sec <n>]]
uip tm perf-scenario stop --execution-id <uuid> (--project-id <id> | --project-key <key>)
uip tm perf-scenario list-dry-run-reports --scenario-key <key>
uip tm perf-scenario licenses get (--project-id <id> | --project-key <key>)
uip tm perf-scenario create (--project-id <id> | --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>
uip tm perf-scenario list (--project-id <id> | --project-key <key>) [--search <text>] [--limit <n>] [--offset <n>] [--query <expr>]
uip tm perf-scenario delete --scenario-key <key> --yes
uip tm perf-scenario execute --scenario-key <key> [--execution-type <dryRun|performanceTesting>] [--wait [--full] [--poll-interval-sec <n>] [--timeout-sec <n>]]
uip tm perf-scenario stop --execution-id <uuid> (--project-id <id> | --project-key <key>)
uip tm perf-scenario list-dry-run-reports --scenario-key <key>
uip tm perf-scenario licenses get (--project-id <id> | --project-key <key>)

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

The project comes from one of two places:

  • create, list, stop, and licenses get take --project-id or --project-key. When you pass both, --project-id wins. If you pass neither, the command fails with ErrorCode: invalid_argument.
  • get, delete, execute, and list-dry-run-reports take no project option. The project is derived from the prefix of --scenario-key (for example, SP1:7 → project SP1).

Refer to the Load groups, Execution data, and Reports pages for the project options of their verbs.

uip tm perf-scenario create​

Create a performance scenario in a Test Manager project.

Arguments​

None.

Options​

FlagDescription
--project-id <id>Test Manager project ID. Wins if --project-key is also given.
--project-key <key>Test Manager project key (for example, SP1). Ignored if --project-id is also given.
--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​

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

Data shape​

{
  "Code": "ScenarioCreate",
  "Data": {
    "ScenarioKey": "SP1:7",
    "Name": "Checkout load",
    "Version": "1.0",
    "AppType": "web",
    "PerfTestType": "loadTesting",
    "Responsiveness": "fast"
  }
}
{
  "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.

Arguments​

None.

Options​

FlagDescription
--scenario-key <key>Required. Scenario object key (for example, SP1:7). The project is derived from the prefix.

Example​

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

Data shape​

{
  "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
      }
    ]
  }
}
{
  "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). This is a different id from the per-execution rows returned by load-groups list.

uip tm perf-scenario delete​

Delete a performance scenario and its load groups. Past executions and their results are kept but are no longer linked to the scenario. A running execution is not stopped; stop it first with stop.

Arguments​

None.

Options​

FlagDescription
--scenario-key <key>Required. Scenario object key (for example, SP1:7). The project is derived from the prefix.
-y, --yesRequired. Confirms the irreversible operation. The CLI never prompts; without --yes the command returns Result: "Failure" and exits 1.

Example​

uip tm perf-scenario delete --scenario-key SP1:7 --yes
uip tm perf-scenario delete --scenario-key SP1:7 --yes

Data shape​

{
  "Code": "ScenarioDelete",
  "Data": {
    "ScenarioKey": "SP1:7",
    "ScenarioId": "756e8ebf-c227-0000-8a9f-0b49fd934bef",
    "Result": "Deleted"
  }
}
{
  "Code": "ScenarioDelete",
  "Data": {
    "ScenarioKey": "SP1:7",
    "ScenarioId": "756e8ebf-c227-0000-8a9f-0b49fd934bef",
    "Result": "Deleted"
  }
}

uip tm perf-scenario list​

List the performance scenarios in a project.

Arguments​

None.

Options​

FlagDescription
--project-id <id>Test Manager project ID. Wins if --project-key is also given.
--project-key <key>Test Manager project key (for example, DEMO). Ignored if --project-id is also given.
--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​

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

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

Data shape​

{
  "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": "[email protected]"
      },
      {
        "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": "[email protected]"
      }
    ]
  }
}
{
  "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": "[email protected]"
      },
      {
        "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": "[email protected]"
      }
    ]
  }
}

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, and check the remaining virtual-user units with licenses get.

Arguments​

None.

Options​

FlagDescription
--scenario-key <key>Required. Scenario object key (for example, SP1:7). The project is derived from the prefix.
--execution-type <type>dryRun or performanceTesting. Defaults to dryRun.
--waitPoll until the run reaches a terminal state (Finished or Cancelled), then emit a summary built from the same execution data as results get (see Execution data). Exits non-zero if the run is Cancelled, an automation config failed, or an SLO was violated.
--fullWith --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​

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

# run a full performance test and wait for the results bundle
uip tm perf-scenario execute \
  --scenario-key SP1:7 \
  --execution-type performanceTesting \
  --wait
# 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​

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

Data shape — with --wait​

{
  "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"
      }
    ]
  }
}
{
  "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 the execution status until it is terminal, then reads the same execution data as results get and returns it in this LoadGroups/ApplicationLogs shape (Code ScenarioExecutionResults). results get returns the unformatted ExecutionsData map. 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.

Arguments​

None.

Options​

FlagDescription
--execution-id <uuid>Required. Scenario execution UUID (the ExecutionId from execute).
--project-id <id>Test Manager project ID. Wins if --project-key is also given.
--project-key <key>Test Manager project key (for example, SP1). Ignored if --project-id is also given.

Example​

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

Data shape​

{
  "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')."
  }
}
{
  "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.

Arguments​

None.

Options​

FlagDescription
--scenario-key <key>Required. Scenario object key (for example, SP1:7). The project is derived from the prefix.

Example​

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

Data shape​

{
  "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
      }
    ]
  }
}
{
  "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.

uip tm perf-scenario licenses get​

Get the virtual-user units left on the tenant's performance testing license. The value covers the whole tenant, so every project returns the same number.

A full performanceTesting run uses virtual users × units per virtual user. Dry runs use no units.

Load group targetUnits per virtual user
API test1
Chrome or Edge10
Anything else100

Test Manager caches the units in use for up to 4 hours, so the value can lag right after a run starts or ends.

Arguments​

None.

Options​

FlagDescription
--project-id <id>Test Manager project ID. Wins if --project-key is also given.
--project-key <key>Test Manager project key (for example, DEMO). Ignored if --project-id is also given.

Example​

uip tm perf-scenario licenses get --project-key DEMO
uip tm perf-scenario licenses get --project-key DEMO

Data shape​

{
  "Code": "PerfLicensesGet",
  "Data": {
    "RemainingVirtualUserUnits": 4900
  }
}
{
  "Code": "PerfLicensesGet",
  "Data": {
    "RemainingVirtualUserUnits": 4900
  }
}
  • Load groups — bind test cases to a scenario and tune their load profile.
  • Execution data — inspect a finished or in-progress execution.
  • Reports — render authored reports for an execution or a comparison.
  • testcases — link-automation is what gives a test case the automationId that load-groups add and list-dry-run-reports depend on.
  • project — scope that owns every scenario.

See also​

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated