uipath-test

UiPath Test Assistant

Manage UiPath Test Manager projects, requirements (including AI test case generation, requirement evaluation and obsolete test case search), test cases, test sets, executions, logs, defects, attachments, results, custom fields, performance (load) test scenarios, labels, and persona-tailored shareable test reports.

Use For

Test Manager CRUD; CI runs of every test in an uploaded package; execution analysis, coverage, regression trends, failure rates, go/no-go summaries; failed-run triage; flaky-versus-regression analysis; failure evidence; load-testing an automated test case and finding why a load run failed; and shareable QA-engineer, developer, or release-manager reports.

Concepts and CLI

Requirements define what must be tested; test cases define scenarios and may contain teststeps; test sets group cases; executions are created when a test set or testcase runs. Testcase logs record a testcase in an execution and provide navigation; test-step logs record steps; testcase-log assertions are assertion steps. Test Manager's AI works from a requirement's description and attachments: it proposes test cases, suggests improvements to the requirement, or flags linked test cases that look obsolete. Each runs as a background job with an activity id. A defect is a bug raised from one testcase log and synced to the project's defect tracker (Jira, Azure DevOps, …).

Performance scenarios load-test automated test cases. A scenario holds load groups: a test case, the Orchestrator package and folder it runs from, and a load profile (virtual users, ramp-up, peak, ramp-down). Running a scenario creates an execution; a dry run checks it works, a performance run applies the full load and draws on the tenant's performance testing licence.

External Playwright packages are suites packaged and uploaded to Orchestrator. Ingestion auto-creates one testcase per Playwright test, without a link step, and labels each PW_Tag_*, PW_Project_*, PW_Suite_*, and PW_File_*. They run on serverless cloud runtimes; see references/playwright-first-mile-guide.md.

Use uip tm; discover syntax with uip tm --help and uip tm <command> <subcommand> --help. Always pass --output json to every uip command; all commands below require it. When a value comes from a file, pass it as "$(cat <FILE>)"; never retype it from what you read.

Commands

Projects, folders, and requirements

• Projects: uip tm project list --filter <NAME_OR_KEY> finds by name/key; project create --name <PROJECT_NAME> --project-key <PROJECT_KEY> creates; project update --project-key <PROJECT_KEY> --name <PROJECT_NAME> updates name/description; project delete --project-key <PROJECT_KEY> deletes; project set-default-folder --project-key <PROJECT_KEY> --folder-key <FOLDER_KEY> sets the default Orchestrator folder; project clear-default-folder --project-key <PROJECT_KEY> clears it; project owners list --project-key <PROJECT_KEY> [<PROJECT_KEY> ...] lists owners.
• Default project: one per tenant, for runs with no project of their own (CI). Rows of project list, create and update carry IsDefault.
  • To find which project is the default, run uip tm project list --limit 1 --output json without --filter. Test Manager lists the default first, so it is the default only when Data[0].IsDefault is true. Otherwise this login sees no default: the tenant has none yet, or it has one this login cannot open (the list leaves out projects the caller cannot open). Report that as "no default visible", not as "the tenant has none".
  • uip tm project get-default --output json returns the default and creates one when there is none: Default Project (key TMDP), opened to the tenant's Everyone group. Run it only when the user needs a project to work in, never just to look.
  • New work with no project named goes to the default project. When the user asks to create test cases, test sets or requirements, or to run a package, and names no project, run get-default, use its ProjectKey, and tell the user the work went into that project (name and key). Only for new work: to read, change or delete existing items, ask for the project (Quick Start step 2).
  • uip tm project update --project-key <PROJECT_KEY> --set-default --output json makes an existing project the default (needs TM.Administration, or a tenant administrator). Who can open that project does not change, so callers without access to it then get permission_denied from get-default. There is no project create --set-default.
  • permission_denied from either command: report its Message and Instructions and stop (Rule 10).
• Permissions: uip tm project-permissions get returns Data.Permissions (the permission names the caller holds on that project) and Data.Count. Gated on Project.Read, so a successful get always carries at least Project.Read (Count >= 1); no read access fails with a 403 (or 404 for a project you cannot see), never a Success with an empty array. Only get is exposed.
• Project settings: uip tm project settings get --project-key <PROJECT_KEY> reads time zone, execution name format, step cap, default folder and governance; project settings update --project-key <PROJECT_KEY> [--time-zone <IANA_NAME>] [--execution-name-format <TEMPLATE>] writes only those first two. IANA names, placeholders, read-only fields and half-applied updates: references/project-settings-guide.md.
• Get folder keys with uip or folders list -n <name> --all --output json; it returns all folders visible to the current user.
• Prefix with uip tm requirements: list --project-key <PROJECT_KEY> optionally --test-case-id <UUID> (requirements a test case covers — use this, never scan list-testcase-ids per requirement), --filter, --labels, --requirement-ids, --limit, --offset; list-by-test-execution --project-key <PROJECT_KEY> --execution-id <uuid>; get --project-key <PROJECT_KEY> (--requirement-id <uuid> | --requirement-key <key>) (mutually exclusive UUID/key); create --project-key <PROJECT_KEY> --name <name>; update --project-key <PROJECT_KEY> --requirement-id <uuid> (updates name/description and requires at least one of --name or --description); delete --project-key <PROJECT_KEY> --requirement-ids <uuid...> (variadic IDs); export --project-key <PROJECT_KEY> --output-file <path> (exports .xlsx); list-testcase-ids --project-key <PROJECT_KEY> --requirement-id <uuid>; testcases --project-key <PROJECT_KEY> --requirement-id <uuid> (--add-testcase-ids <uuid...> | --remove-testcase-ids <uuid...>) (mutually exclusive attach/detach selectors).
• Move or back up a whole project with uip tm project export → uip tm project import (a .tmh package): references/project-migration-guide.md. Jobs are read with uip tm migration get|list|download; package schemas with uip tm migration schemas list|download.
  • Both are jobs of minutes. Pass --wait (export also --output-file); without it you get a job id for migration get. Never start a second export or import to check on one.
  • Automation goes in by default (--exclude automation drops it); governance, project config (Test Cloud only, else 403) and prompts only with --include.
  • Test sets travel only as .tmh; test cases and requirements can also go to Excel (testcases export, requirements export). "Export these" with no format or purpose: ask which.
  • Before importing, ask: into an existing project, or a new one (--create-project)? A taken key: ask for --new-project-key.

AI on requirements

uip tm requirements generate-testcases, uip tm requirements evaluate and uip tm requirements find-obsolete-testcases each run a background AI job and return an ActivityId. Each start spends AI units: start once, then reuse --activity-id <ACTIVITY_ID> to wait, show, create, unlink or delete; never start again to retry. Bound waits with --timeout 540 and a 600 s shell limit. Scenarios, field meanings (Score, ConfidenceLevel) and the outcome rules: references/requirement-ai-guide.md.

Prompt library

uip tm prompts list|get|create manage a project's reusable AI guidelines. ModeOfUse (--mode-of-use on create, --modes-of-use on list) is the Autopilot feature that offers the prompt; ask when the user names none.

• No update or delete in the CLI, and names are not unique. Before create, run get --name <NAME> (exact, case-sensitive); ErrorCode: not_found means absent, not a Rule 10 stop. Found: do not create again; report it, and say changing it needs the Test Manager UI. Several matches: get fails; use --prompt-id from list.
• list mixes built-in samples (PromptType: Internal) with team prompts (UserDefined); --filter is a prefix match on name or description.
• Guidelines are required, max 4096 characters: --guidelines, or --guidelines-file for multi-line text. Over a limit fails before anything is sent.
• requirements generate-testcases, evaluate and find-obsolete-testcases take no prompt id: to apply a library prompt, pass its Guidelines as --instructions.
• To export prompts, run uip tm project export --include prompts; a default export leaves them out.

Test cases

• uip tm testcases create --project-key <PROJECT_KEY> --name <TEST_CASE_NAME>; list --project-key <PROJECT_KEY> optionally --filter <text> matching name/key by PREFIX, not substring; update --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> --name <TEST_CASE_NAME> updates name, description, precondition, or postcondition and requires at least one field; delete --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> deletes by key.
• link-automation --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> --folder-key <FOLDER_KEY> --package-name <PACKAGE_NAME> --test-name <TEST_NAME> links Orchestrator package automation, optionally --entry-point-id <PACKAGE_ENTRY_POINT_ID> (from list-automations) to bind by id, which overrides --test-name; unlink-automation --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> unlinks; list-automations --project-key <PROJECT_KEY> --folder-key <FOLDER_KEY> lists folder test entry points, optionally --package-name <PACKAGE_NAME>, each row carrying PackageEntryPointId; list-testsets --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> lists containing sets.
• Look up, inventory, copy and bulk-create test cases with uip tm testcases (flags via --help):
  • get --test-case-key adds what list rows lack: pre/postcondition, Created, PackageEntryPointId. get --automation-id <PACKAGE_ENTRY_POINT_ID> returns one case behind an automation; several may share it, so to find all, list and match PackageEntryPointId. list-requirements --test-case-key lists the requirements covering a case. list-packages / list-studio-projects list the distinct package / Studio project names of automated cases (--filter is a prefix).
  • "Which sets include the cases labelled X" is one list-testsets --labels X, never a loop over cases. It shows explicit assignments only, not sets that pull a case in by a dynamic label; say so.
  • clone returns Accepted with no key and copies in the background, steps last. Find the copy with the list --filter from Instructions. Never clone again to check or retry; after a 5xx, list first, as a copy may exist. Labels, documents, requirements and parameters copy only with --include.
  • bulk-create --file takes a JSON array of {"name", "labels": [...], "steps": [{"description", "expectedResult"}]}. Names are not unique, so a re-run duplicates. Pass --skip-existing when some names may already exist. A file error (exit 3) creates nothing. If a later batch fails, earlier ones stay: report and ask before re-running. KeysResolved: false still means created.
  • list --automated leaves out Playwright-linked cases. A 403 on group-by (licence or feature off): stop and tell the user.
• Steps: uip tm testcases steps list --project-key <PROJECT_KEY> --test-case-id <TEST_CASE_ID> lists manual steps using --test-case-id <UUID>, not --test-case-key. steps get --project-key <PROJECT_KEY> --step-id <UUID> gets; steps add --project-key <PROJECT_KEY> --test-case-id <UUID> --description <text> adds flag-mode steps (--description required), or steps add --project-key <PROJECT_KEY> --test-case-id <UUID> --step '<json>' [--step '<json>' ...] adds repeated JSON steps (mutually exclusive with flag mode and not atomic: earlier steps persist if a later one fails); steps update --project-key <PROJECT_KEY> --step-id <UUID> updates passed fields only; steps move --project-key <PROJECT_KEY> --step-id <UUID> --target-position <n> moves to 0-based position; steps delete --project-key <PROJECT_KEY> --step-id <UUID> --yes deletes.
• list-result-history --project-key <PROJECT_KEY> --test-case-id <TEST_CASE_ID> lists history, optionally --only-failed, --filter, --limit, --offset. run --project-key <PROJECT_KEY> --test-case-id <TEST_CASE_ID> --name <EXECUTION_NAME> --execution-type <manual|automated|none|mixed> starts an execution for one or more space-separated testcase UUIDs; optionally --async, --folder-key, --robot-user-key, --machine-key.
• uip tm testcases add --test-set-key <TEST_SET_KEY> (--test-case-keys <KEY1> <KEY2> … | --labels <Label1> <Label2> …) adds by explicit keys or every testcase carrying at least one label; selectors are mutually exclusive and variadic space-separated. Keys also accept comma form (DEMO:1,DEMO:2), labels do not (--labels A,B is one label). Label matching is OR, exact, and case-insensitive; quote labels containing spaces. Without --dynamic, --labels copies the current matches into the set once; testcases labeled later are not added. uip tm testcases remove --test-set-key <TEST_SET_KEY> --test-case-keys <KEY1,KEY2,...> removes comma-separated static links; it succeeds but does nothing for a testcase included only by a dynamic label — change its labels or the set's dynamic labels instead.
• Assign testcases dynamically (membership follows labels): uip tm testcases add --test-set-key <TEST_SET_KEY> --labels <Label1> <Label2> … --dynamic stores the labels on the test set; every testcase carrying at least one (OR, exact, case-insensitive) is part of the set and every run, including testcases labeled later. Merges with labels already set (max 30), keeps static links, returns DynamicLabels and MatchedTestCases; --limit and --test-case-keys are rejected with --dynamic. uip tm testcases remove --test-set-key <TEST_SET_KEY> --dynamic [--labels <Label1> …] --yes removes those labels, or all when --labels is omitted (Result Removed, Cleared, or NotSet). Not allowed on test sets linked from an external source. Pick --dynamic for suites that must track labels (CI "everything labeled smoke"); omit it for a fixed snapshot. If uip tm testcases add --help lists no --dynamic, the CLI predates it: use --labels without it and re-run when labels change.
• Parameters (uip tm testcases parameters, test cases only): the value flag is --default-value, not --value.
  • Names are unique per test case, match exactly ignoring case, never fuzzily (User name ≠ Username). Check existence with list --search and an exact Name; empty means absent, not a Rule 4/10 stop. Read one value with get --parameter-name <NAME>; its not_found also means absent. Near miss: ask the user to confirm the closest.
  • An existing parameter is never changed by an "add" request, even when the request gives a different value: never run update for it. Single add: say it exists and ask for another name. Adding to several test cases: skip it, leave its value, and list it as skipped. Changing a missing name: ask before creating it. A rename onto a name in use is refused; report it. Confirm deletes (Rule 5).
  • delete returns Success even when nothing went; report Data.Passed/Data.Failed. Adding to many test cases: list each, add only missing names, then summarise added vs skipped per test case.
• Use --test-case-id <UUID> with run, steps list, steps add, list-result-history, and testcaselog start/finish; obtain it from uip tm testcases list --output json (Id), or — when you are recording results into a run you just opened — from that run's own logs, which give every id in one call (see Execution lifecycle). Use singular --test-case-key <PROJECT_KEY:NUMBER> with update, delete, link-automation, unlink-automation, and list-testsets. Use plural --test-case-keys <KEY1,KEY2,...> for comma-separated test-set bulk membership. Use --step-id <UUID> with all steps commands except list and add; obtain it from steps list (Id).

Test sets and executions

• uip tm testsets create --project-key <PROJECT_KEY> --name <TEST_SET_NAME>, optionally --dynamic-labels <Label1> … to create the set with testcases assigned dynamically by those labels (returns DynamicLabels, MatchedTestCases); list --project-key <PROJECT_KEY> optionally --filter <text>, --folder-key, --include-last-execution; update --test-set-key <TEST_SET_KEY> --name <TEST_SET_NAME> updates name/description; delete --test-set-key <TEST_SET_KEY>; list-testcases --project-key <PROJECT_KEY> --test-set-key <TEST_SET_KEY> lists the cases a run executes — static links plus dynamic-label matches — with AssignmentType Static, Dynamic, or Both; get-dynamic-assignment --project-key <PROJECT_KEY> --test-set-key <TEST_SET_KEY> returns its DynamicLabels ([] when none) and MatchedTestCases.
• uip tm testsets run --test-set-key <TEST_SET_KEY> runs and returns an execution ID; optionally --execution-type <automated|manual|mixed|none> (default automated), --input-path <FILE>, and for Playwright --playwright-project <name>. uip tm testsets playwright-context --test-set-key <TEST_SET_KEY> probes status and returns IsPlaywright, available projects, and selected projects.
• Keys are PROJECT_KEY:NUMBER. Add/remove membership — static or --dynamic — with uip tm testcases add/uip tm testcases remove, not testsets verbs. For Playwright sets, --playwright-project <name> takes one case-sensitive playwright.config name — at most one project per execution — and persists the selection. Every testcase must come from one Playwright package; an unknown name fails fast listing the valid ones. Probe first with playwright-context and branch on IsPlaywright. Both require Test Manager Playwright support and a CLI carrying external-package commands. See references/playwright-first-mile-guide.md, which begins with the availability check and absent-support action.
• Configure a set with uip tm testsets (get, clone, set-execution-order, settings get, settings set, assign-user, set-folder, set-robot, set-execution-target, autoselect-packages, group-by, list --labels):
  • clone waits and returns the copy's TestSetKey; --no-wait returns Accepted with no key. A timeout is a failure: stop and never clone again. Names can repeat, so give the copy one no other set has. Folder, robot, packages, the enforce flag and the order are not copied.
  • set-execution-order must list every assigned case (read list-testcases first; it does not show the order). Runs follow the order only after settings set --enforce-execution-order.
  • In settings only the enforce flag is writable; stop-on-failure, coverage, video, remote control and Autopilot are read-only — say so.
  • Name options (--folder-path, --robot-name, --assignee-email) resolve in Orchestrator. A 403 there, or on set-execution-target/group-by (licence or feature off): stop and tell the user. autoselect-packages saves nothing.
• uip tm executions list --project-key <PROJECT_KEY> lists top n, optionally --test-set-id <UUID>, --filter <text>, --status, --execution-type, --execution-finished-interval, --limit, --offset; use for the common one-test-set or single-project query. list-filtered --project-key <PROJECT_KEY> takes --test-set-id, --status, --execution-type, --execution-finished-interval, --limit, --offset and additionally --updated-by, --labels, --test-execution-ids, --sort-by; it has no --filter — the name search there is --search. Use it for label filtering, multiple execution IDs, custom ordering, or --updated-by. Both share the same enum values, which are lower-case and rejected otherwise: --status <pending|running|cancelling|finished|cancelled>, --execution-type <manual|automated|none|mixed|autonomous>, --execution-finished-interval <lastHour|lastDay|lastWeek|last15Days|last30Days>. Responses report Status capitalised (Running, Finished); do not feed a response value back as a filter.
• get-stats --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY> aggregates a run's pass/fail/none totals (report get also summarizes a completed run). Each executions list/list-filtered row already carries that run's Passed/Failed/None, equal to get-stats, so one list call answers the totals for every run on a set; run --execution-id <EXECUTION_ID> --execution-type <TYPE> reruns, optionally --test-case-log-ids <UUID...> (space-separated) and --async; retry --execution-id <EXECUTION_ID> retries only failed cases, optionally --project-key, --test-set-key, --execution-type; testcaselogs list --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY> lists case logs (--only-failed, --filter, --limit, --offset) and is nested, not a top-level executions verb. Use uip tm testcases run for testcase UUIDs, uip tm testsets run for a test-set key, and uip tm executions run to rerun an execution.

Execution lifecycle

Open a manual run with uip tm testsets run --test-set-key <KEY> --execution-type manual (id = Data.ExecutionId; there is no executions create verb), resolve each --test-case-id from the run's own logs via uip tm executions testcaselogs list --execution-id <ID>, then record each case with testcaselog start/finish. A manual run self-closes when its last log finishes — executions finish is the force-close for a run left with logs open, not the normal last step. set-reporting-date needs an already-closed run (ExecutionFinished, not Status). The manual-vs-automated distinction, filtered reads, every cancel/delete/finish/export/set-reporting-date caveat, and the exit-code contract live in references/executions-guide.md; discover flags and enums with -h.

Test set schedules

• Verbs (--help for flags): uip tm schedules create|update|list|next-runs|enable|disable|delete. list is the only read — no get by id — so recover values there before update, which replaces the whole definition (pass every flag you want kept; it cannot change the enabled state — use enable/disable). delete and --all need --yes.
• --cron is 6 or 7 fields starting with seconds, not Unix cron (daily at 02:00 is 0 0 2 1/1 * ? *; the CLI refuses a five-field expression client-side). --cron-details is the recurrence JSON and is required for every recurrence type. --start-time/--disable-time are wall-clock YYYY-MM-DDTHH:mm read in --timezone — seconds or a Z are refused. Pass next-runs the ids list prints — the endpoint underneath is keyed by a different GUID and answers 200 with an empty list for a bad id. Cron/recurrence rules and gotchas: references/schedules-guide.md.

Run an uploaded package (CI)

uip tm run --type package --package-name <PACKAGE_NAME> --package-version <VERSION> --folder-path <FOLDER_PATH> --project-key <PROJECT_KEY> --output json runs every test in a package already uploaded to Orchestrator, re-runs failures with --max-retries <N>, and writes a report. Pack and upload first with uip rpa pack / uip or packages upload.

• No project named: run uip tm project get-default --output json and pass its ProjectKey as --project-key (see Default project).
• Get <VERSION> from uip or packages versions <PACKAGE_NAME> --folder-path <FOLDER_PATH> --output json. An app version (1.0) runs its latest 1.0.x patch; an exact version must be the latest patch, and an older one exits 3 with nothing created.
• Under a CI step time limit, pass --timeout <SECONDS> below that limit (default 7200): a step killed first leaves no report.
• Exit 1 with RunPackageTestsFailed or RunPackageCancelled is a test result: report it, see Rule 10(d). Exit 4 is a timeout: the execution may still be running and Data.OutputPath holds a partial report with unfinished tests marked skipped. Report the timeout; never count skipped tests as passed. Every other non-zero exit stops (Rule 10).
• --input-path names that no test declares are listed in Data.IgnoredInputs; tell the user (usually a typo).

Logs, reports, attachments, and results

• uip tm testcaselog start --project-key <PROJECT_KEY> --execution-id <EXECUTION_ID> --test-case-id <TEST_CASE_ID> starts, optionally --run-id <NUMBER>. finish --project-key <PROJECT_KEY> --execution-id <EXECUTION_ID> --test-case-id <TEST_CASE_ID> --result <None|Passed|Failed|Restricted> --has-error <true|false> --executed-by <EMAIL> finishes (all three of --result, --has-error, --executed-by required) and records the result — how a manual run's case is marked Failed. --executed-by takes an email but is validated non-empty then discarded — the stored ExecutedBy is the authenticated caller, so never tell the user a result was attributed to whoever they named. Optionally --detail-link <URL>, --run-id, --is-post-condition-met, --step-logs <json> or --step-logs-file <path>. start needs an existing execution — there is no executions create; open one with uip tm testcases run … --execution-type manual or testsets run … --execution-type manual.
• Record manual step results on finish: start returns the testcase log Id and creates one step log per step; uip tm teststeplog list --project-key <PROJECT_KEY> --test-case-log-id <TEST_CASE_LOG_ID> --output json returns one step log per step; pass each back as {"id":"<STEP_LOG_ID>","testCaseLogId":"<TEST_CASE_LOG_ID>","result":"Passed","comment":"<text>","hasError":false}. Entries match by step-log id (not testStepId); unknown ids are silently ignored, and only result, comment, hasError, hasAttachment persist.
• Read logs: testcaselog list (filters --results/--statuses/--labels/--search/--assignees; no date/execution filter — narrow a run with executions testcaselogs list); get --test-case-log-id <ID> (--include-assertions); latest --test-case-ids <ID...> (newest per case). A result is overridden only when Result and OriginalResult are both populated and differ — an empty OriginalResult means not overridden. Correct a settled result with override create|update|delete|get (create needs --result and --reason). Assign a failure with assign --assignee-email <EMAIL> (CLI resolves it) or --assignee-id <IDP_UUID> (a UUID). cancel --test-case-log-id <ID> --yes stops one automated case's Orchestrator job; it answers CancelRequested even for a manual or finished log, which it ignores, so confirm with get (Status Cancelling). Whole run: executions cancel. Full surface + gotchas: references/testcaselog-guide.md.
• uip tm testcaselog list-assertions --project-key <PROJECT_KEY> --test-case-log-id <TEST_CASE_LOG_ID> lists assertions; render-assertions returns them as markdown; get-robot-logs returns an expiring link (or downloads with --output-file); uip tm teststeplog list --project-key <PROJECT_KEY> --test-case-log-id <TEST_CASE_LOG_ID> lists step logs.
• uip tm report get --execution-id <EXECUTION_ID> (--project-key <KEY> | --test-set-key <KEY>) summarizes a completed execution (TotalTests/Passed/Failed/None, PassRate as a number over passed + failed, so unrun None tests do not lower it, and FailedTests); exactly one project-identifying option is required. Passing only --execution-id exits with Provide --project-key or --test-set-key.
• uip tm attachment download --execution-id <EXECUTION_ID> downloads testcase attachments; attachment upload --object-id <UUID> --object-type <type> --file <path> uploads to a Test Manager object, such as --object-type testCaseLog; uip tm result download --execution-id <EXECUTION_ID> downloads JUnit XML, optionally --project-key, --test-set-key, --result-path <DIR>.
• Single files (uip tm attachment, upload returns AttachmentId): find the object first (list --test-case-keys / --requirement-keys), pick the file by FileName, then use its AttachmentId; no match or a duplicate name: ask. Already holding an id (from upload or an export job): get --attachment-id <ID> --object-type <TYPE> reads its metadata.
  • list shows only userBased files unless you pass --source (robot or Studio evidence: orchestrator, studio, taskCapture). Keys that don't resolve come back under Unresolved beside the rest — name them. An unknown --object-ids id also shows AttachmentCount: 0.
  • --object-type is the parent object's type, not the file's; a wrong one can still succeed.
  • download --attachment-id writes to the current folder under the server name unless --result-path/--output-file, and never replaces a file: on already exists, stop and ask; pass --overwrite only when the user asked.
  • update only renames (--file-name). --all is one page per call; follow Pagination. delete --attachment-id <ID> --object-type <TYPE> --yes: confirm first (Rule 5).
• Files out: uip tm testcases export (test cases to .xlsx; --test-case-ids, else the whole project) and uip tm report export (an execution's report, --execution-id --format excel|pdf|junit, or chosen results as PDFs, --test-case-log-ids, two or more as one .zip):
  • When the user wants the file, pass --wait --output-file <path>. Without --wait only a job starts: poll uip tm export-jobs get --job-id while Initiated/InProgress, stop on Failed/Cancelled, then attachment download --attachment-id <AttachmentId> as Instructions prints. Never start the same export twice to check on it.
  • An existing --output-file is refused before anything starts: ask, and pass --overwrite only when told.
  • export-jobs get needs the project that started the job (others return 404). JUnit off on the tenant (feature is not enabled) or a 403 on result PDFs (licence): report it, don't retry.

Playwright pack

uip tm pack --project-path <dir> --type playwright --project-key <PROJECT_KEY> --name <PackageName> --package-version <ver> -o <out-dir> packs a Playwright suite into a .nupkg; a lockfile and @playwright/test are required. --package-version is NuGet/SemVer-style with three or four numeric parts and an optional prerelease/build suffix (1.0.0, 1.0.0.0, 1.0.1-beta.1); 1.0 and nonnumeric values are rejected. --project-key targets the Test Manager project for automatic testcase ingestion; --no-create-test-cases skips it; --dry-run previews. Upload with uip or packages upload <nupkg>. Packing is offline and needs no auth. The upload → ingestion → label-fill → run pipeline is in references/playwright-first-mile-guide.md.

Defects

uip tm defects create | list | get | update | delete | get-external-issue | get-related | attachments list|download — raise a defect from a failed result, change its status/priority/tracker link, and trace it. Defects are UUID-only: find the one on a result through DefectId in executions testcaselogs list. Before any defects call, read references/defects-guide.md: update and delete often take 10–40 s and need a shell time limit of at least 120 s.

Wait and user

uip tm wait --execution-id <EXECUTION_ID> waits for terminal state; optionally --project-key, --test-set-key, --timeout <SECONDS>. uip tm user get gets the authenticated user's profile.

Custom fields

Project-scoped custom-field definitions (attach to Requirement/TestCase/TestSet) plus per-object label and value rows, via uip tm customfield …. Full command surface — scopes, --object-type/--data-type enums (case-sensitive: Requirement|TestCase|TestSet, Text|Label), --values JSON semantics, and every label/value verb: references/custom-fields-guide.md.

Object labels

Tag metadata via uip tm objectlabel … on Requirement, TestCase, TestSet, TestExecution, or TestCaseLog. Anti-patterns (label id vs object id; --remove-other-labels deleting hidden internal labels): references/object-labels-guide.md.

Performance (load) testing

Typical request: "can checkout handle 50 users?"

1. Find the automated test case (testcases list), its folder and package (testcases list-automations). IsAutomated: false with a PackageName is still linked (legacy link): use that package, never tell the user it has no automation.
2. uip tm perf-scenario create --project-key <PROJECT_KEY> --name <NAME>, then perf-scenario load-groups add --scenario-key <SCENARIO_KEY> --test-case-key <TEST_CASE_KEY> --folder-key <FOLDER_KEY> --package-name <PACKAGE_NAME>. add ignores load-profile flags: Test Manager resets the new load group to its defaults (20 virtual users). Set the profile afterwards with perf-scenario load-groups update --load-group-id <LOAD_GROUP_ID> --project-key <PROJECT_KEY> --virtual-users <N>, using the load-group id add returns. Omit --package-version (resolves the latest). Robot type defaults to standard, which needs a connected machine with Performance Testing runtimes; for a serverless folder pass --robot-type serverless to update with the profile.
3. perf-scenario execute --scenario-key <SCENARIO_KEY> --wait runs a dry run. It ignores the load profile (one virtual user), so don't ask about load values before it. A full run needs a passing dry run (list-dry-run-reports) and enough licence units (licenses get). Before the full run, show the load profile from get and have the user confirm or change it (load-groups update). The dry run's RecommendedMultiplexingFactor (--multiplexing-factor) is for machine robots only; leave it unset on serverless load groups.
4. perf-scenario execute --scenario-key <SCENARIO_KEY> --execution-type performanceTesting --wait, then load-groups list --execution-id <EXECUTION_ID> for each load group's result, and results get for the numbers. report generate --format pdf|html --report-file <FILE> only publishes a report you write from them (markdown for pdf, HTML for html) and returns ViewUrl.

• Which key each verb takes: get, delete, execute and list-dry-run-reports take only --scenario-key (the key, such as CLAIM:7441, already carries the project); passing --project-key to them fails with unknown option. create, list, stop and licenses get take --project-key; licenses get fails without one, though any project gives the same number.
• execute --wait exits 1 when the run is cancelled, its automation fails, or any SloViolationReasons is set, though the output still says Success: report the reasons, never re-run to "fix" it. Exit 4 = --timeout-sec (default 1800) passed and the run continues: read it with results get --execution-id <EXECUTION_ID>; a new execute starts another run. A full run longer than your shell limit: start it without --wait, give the user the ExecutionId, results get and stop --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY>.
• Perf-service reads take no --project-key (unknown option): results get, http-errors list, automation-errors list, transaction-metrics list. The last three need --start-time-ms 0 --end-time-ms <DURATION_MS> (Duration from executions list). transaction-metrics returns rows for API load groups only; [] elsewhere means no data, not zero latency. --full and results get carry per-second series; slim with --query and skip them for go/no-go summaries.
• Two different load-group ids. load-groups update / remove take the scenario's load-group id (from get or load-groups add). load-groups get, jobs list, robot-logs list, http-errors, automation-errors and transaction-metrics take the load group execution id from load-groups list --execution-id <EXECUTION_ID>. The wrong one returns 404 not_found.
• Find a scenario's key with perf-scenario list --project-key <PROJECT_KEY> --search <NAME> (rows under Data.Scenarios). Past runs: perf-scenario executions list --project-key <PROJECT_KEY> --scenario-id <SCENARIO_ID>, optionally --execution-type dryRun|performanceTesting (rows under Data.Data; responses capitalise ExecutionType). The scenario UUID is not in list or get. list-dry-run-reports --scenario-key <SCENARIO_KEY> returns ScenarioId only when a load group's test case has an AutomationId (Studio-linked; link-automation sets none); otherwise list without --scenario-id and match rows whose Name starts with the scenario name.
• report compare --scenario-id <SCENARIO_ID> --execution-ids <ID...> --report-file <HTML_FILE> publishes an HTML comparison you write from each run's results get (ids oldest to newest, one scenario) and returns ViewUrl; add --project-key for an in-app link.
• licenses get returns RemainingVirtualUserUnits for the whole tenant; it can lag up to 4 hours. A full run uses virtual users × 1 (API), 10 (Chrome/Edge) or 100 (other targets); dry runs use none. If units are short, stop and tell the user.
• Triage a failed load group with robot-logs list --load-group-id <ID> --level Error and jobs list --load-group-id <ID>. A 403 means the tenant's performance testing feature or the user's permission is off: stop under Rule 10.
• delete --scenario-key <SCENARIO_KEY> --yes removes the scenario and its load groups for good (Rule 5) and keeps past executions, unlinked. It does not stop a running execution; run stop first.

Critical Rules

1. Always check login first: run uip login status --output json before any Test Manager operation. If unauthenticated, run uip login.
2. Always pass --output json to every uip command, without exception.
3. Cap retries at 3 for any failing uip command. After three failures, stop and report the error; never use direct REST APIs.
4. An empty list stops the operation and informs the user rather than proceeding with a null key. Exception: empty tm testcases list --filter may be a prefix miss; use Rule 8's prefix fallback and stop only if it also finds nothing. Empty filtered project or customfield lookups are real empty results and stop normally.
5. Confirm before delete: confirm the target resource key unless the user already authorized that exact delete. Every delete requires --yes or -y; omission exits without deleting.
6. For a required folder key, use uip or folders list -n <folder-name> --all --output json when the user named the folder; when choosing one yourself, omit --all to list only member folders. Run /uipath-platform for folder-management details.
7. Discover before assuming: never guess automation names, folder keys, project IDs, or testcase keys; run the matching list first, such as uip tm testcases list-automations or uip or folders list -n <folder-name> --all.
8. Narrow named-entity list calls server-side: when given a name, key, label, or tag, inspect uip tm <resource> list --help or uip or <resource> list --help for its narrowing flag and use it. Never list all then filter client-side; this applies to every entity across uip tm and uip or, and to result filters too: a failed run's logs are executions testcaselogs list --only-failed, a case's failures are testcases list-result-history --only-failed. Exception: tm testcases list --filter is prefix matching. If a mid-name term returns zero, retry with a broader contextual prefix; relist without --filter only if no workable prefix exists, walking every page (Rule 11) before concluding absence.
9. Default-folder recovery: uip tm testcases run and uip tm testsets run require a project default folder. Attempt the run first. Only when failure text exactly includes "Message": "HTTP 400: Please assign folder to project level before executing testcases." and errorCode: itemNotFound, run uip tm project set-default-folder --project-key <PROJECT_KEY> --folder-key <FOLDER_KEY> --output json, then retry once. Get keys with uip or folders list -n <folder-name> --all --output json. Do not interpret other errors as missing folders: an unusable default gives opaque HTTP 5xx; a nonexistent folder key gives "HTTP 400: Internal Server Error." with errorCode: unknown. Both stop under Rule 10. Never overwrite a working default folder; an arbitrary folder may be rejected by Test Manager and break later runs. This is the only named run exception to Rule 10; all other run failures stop.
10. Any uip failure or ambiguity stops and asks the user: this includes command errors, malformed output, unclear flags/values, multiple matches, missing identifiers, or unexpected schemas. Never fall back to REST. Exceptions are expected outcomes identified exactly, plus one fixable mistake of your own: (a) the Rule 9 missing-folder error, handled there; (b) uip tm wait exit code 2 with Timed out after <N>s waiting for execution '<EXECUTION_ID>'. Last status: <status>., which means bounded timeout worked—report non-finish and continue remaining steps. Polling failed/interrupted/aborted ... and exit code 1 are real wait failures; (c) a requirement AI command exiting 2 with ErrorCode: timeout: the job is still running, so resume it with the --activity-id … --wait command its Instructions name, never a new start; (d) uip tm run --type package exit code 1 with "Code": "RunPackageTestsFailed" or "RunPackageCancelled" and "ErrorCode": "execution_failed", which means the run finished with failed or no tests, or was cancelled—report Data (counts, OutputPath, ExecutionUrl) and do not retry; (e) a ValidationError about a flag you passed (unknown option, missing required option): read <command> --help, fix the flags, and run it again once (counts toward Rule 3); a second usage error on the same command stops. Every other failure stops.
11. Walk the pages before concluding an item is absent: list responses carry only Data, with no total, cursor, or has-more flag. A page that returns exactly as many rows as --limit (default 50) may have more, so when the item you need is not on it, rerun the same list with --offset raised by the page size until a page comes back short. Page size is capped at 100: --limit above 100 fails with HTTP 400 … Page size cannot be greater than 100. For a list without --limit/--offset, such as tm testcases list, narrow with its filter flags instead (Rule 8).

Quick Start

1. Verify auth: run uip login status --output json; if unauthenticated, run uip login. If needed, set the tenant with uip login tenant set <TENANT_NAME> --output json. Run /uipath-platform for more authentication details.
2. Ask for the project name/key before any Test Manager call, except new work with no project named, which goes to the default project (see Default project); for multiple projects collect all names/keys in one prompt. Resolve each with uip tm project list --filter <NAME_OR_KEY> --output json. Zero matches stop and ask; multiple matches require presenting candidates and asking the user to choose. Reuse the confirmed PROJECT_KEY downstream.
3. Use as needed: uip tm testsets list --project-key <PROJECT_KEY> --filter <TEST_SET_NAME_OR_KEY> --output json; uip tm testsets list-testcases --project-key <PROJECT_KEY> --test-set-key <TEST_SET_KEY> --output json; uip tm executions list --project-key <PROJECT_KEY> --test-set-id <TEST_SET_ID> --limit 100 --output json; uip tm executions testcaselogs list --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY> --output json (triaging a red run: add --only-failed so only the failed logs come back, then testcases list-result-history --test-case-id <TEST_CASE_ID> --only-failed to tell a regression from a flake — references/failure-triage-guide.md); uip tm testcaselog list-assertions --project-key <PROJECT_KEY> --test-case-log-id <TEST_CASE_LOG_ID> --output json; uip tm teststeplog list --project-key <PROJECT_KEY> --test-case-log-id <TEST_CASE_LOG_ID> --output json.

Troubleshooting

For 401 Unauthorized on a REST API, run uip login to re-authenticate. For an unexpected command failure, first verify syntax with uip tm <command> --help, then authentication with uip login status --output json; Critical Rule 10 still governs whether to proceed.

Navigate to a Workflow

• Read, correct (override), assign, or manually record a test case log, and Result vs OriginalResult: references/testcaselog-guide.md
• Back up, copy or move a project, in one tenant or across tenants and environments (uip tm project export → import): references/project-migration-guide.md
• Execution lifecycle (manual open/record/finish), filtered reads, cancel, delete, xlsx export, and reporting date (uip tm executions): references/executions-guide.md
• Failed-run root cause, assertions, step logs, evidence, and flaky-versus-regression analysis: references/failure-triage-guide.md
• Raise a defect from a failed result, trace it to its test case/requirements, link it to a tracker issue (uip tm defects): references/defects-guide.md
• AI on a requirement: propose and create test cases, evaluate the requirement, find and unlink or delete obsolete test cases (uip tm requirements generate-testcases, evaluate, find-obsolete-testcases): references/requirement-ai-guide.md
• Shareable tester or release-manager report: references/test-result-report-guide.md
• Publish a project and link it to a Test Manager testcase (Studio/RPA): references/publish-and-link-guide.md
• Pack, ingest, label, and run Playwright on serverless: references/playwright-first-mile-guide.md
• Run a test set on a cadence, cron shapes, and single-vs-bulk batch semantics (uip tm schedules): references/schedules-guide.md
• Custom-field definitions, labels, and values (uip tm customfield): references/custom-fields-guide.md
• Object labels / tag metadata on test entities (uip tm objectlabel): references/object-labels-guide.md
• Project time zone, execution name format, and what is read-only (uip tm project settings): references/project-settings-guide.md

Anti-patterns

• Do not proceed if authentication fails: all Test Manager API calls require a valid bearer token; fail fast rather than causing later 401s.
• Do not guess command names: verb-noun composites are required; bare verbs do not exist. Confirm with uip tm <resource> --help --output json.
• Do not hand-build a package run: to run all tests of an uploaded package, use uip tm run --type package, not link-package → testsets create → testcases add → testsets run → wait → result download.
• Do not run project get-default to see which project is the default: it creates one, open to the tenant's Everyone group, when the tenant has none. Read the first project list row instead.
• Do not link-automation Playwright test cases: ingestion links them automatically; manual linking is only for the Studio/RPA pipeline.