uipath-test

UiPath Test Assistant

管理 UiPath Test Manager 项目、需求（包括 AI 测试用例生成、需求评估和过时测试用例搜索）、测试用例、测试集、执行、日志、缺陷、附件、结果、自定义字段、性能（负载）测试场景、标签，以及可按角色定制并分享的测试报告。

适用场景

Test Manager 的增删改查；对上传包中的每项测试进行 CI 运行；执行分析、覆盖率、回归趋势、失败率、是否继续的摘要；失败运行的分类处理；不稳定测试与回归测试分析；失败证据；对自动化测试用例进行负载测试并查明负载运行失败的原因；以及可分享给 QA 工程师、开发者或发布经理的报告。

概念和 CLI

需求定义必须测试的内容；测试用例定义场景，并且可能包含 teststeps；测试集用于对测试用例分组；运行测试集或测试用例时会创建执行。测试用例日志记录执行中的测试用例，并提供导航；测试步骤日志记录各步骤；测试用例日志断言是断言步骤。Test Manager 的 AI 会根据需求的说明和附件开展工作：提出测试用例、建议改进需求，或标记看起来已过时的关联测试用例。每项任务都会作为后台作业运行，并带有一个活动 ID。缺陷是从一条测试用例日志中提出的 Bug，并同步到项目的缺陷跟踪工具（Jira、Azure DevOps、……）。

性能场景用于对自动化测试用例进行负载测试。场景包含 负载组：一个测试用例、运行该用例所用的 Orchestrator 包和文件夹，以及一个负载配置文件（虚拟用户数、升压时间、峰值、降压时间）。运行场景会创建一次执行；干运行用于检查场景能否正常运行，性能运行则施加完整负载，并使用租户的性能测试许可证。

外部 Playwright 包是打包并上传到 Orchestrator 的测试套件。导入时会自动为每项 Playwright 测试创建一个测试用例，无需链接步骤，并为每项测试添加 PW_Tag_*、PW_Project_*、PW_Suite_* 和 PW_File_* 标签。它们在无服务器云运行时上运行；请参阅 references/playwright-first-mile-guide.md。

使用 uip tm；通过 uip tm --help 和 uip tm <command> <subcommand> --help 查看语法。务必为每条 uip 命令传入 --output json；以下所有命令都必须带上它。 当值来自文件时，将其作为 "$(cat <FILE>)" 传入；切勿根据所读内容重新输入。

命令

项目、文件夹和需求

• 项目：uip tm project list --filter <NAME_OR_KEY> 按名称/键查找；project create --name <PROJECT_NAME> --project-key <PROJECT_KEY> 创建项目；project update --project-key <PROJECT_KEY> --name <PROJECT_NAME> 更新名称/说明；project delete --project-key <PROJECT_KEY> 删除项目；project set-default-folder --project-key <PROJECT_KEY> --folder-key <FOLDER_KEY> 设置默认 Orchestrator 文件夹；project clear-default-folder --project-key <PROJECT_KEY> 清除默认文件夹；project owners list --project-key <PROJECT_KEY> [<PROJECT_KEY> ...] 列出所有者。
• 默认项目：每个租户有一个，用于没有所属项目的运行（CI）。project list、create 和 update 的行中都包含 IsDefault。
  • 要查找哪个项目是默认项目，请运行 uip tm project list --limit 1 --output json，不要带 --filter。Test Manager 会将默认项目列在首位，因此仅当 Data[0].IsDefault 为 true 时，它才是默认项目。否则，此登录看不到默认项目：租户尚未创建默认项目，或者该项目无法由此登录打开（列表会省略调用者无法打开的项目）。请将此情况报告为“看不到默认项目”，而不是“租户没有默认项目”。
  • uip tm project get-default --output json 会返回默认项目，并且在不存在默认项目时创建一个：Default Project（键为 TMDP），并向租户的 Everyone 组开放。仅当用户需要一个项目开展工作时才运行；切勿只为查看而运行。
  • 未指定项目的新工作会进入默认项目。 当用户要求创建测试用例、测试集或需求，或运行软件包，但未指定项目时，运行 get-default，使用其 ProjectKey，并告知用户该工作已进入该项目（名称和键）。仅限新工作：若要读取、更改或删除现有项目项，请询问项目（快速入门第 2 步）。
  • uip tm project update --project-key <PROJECT_KEY> --set-default --output json 可将现有项目设为默认项目（需要 TM.Administration 权限，或租户管理员身份）。谁可以打开该项目不会改变，因此无法访问该项目的调用方随后会从 get-default 收到 permission_denied。没有 project create --set-default 命令。
  • 任一命令返回 permission_denied：报告其 Message 和 Instructions 并停止（规则 10）。
• 权限：uip tm project-permissions get 返回 Data.Permissions（调用方在该项目上拥有的权限名称）和 Data.Count。该命令受 Project.Read 权限控制，因此成功的 get 始终至少包含 Project.Read（Count >= 1）；没有读取权限会失败并返回 403（或对于无法查看的项目返回 404），绝不会成功但返回空数组。仅开放 get。
• 项目设置：uip tm project settings get --project-key <PROJECT_KEY> 可读取时区、执行名称格式、步骤上限、默认文件夹和治理设置；project settings update --project-key <PROJECT_KEY> [--time-zone <IANA_NAME>] [--execution-name-format <TEMPLATE>] 仅写入前两项。IANA 名称、占位符、只读字段和部分更新：项目设置指南。
• 使用 uip or folders list -n <name> --all --output json 获取文件夹键；它会返回当前用户可见的所有文件夹。
• 命令前缀为 uip tm requirements：list --project-key <PROJECT_KEY> 可选 --test-case-id <UUID>（测试用例涵盖的需求——使用此选项，绝不要逐个需求扫描 list-testcase-ids）、--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>)（UUID 和键互斥）；create --project-key <PROJECT_KEY> --name <name>；update --project-key <PROJECT_KEY> --requirement-id <uuid>（更新名称/描述，且至少需要 --name 或 --description 之一）；delete --project-key <PROJECT_KEY> --requirement-ids <uuid...>（可变参数 ID）；export --project-key <PROJECT_KEY> --output-file <path>（导出 .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...>)（添加/移除选择器互斥）。
• 使用 uip tm project export → uip tm project import（.tmh 软件包）迁移或备份整个项目：项目迁移指南。使用 uip tm migration get|list|download 读取作业；使用 uip tm migration schemas list|download 获取软件包架构。
  • 两者都是耗时数分钟的作业。传入 --wait（导出时还要传入 --output-file）；不传时会返回作业 ID，以供 migration get 使用。切勿为了查看进度而启动第二次导出或导入。
  • 默认会包含自动化（--exclude automation 会将其排除）；治理设置、项目配置（仅限 Test Cloud，否则返回 403）和提示词仅在传入 --include 时包含。
  • 测试集只能以 .tmh 格式迁移；测试用例和需求也可以导出到 Excel（testcases export、requirements export）。用户只说“导出这些”但未说明格式或用途时，请询问。
  • 导入前请询问：导入到现有项目，还是新建项目（--create-project）？若项目键已被占用，请询问是否使用 --new-project-key。

需求 AI

uip tm requirements generate-testcases、uip tm requirements evaluate 和 uip tm requirements find-obsolete-testcases 都会运行后台 AI 任务，并返回一个 ActivityId。**每次启动都会消耗 AI 单位：只启动一次，然后重复使用 --activity-id <ACTIVITY_ID> 来等待、查看、创建、取消关联或删除；切勿为了重试而再次启动。**使用 --timeout 540 限制等待时间，并将 shell 时限设为 600 s。场景、字段含义（Score、ConfidenceLevel）和结果规则：references/requirement-ai-guide.md。

提示词库

uip tm prompts list|get|create 用于管理项目中可重复使用的 AI 指引。ModeOfUse（create 使用 --mode-of-use，list 使用 --modes-of-use）是提供该提示词的 Autopilot 功能；如果用户未指定，请先询问。

• CLI 中没有 update 或 delete，且名称不唯一。执行 create 前，先运行 get --name <NAME>（精确匹配且区分大小写）；ErrorCode: not_found 表示不存在，不属于规则 10 的停止条件。若找到，则不要再次创建；请告知用户，并说明需要通过 Test Manager UI 修改。若有多个匹配项，get 会失败；请使用 list 中的 --prompt-id。
• list 会混合显示内置示例（PromptType: Internal）和团队提示词（UserDefined）；--filter 按名称或描述的前缀匹配。
• 指引为必填项，最长 4096 个字符：使用 --guidelines，或使用 --guidelines-file 提供多行文本。超出限制时，会在发送任何内容之前失败。
• requirements generate-testcases、evaluate 和 find-obsolete-testcases 不接受提示词 ID：要应用提示词库中的提示词，请将其 Guidelines 作为 --instructions 传入。
• 要导出提示词，请运行 uip tm project export --include prompts；默认导出不会包含提示词。

测试用例

• uip tm testcases create --project-key <PROJECT_KEY> --name <TEST_CASE_NAME>；list --project-key <PROJECT_KEY> 可选使用 --filter <text>，按名称或键进行前缀匹配，而非子字符串匹配；update --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> --name <TEST_CASE_NAME> 可更新名称、描述、前置条件或后置条件，且至少需要一个字段；delete --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_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> 可关联 Orchestrator 包自动化；可选使用 --entry-point-id <PACKAGE_ENTRY_POINT_ID>（来自 list-automations）按 ID 绑定，该选项会覆盖 --test-name；unlink-automation --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> 可取消关联；list-automations --project-key <PROJECT_KEY> --folder-key <FOLDER_KEY> 可列出文件夹测试入口，可选使用 --package-name <PACKAGE_NAME>，每行都包含 PackageEntryPointId；list-testsets --project-key <PROJECT_KEY> --test-case-key <TEST_CASE_KEY> 可列出包含该测试用例的测试集。
• 使用 uip tm testcases 查找、盘点、复制和批量创建测试用例（通过 --help 查看标志）：
  • get --test-case-key 会补充 list 行中缺少的信息：前置条件、后置条件、Created、PackageEntryPointId。get --automation-id <PACKAGE_ENTRY_POINT_ID> 会返回关联某个自动化的一个测试用例；多个测试用例可能共用该自动化，因此要查找全部测试用例，请使用 list 并匹配 PackageEntryPointId。list-requirements --test-case-key 可列出覆盖该测试用例的需求。list-packages / list-studio-projects 可列出自动化测试用例所用的不同包名 / Studio 项目名（--filter 按前缀匹配）。
  • 要查询“哪些测试集包含标记为 X 的测试用例”，只需调用一次 list-testsets --labels X，不要逐个测试用例循环查询。它只显示显式分配，不包括通过动态标签纳入测试用例的测试集；请明确说明这一点。
  • clone 返回 Accepted，不带键，并在后台复制，步骤最后复制。使用 Instructions 中的 list --filter 查找副本。切勿为检查或重试而再次克隆；遇到 5xx 后先执行 list，因为副本可能已经存在。只有使用 --include 时才会复制标签、文档、需求和参数。
  • bulk-create --file 接受一个 JSON 数组，格式为 {"name", "labels": [...], "steps": [{"description", "expectedResult"}]}。名称不唯一，因此重新运行会产生重复项。名称可能已存在时，请传入 --skip-existing。文件错误（退出码 3）不会创建任何内容。如果后续批次失败，之前的批次仍会保留：请报告情况，并在重新运行前征求确认。KeysResolved: false 仍表示已创建。
  • list --automated 不包含关联了 Playwright 的测试用例。group-by 遇到 403（许可证或功能未启用）时，请停止并告知用户。
• 步骤：uip tm testcases steps list --project-key <PROJECT_KEY> --test-case-id <TEST_CASE_ID> 使用 --test-case-id <UUID>（而非 --test-case-key）列出手动步骤。steps get --project-key <PROJECT_KEY> --step-id <UUID> 可获取步骤；steps add --project-key <PROJECT_KEY> --test-case-id <UUID> --description <text> 可添加标志模式步骤（必须提供 --description）；或者使用 steps add --project-key <PROJECT_KEY> --test-case-id <UUID> --step '<json>' [--step '<json>' ...] 添加多个 JSON 步骤（与标志模式互斥，且不具备原子性：后续步骤失败时，之前的步骤仍会保留）；steps update --project-key <PROJECT_KEY> --step-id <UUID> 只更新已传入的字段；steps move --project-key <PROJECT_KEY> --step-id <UUID> --target-position <n> 将步骤移至从 0 开始的位置；steps delete --project-key <PROJECT_KEY> --step-id <UUID> --yes 删除步骤。
• list-result-history --project-key <PROJECT_KEY> --test-case-id <TEST_CASE_ID> 可列出历史记录，可选使用 --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> 可为一个或多个以空格分隔的测试用例 UUID 启动执行；可选使用 --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> …) 可按显式键，或按带有至少一个指定标签的所有测试用例添加成员；两种选择器互斥，且接受以空格分隔的多个值。键也接受逗号形式（DEMO:1,DEMO:2），标签不接受（--labels A,B 会被视为一个标签）。标签匹配为 OR、精确匹配且不区分大小写；包含空格的标签请加引号。不使用 --dynamic 时，--labels 会将当前匹配项一次性复制到测试集中；之后添加相应标签的测试用例不会被纳入。uip tm testcases remove --test-set-key <TEST_SET_KEY> --test-case-keys <KEY1,KEY2,...> 可移除以逗号分隔的静态关联；若测试用例仅通过动态标签纳入，则命令虽会成功，但不会执行任何操作——请改为修改该测试用例的标签或测试集的动态标签。
• 动态分配测试用例（成员资格随标签变化）：uip tm testcases add --test-set-key <TEST_SET_KEY> --labels <Label1> <Label2> … --dynamic 会将标签存储在测试集上；带有其中至少一个标签的所有测试用例（OR、精确匹配且不区分大小写）都会成为该测试集的成员，并纳入每次运行，包括之后才添加标签的测试用例。此操作会与已有标签合并（最多 30 个），保留静态关联，并返回 DynamicLabels 和 MatchedTestCases；使用 --dynamic 时不支持 --limit 和 --test-case-keys。uip tm testcases remove --test-set-key <TEST_SET_KEY> --dynamic [--labels <Label1> …] --yes 可移除指定标签；省略 --labels 时会移除全部标签（Result 为 Removed、Cleared 或 NotSet）。不能对关联了外部来源的测试集使用此操作。需要测试套件持续跟踪标签时（例如 CI 中“所有标记为 smoke 的测试用例”），请使用 --dynamic；需要固定快照时则不使用。如果 uip tm testcases add --help 未列出 --dynamic，说明 CLI 版本较旧：请使用不带该选项的 --labels，并在标签变更后重新运行。
• 参数（uip tm testcases parameters，仅适用于测试用例）：值标志是 --default-value，不是 --value。
  • 每个测试用例中的名称都必须唯一，按忽略大小写的精确匹配查找，绝不进行模糊匹配（User name ≠ Username）。使用 list --search 并检查精确的 Name 以确认是否存在；结果为空表示不存在，不属于 Rule 4/10 的停止条件。使用 get --parameter-name <NAME> 读取一个值；返回 not_found 也表示不存在。遇到相近名称时，请询问用户是否确认使用最接近的名称。
  • 即使请求提供了不同的值，也绝不能通过“add”请求修改已有参数：绝不对已有参数运行 update。单个添加：说明参数已存在，并询问其他名称。向多个测试用例添加参数：跳过已有参数，保留其值，并将其列为已跳过。修改不存在的名称：创建前请先询问。重命名为已被占用的名称会被拒绝；请报告此情况。删除前请确认（Rule 5）。
  • delete 即使未删除任何内容，也会返回 Success；请报告 Data.Passed / Data.Failed。向多个测试用例添加参数时：逐个执行 list，仅对缺少的名称执行 add，然后按测试用例汇总已添加和已跳过的参数。
• run、steps list、steps add、list-result-history 和 testcaselog start / finish 使用 --test-case-id <UUID>；通过 uip tm testcases list --output json 获取该值（Id），或者——在将结果记录到刚打开的运行中时——从该运行自身的日志获取（一次调用即可取得所有 ID，参见 Execution lifecycle）。update、delete、link-automation、unlink-automation 和 list-testsets 使用单数形式的 --test-case-key <PROJECT_KEY:NUMBER>。测试集批量成员操作使用逗号分隔的 --test-case-keys <KEY1,KEY2,...>。除 list 和 add 外，所有 steps 命令都使用 --step-id <UUID>；通过 steps list 获取该值（Id）。

测试集和执行

• uip tm testsets create --project-key <PROJECT_KEY> --name <TEST_SET_NAME>，可选添加 --dynamic-labels <Label1> …，按这些标签动态分配测试用例来创建测试集（返回 DynamicLabels、MatchedTestCases）；list --project-key <PROJECT_KEY> 可选添加 --filter <text>、--folder-key、--include-last-execution；update --test-set-key <TEST_SET_KEY> --name <TEST_SET_NAME> 更新名称/描述；delete --test-set-key <TEST_SET_KEY>；list-testcases --project-key <PROJECT_KEY> --test-set-key <TEST_SET_KEY> 列出一次运行会执行的用例——包括静态关联和匹配动态标签的用例，AssignmentType 为 Static、Dynamic 或 Both；get-dynamic-assignment --project-key <PROJECT_KEY> --test-set-key <TEST_SET_KEY> 返回其 DynamicLabels（没有时为 []）和 MatchedTestCases。
• uip tm testsets run --test-set-key <TEST_SET_KEY> 运行测试集并返回执行 ID；可选添加 --execution-type <automated|manual|mixed|none>（默认值为 automated）、--input-path <FILE>；对于 Playwright，还可添加 --playwright-project <name>。uip tm testsets playwright-context --test-set-key <TEST_SET_KEY> 可探测状态，并返回 IsPlaywright、可用项目和选定项目。
• 键的格式为 PROJECT_KEY:NUMBER。使用 uip tm testcases add/uip tm testcases remove 添加/移除成员——静态方式或使用 --dynamic，不要使用 testsets 子命令。对于 Playwright 测试集，--playwright-project <name> 接受一个区分大小写的 playwright.config 名称——每次执行最多指定一个项目，并会保存此选择。所有测试用例必须来自同一个 Playwright 包；名称未知时会立即失败，并列出有效名称。先用 playwright-context 探测，并根据 IsPlaywright 分支处理。这两项功能都需要 Test Manager 的 Playwright 支持，以及包含外部包命令的 CLI。请参阅 references/playwright-first-mile-guide.md，其中首先介绍可用性检查及缺少支持时的处理方式。
• 使用 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 会等待并返回副本的 TestSetKey；--no-wait 会返回不带键的 Accepted。超时表示失败：停止操作，绝不要再次克隆。名称可以重复，因此请为副本指定一个其他测试集没有的名称。不会复制文件夹、Robot、包、强制执行标记和顺序。
  • set-execution-order 必须列出所有已分配的用例（先读取 list-testcases；该命令不会显示顺序）。只有在 settings set --enforce-execution-order 后，运行才会遵循此顺序。
  • 在 settings 中，只有强制执行标记可写入；遇到失败时停止、覆盖率、视频、远程控制和 Autopilot 均为只读——请说明这一点。
  • 名称选项（--folder-path、--robot-name、--assignee-email）会在 Orchestrator 中解析。若在 Orchestrator 中，或在 set-execution-target/group-by 中遇到 403（许可证或功能未启用），请停止并告知用户。autoselect-packages 不会保存任何内容。
• uip tm executions list --project-key <PROJECT_KEY> 列出前 n 条记录，可选添加 --test-set-id <UUID>、--filter <text>、--status、--execution-type、--execution-finished-interval、--limit、--offset；适用于常见的单测试集或单项目查询。list-filtered --project-key <PROJECT_KEY> 接受 --test-set-id、--status、--execution-type、--execution-finished-interval、--limit、--offset，并额外接受 --updated-by、--labels、--test-execution-ids、--sort-by；它没有 --filter——此处的名称搜索选项是 --search。需要按标签筛选、查询多个执行 ID、自定义排序或使用 --updated-by 时，请使用此命令。两者使用相同的枚举值，必须为小写，否则会被拒绝：--status <pending|running|cancelling|finished|cancelled>、--execution-type <manual|automated|none|mixed|autonomous>、--execution-finished-interval <lastHour|lastDay|lastWeek|last15Days|last30Days>。响应中的 Status 首字母大写（Running、Finished）；不要将响应值用作筛选值。
• get-stats --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY> 汇总一次运行的通过/失败/无结果总数（report get 也会汇总已完成的运行）。每条 executions list/list-filtered 记录都已包含该运行的 Passed/Failed/None，且与 get-stats 的结果相同，因此一次列表调用就能获取某测试集所有运行的总数；run --execution-id <EXECUTION_ID> --execution-type <TYPE> 重新运行，可选添加 --test-case-log-ids <UUID...>（以空格分隔）和 --async；retry --execution-id <EXECUTION_ID> 仅重试失败的用例，可选添加 --project-key、--test-set-key、--execution-type；testcaselogs list --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY> 列出用例日志（可选添加 --only-failed、--filter、--limit、--offset），它是嵌套子命令，不是顶层 executions 子命令。对于测试用例 UUID，请使用 uip tm testcases run；对于测试集键，请使用 uip tm testsets run；对于重新运行某次执行，请使用 uip tm executions run。

执行生命周期

使用 uip tm testsets run --test-set-key <KEY> --execution-type manual 开始一次手动运行（id = Data.ExecutionId；没有 executions create 这个动词），然后通过 uip tm executions testcaselogs list --execution-id <ID> 从该运行自身的日志中解析每个 --test-case-id，再使用 testcaselog start/finish 记录每个用例。手动运行会在最后一条日志完成时自动关闭——executions finish 用于强制关闭仍有未完成日志的运行，并非正常的最后一步。set-reporting-date 需要运行已关闭（ExecutionFinished，而非 Status）。手动与自动运行的区别、筛选读取，以及每个 cancel/delete/finish/export/set-reporting-date 的注意事项和退出码约定，详见 references/executions-guide.md；使用 -h 查看标志和枚举值。

测试集计划

• 动词（使用 --help 查看标志）：uip tm schedules create|update|list|next-runs|enable|disable|delete。list 是唯一的读取操作——没有按 id 查询的命令——因此在执行 update 前先从中找回所需值；update 会替换整个定义（传入所有希望保留的标志；无法更改启用状态，请使用 enable/disable）。delete 和 --all 需要 --yes。
• --cron 需要 6 或 7 个字段，且从秒开始，并非 Unix cron（每天 02:00 为 0 0 2 1/1 * ? *；CLI 会在客户端拒绝五字段表达式）。每种重复类型都必须提供 --cron-details（重复规则 JSON）。--start-time/--disable-time 是按 --timezone 解读的本地时间 YYYY-MM-DDTHH:mm——秒或 Z 都会被拒绝。将 list 输出的 id 传给 next-runs——底层端点使用不同的 GUID 作为键，id 错误时会返回 200 和空列表。Cron/重复规则及注意事项详见：references/schedules-guide.md。

运行已上传的包（CI）

uip tm run --type package --package-name <PACKAGE_NAME> --package-version <VERSION> --folder-path <FOLDER_PATH> --project-key <PROJECT_KEY> --output json 会运行已上传到 Orchestrator 的包中的所有测试，使用 --max-retries <N> 重新运行失败项，并生成报告。先使用 uip rpa pack / uip or packages upload 打包并上传。

• 如果未指定项目：运行 uip tm project get-default --output json，并将其 ProjectKey 作为 --project-key 传入（参见默认项目）。
• 使用 uip or packages versions <PACKAGE_NAME> --folder-path <FOLDER_PATH> --output json 获取 <VERSION>。应用版本（1.0）会运行最新的 1.0.x 补丁版本；精确版本必须是最新补丁版本，较旧版本会以退出码 3 退出且不会创建任何内容。
• 在 CI 步骤的时限内，传入低于该时限的 --timeout <SECONDS>（默认值为 7200）：如果步骤先被终止，则不会生成报告。
• 退出码为 1 且错误为 RunPackageTestsFailed 或 RunPackageCancelled 时，表示测试结果：报告该结果，参见规则 10(d)。退出码 4 表示超时：执行可能仍在运行，且 Data.OutputPath 中会保存部分报告，其中未完成的测试会标记为跳过。报告超时；切勿将跳过的测试计为通过。其他所有非零退出码都会导致停止（规则 10）。
• 没有任何测试声明的 --input-path 名称会列在 Data.IgnoredInputs 中；请告知用户（通常是拼写错误）。

日志、报告、附件和结果

• uip tm testcaselog start --project-key <PROJECT_KEY> --execution-id <EXECUTION_ID> --test-case-id <TEST_CASE_ID> 启动，可选 --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> 结束并记录结果（--result、--has-error、--executed-by 三项均为必填）——手动运行的用例会被标记为 Failed。--executed-by 接受电子邮件地址，但只会验证其非空，随后便会丢弃——存储的 ExecutedBy 是经过身份验证的调用者，因此绝不要告诉用户结果归因于他们指定的人。可选参数：--detail-link <URL>、--run-id、--is-post-condition-met、--step-logs <json> 或 --step-logs-file <path>。start 需要已有执行记录——不存在 executions create；使用 uip tm testcases run … --execution-type manual 或 testsets run … --execution-type manual 来创建执行记录。
• 在结束时记录手动步骤结果：start 会返回测试用例日志的 Id，并为每个步骤创建一个步骤日志；uip tm teststeplog list --project-key <PROJECT_KEY> --test-case-log-id <TEST_CASE_LOG_ID> --output json 会为每个步骤返回一个步骤日志；将每条日志按如下格式传回：{"id":"<STEP_LOG_ID>","testCaseLogId":"<TEST_CASE_LOG_ID>","result":"Passed","comment":"<text>","hasError":false}。条目按步骤日志的 id（而非 testStepId）匹配；未知 ID 会被静默忽略，且只有 result、comment、hasError、hasAttachment 会持久化。
• 读取日志：testcaselog list（筛选条件为 --results/--statuses/--labels/--search/--assignees；没有日期/执行记录筛选条件——使用 executions testcaselogs list 缩小到某次运行）；get --test-case-log-id <ID>（--include-assertions）；latest --test-case-ids <ID...>（每个用例返回最新记录）。**仅当 Result 和 OriginalResult 均有值且不同时，结果才会被覆盖——OriginalResult 为空表示未覆盖。**使用 override create|update|delete|get 更正已确定的结果（create 需要 --result 和 --reason）。使用 assign --assignee-email <EMAIL>（CLI 会解析该地址）或 --assignee-id <IDP_UUID>（UUID）分配失败项。cancel --test-case-log-id <ID> --yes 会停止一个自动化用例的 Orchestrator 作业；即使是手动或已完成的日志，它也会返回 CancelRequested，但会忽略取消请求，因此请使用 get 确认（状态为 Cancelling）。取消整个运行：executions cancel。完整命令说明及注意事项：references/testcaselog-guide.md。
• uip tm testcaselog list-assertions --project-key <PROJECT_KEY> --test-case-log-id <TEST_CASE_LOG_ID> 列出断言；render-assertions 将其以 Markdown 格式返回；get-robot-logs 返回一个会过期的链接（或使用 --output-file 下载）；uip tm teststeplog list --project-key <PROJECT_KEY> --test-case-id <TEST_CASE_LOG_ID> 列出步骤日志。
• uip tm report get --execution-id <EXECUTION_ID> (--project-key <KEY> | --test-set-key <KEY>) 汇总已完成的执行（TotalTests/Passed/Failed/None、PassRate 为通过数除以通过数与失败数之和，因此未运行的 None 测试不会降低该比率，以及 FailedTests）；必须且只能提供一个用于标识项目的选项。只传入 --execution-id 会退出并提示 Provide --project-key or --test-set-key。
• uip tm attachment download --execution-id <EXECUTION_ID> 下载测试用例附件；attachment upload --object-id <UUID> --object-type <type> --file <path> 将附件上传到 Test Manager 对象，例如 --object-type testCaseLog；uip tm result download --execution-id <EXECUTION_ID> 下载 JUnit XML，可选参数为 --project-key、--test-set-key、--result-path <DIR>。
• 单个文件（uip tm attachment，upload 会返回 AttachmentId）：先查找对象（list --test-case-keys / --requirement-keys），按 FileName 选择文件，然后使用其 AttachmentId；没有匹配项或文件名重复时，请询问用户。已有 ID（来自 upload 或导出作业）：get --attachment-id <ID> --object-type <TYPE> 可读取其元数据。
  • list 仅显示 userBased 文件，除非传入 --source（robot 或 Studio 证据：orchestrator、studio、taskCapture）。无法解析的键会与其余结果一起显示在 Unresolved 下——请指出这些键。未知的 --object-ids ID 也会显示 AttachmentCount: 0。
  • --object-type 指的是父对象的类型，而非文件类型；即使类型错误，也可能成功。
  • download --attachment-id 会使用服务器上的文件名将文件写入当前文件夹，除非指定 --result-path/--output-file；且绝不会替换现有文件：如果提示 already exists，请停止并询问用户；仅当用户提出要求时才传入 --overwrite。
  • update 仅可重命名（--file-name）。每次调用时，--all 只返回一页；请根据 Pagination 继续获取后续页面。delete --attachment-id <ID> --object-type <TYPE> --yes：先确认（规则 5）。
• 导出文件：uip tm testcases export（将测试用例导出为 .xlsx；使用 --test-case-ids，否则导出整个项目）以及 uip tm report export（导出执行报告，使用 --execution-id --format excel|pdf|junit；或将所选结果导出为 PDF，使用 --test-case-log-ids，两个或更多结果会打包为一个 .zip）：
  • 用户需要文件时，传入 --wait --output-file <path>。不传 --wait 时只会启动作业：当状态为 Initiated/InProgress 时轮询 uip tm export-jobs get --job-id，状态为 Failed/Cancelled 时停止，然后按照 Instructions 中的说明执行 attachment download --attachment-id <AttachmentId>。切勿为了查看进度而重复启动同一个导出作业。
  • 如果 --output-file 指定的文件已存在，则会在启动任何操作前拒绝执行：请询问用户，并且仅在用户明确要求时传入 --overwrite。
  • export-jobs get 需要使用启动该作业的项目（其他项目会返回 404）。如果租户未启用 JUnit（feature is not enabled），或下载结果 PDF 时遇到 403（许可证限制），请报告问题，不要重试。

Playwright 打包

uip tm pack --project-path <dir> --type playwright --project-key <PROJECT_KEY> --name <PackageName> --package-version <ver> -o <out-dir> 会将 Playwright 测试套件打包为 .nupkg；需要锁文件和 @playwright/test。--package-version 使用 NuGet/SemVer 格式，包含三段或四段数字，并可带可选的预发布/构建后缀（1.0.0、1.0.0.0、1.0.1-beta.1）；1.0 和非数字值会被拒绝。--project-key 指定用于自动导入测试用例的 Test Manager 项目；--no-create-test-cases 会跳过此步骤；--dry-run 可预览。使用 uip or packages upload <nupkg> 上传。打包可离线进行，无需身份验证。上传 → 导入 → 填充标签 → 运行的流程见 references/playwright-first-mile-guide.md。

缺陷

uip tm defects create | list | get | update | delete | get-external-issue | get-related | attachments list|download — 根据失败结果提交缺陷、更改其状态/优先级/跟踪器链接，并追踪缺陷。缺陷仅使用 UUID：通过 executions testcaselogs list 中结果的 DefectId 查找缺陷。在调用任何 defects 命令前，请阅读 references/defects-guide.md：update 和 delete 通常需要 10–40 秒，且 shell 时间限制至少需要设为 120 秒。

等待和用户

uip tm wait --execution-id <EXECUTION_ID> 等待执行进入终止状态；可选参数包括 --project-key、--test-set-key、--timeout <SECONDS>。uip tm user get 获取已通过身份验证的用户资料。

自定义字段

项目范围的自定义字段定义（关联到 Requirement/TestCase/TestSet），以及每个对象的 label 和 value 行，通过 uip tm customfield … 管理。完整命令说明 — 作用范围、--object-type/--data-type 枚举值（区分大小写：Requirement|TestCase|TestSet、Text|Label）、--values 的 JSON 语义，以及所有 label/value 操作：见 references/custom-fields-guide.md。

对象标签

通过 uip tm objectlabel … 为 Requirement、TestCase、TestSet、TestExecution 或 TestCaseLog 添加标签元数据。反模式（标签 ID 与对象 ID 混淆；--remove-other-labels 删除隐藏的内部标签）：见 references/object-labels-guide.md。

性能（负载）测试

典型请求：“结账能否处理 50 个用户？”

1. 查找自动化测试用例（testcases list）、其文件夹和程序包（testcases list-automations）。IsAutomated: false 但带有 PackageName 时仍表示已关联（旧版关联）：使用该程序包，绝不要告诉用户它没有自动化。
2. 执行 uip tm perf-scenario create --project-key <PROJECT_KEY> --name <NAME>，然后执行 perf-scenario load-groups add --scenario-key <SCENARIO_KEY> --test-case-key <TEST_CASE_KEY> --folder-key <FOLDER_KEY> --package-name <PACKAGE_NAME>。add 会忽略负载配置文件标志：Test Manager 会将新负载组重置为默认值（20 个虚拟用户）。之后使用 perf-scenario load-groups update --load-group-id <LOAD_GROUP_ID> --project-key <PROJECT_KEY> --virtual-users <N> 设置配置文件，并使用 add 返回的负载组 ID。省略 --package-version（将解析最新版本）。Robot 类型默认为 standard，需要连接的、装有 Performance Testing 运行时的计算机；对于无服务器文件夹，请在 update 设置配置文件时传入 --robot-type serverless。
3. perf-scenario execute --scenario-key <SCENARIO_KEY> --wait 会运行试运行。它会忽略负载配置文件（使用一个虚拟用户），因此运行前不要询问负载值。完整运行需要试运行通过（list-dry-run-reports），并且有足够的许可证单位（licenses get）。完整运行前，通过 get 显示负载配置文件，并让用户确认或更改（load-groups update）。试运行的 RecommendedMultiplexingFactor（--multiplexing-factor）仅适用于机器 Robot；无服务器负载组不要设置该值。
4. 执行 perf-scenario execute --scenario-key <SCENARIO_KEY> --execution-type performanceTesting --wait，然后对每个负载组的结果执行 load-groups list --execution-id <EXECUTION_ID>，并执行 results get 获取数值。report generate --format pdf|html --report-file <FILE> 只会发布你据此编写的报告（PDF 使用 Markdown，HTML 使用 HTML），并返回 ViewUrl。

• 各动词接受的键：get、delete、execute 和 list-dry-run-reports 只接受 --scenario-key（键本身已包含项目，例如 CLAIM:7441）；传入 --project-key 会因 unknown option 而失败。create、list、stop 和 licenses get 接受 --project-key；licenses get 缺少该参数时会失败，不过任何项目返回的数量都相同。
• 如果运行被取消、自动化失败，或设置了任何 SloViolationReasons，execute --wait 会以状态码 1 退出，尽管输出仍显示 Success：报告这些原因，切勿重新运行来“修复”。状态码 4 表示已超过 --timeout-sec（默认值为 1800），且运行仍在继续：使用 results get --execution-id <EXECUTION_ID> 读取结果；新的 execute 会启动另一次运行。若完整运行时间超过 shell 限制：不带 --wait 启动运行，将 ExecutionId 提供给用户，并使用 results get 和 stop --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY>。
• 性能服务的读取命令不接受 --project-key（会报 unknown option）：results get、http-errors list、automation-errors list、transaction-metrics list。后三个命令需要 --start-time-ms 0 --end-time-ms <DURATION_MS>（Duration 来自 executions list）。transaction-metrics 仅返回 API 负载组的行；其他情况下的 [] 表示没有数据，而非延迟为零。--full 和 results get 会包含每秒序列；使用 --query 精简结果，并在汇总是否可上线时跳过这些序列。
• 存在两种不同的负载组 ID。load-groups update / remove 接受场景的负载组 ID（来自 get 或 load-groups add）。load-groups get、jobs list、robot-logs list、http-errors、automation-errors 和 transaction-metrics 接受来自 load-groups list --execution-id <EXECUTION_ID> 的负载组执行 ID。用错 ID 会返回 404 not_found。
• 使用 perf-scenario list --project-key <PROJECT_KEY> --search <NAME> 查找场景的键（行位于 Data.Scenarios 下）。查看过去的运行：perf-scenario executions list --project-key <PROJECT_KEY> --scenario-id <SCENARIO_ID>，可选传入 --execution-type dryRun|performanceTesting（行位于 Data.Data 下；响应中的 ExecutionType 首字母大写）。list 或 get 不会返回场景 UUID。list-dry-run-reports --scenario-key <SCENARIO_KEY> 仅在负载组的测试用例具有 AutomationId（链接到 Studio；link-automation 不会设置该值）时才返回 ScenarioId；否则，不带 --scenario-id 列出，并匹配 Name 以场景名称开头的行。
• report compare --scenario-id <SCENARIO_ID> --execution-ids <ID...> --report-file <HTML_FILE> 会发布一个 HTML 对比报告；该报告由你根据每次运行的 results get 编写（ID 按从旧到新的顺序排列，且属于同一场景），并返回 ViewUrl；添加 --project-key 可获取应用内链接。
• licenses get 返回整个租户的 RemainingVirtualUserUnits；该值最多可能延迟 4 小时。完整运行会消耗虚拟用户数 × 1（API）、10（Chrome/Edge）或 100（其他目标）；试运行不消耗任何单位。如果单位不足，请停止并告知用户。
• 排查失败的负载组时，使用 robot-logs list --load-group-id <ID> --level Error 和 jobs list --load-group-id <ID>。403 表示租户的性能测试功能未启用，或用户权限不足：按照规则 10 停止。
• delete --scenario-key <SCENARIO_KEY> --yes 会永久移除场景及其负载组（规则 5），并保留过去的执行记录，但这些记录将不再关联场景。它不会停止正在运行的执行；请先运行 stop。

关键规则

1. **始终先检查登录状态：**在执行任何 Test Manager 操作前，运行 uip login status --output json。如果未通过身份验证，运行 uip login。
2. 始终为每条 uip 命令传入 --output json，无一例外。
3. **任何失败的 uip 命令最多重试 3 次。**失败 3 次后，停止并报告错误；绝不使用直接 REST API。
4. 如果列表为空，则停止操作并告知用户，不要继续使用空键。例外：tm testcases list --filter 返回空列表可能是前缀未匹配；使用规则 8 的前缀回退，并且只有在仍未找到任何结果时才停止。筛选后的项目或 customfield 查询为空，属于实际的空结果，正常停止。
5. **删除前确认：**除非用户已授权删除该特定对象，否则先确认目标资源键。每次删除都必须传入 --yes 或 -y；未传入时命令会退出，不执行删除。
6. 对于必需的文件夹键，如果用户指定了文件夹名称，使用 uip or folders list -n <folder-name> --all --output json；如果由你自行选择，则省略 --all，仅列出成员文件夹。运行 /uipath-platform 查看文件夹管理详情。
7. **先查找，再假设：**绝不要猜测自动化名称、文件夹键、项目 ID 或测试用例键；先运行对应的列表命令，例如 uip tm testcases list-automations 或 uip or folders list -n <folder-name> --all。
8. **在服务端缩小命名实体列表查询的范围：**收到名称、键、标签或标记时，先查看 uip tm <resource> list --help 或 uip or <resource> list --help，找到相应的缩小范围标志并使用。绝不要先列出全部内容再在客户端筛选；这适用于 uip tm 和 uip or 中的所有实体，也适用于结果筛选：失败运行的日志使用 executions testcaselogs list --only-failed，某个测试用例的失败记录使用 testcases list-result-history --only-failed。例外：tm testcases list --filter 使用前缀匹配。如果名称中间的词语返回零条结果，请改用更宽泛、且包含上下文的前缀重试；只有在不存在可用前缀时才省略 --filter 重新列出，并按照规则 11 遍历所有页面，再确认不存在。
9. 恢复默认文件夹：uip tm testcases run 和 uip tm testsets run 需要项目默认文件夹。先尝试运行。只有当失败文本准确包含 "Message": "HTTP 400: Please assign folder to project level before executing testcases." 且 errorCode: itemNotFound 时，才运行 uip tm project set-default-folder --project-key <PROJECT_KEY> --folder-key <FOLDER_KEY> --output json，然后重试一次。使用 uip or folders list -n <folder-name> --all --output json 获取键。不要将其他错误解读为缺少文件夹：不可用的默认文件夹会返回含糊的 HTTP 5xx；不存在的文件夹键会返回 "HTTP 400: Internal Server Error." 和 errorCode: unknown。这两种情况均按规则 10 停止。绝不要覆盖有效的默认文件夹；Test Manager 可能会拒绝任意文件夹，并导致后续运行失败。这是规则 10 中唯一针对指定名称运行操作的例外；所有其他运行失败均停止。
10. **任何 uip 失败或存在歧义时，都要停止并询问用户：**包括命令错误、输出格式错误、标志或值不明确、匹配项过多、标识符缺失或架构异常。绝不要回退到 REST。只有明确指出的预期结果，以及一项可修正的自身失误，属于例外：(a) 规则 9 中缺少文件夹的错误，按该规则处理；(b) uip tm wait 退出代码为 2，且返回 Timed out after <N>s waiting for execution '<EXECUTION_ID>'. Last status: <status>.，这表示有界等待正常生效——报告运行未完成，并继续执行剩余步骤。Polling failed/interrupted/aborted ... 和退出代码 1 属于实际等待失败；(c) requirement AI 命令以退出代码 2 退出且出现 ErrorCode: timeout：作业仍在运行，因此使用其 Instructions 中命名的 --activity-id … --wait 命令恢复，绝不要重新启动；(d) uip tm run --type package 以退出代码 1 退出，且出现 "Code": "RunPackageTestsFailed" 或 "RunPackageCancelled" 以及 "ErrorCode": "execution_failed"，这表示运行已结束，但测试失败、没有测试，或运行已取消——报告 Data（计数、OutputPath、ExecutionUrl），不要重试；(e) 关于所传标志的 ValidationError（unknown option、missing required option）：阅读 <command> --help，修正标志后再运行一次（计入规则 3 的重试次数）；同一命令再次出现用法错误时停止。所有其他失败均停止。
11. **确认条目不存在前，遍历所有页面：**列表响应仅包含 Data，不含总数、游标或是否有更多结果的标志。若某页返回的行数恰好等于 --limit（默认值为 50），则可能还有更多结果；如果该页没有所需条目，请使用 --offset 加上页面大小，重新运行相同的列表命令，直到某页返回的行数少于页面大小。页面大小上限为 100：--limit 大于 100 会因 HTTP 400 … Page size cannot be greater than 100. 而失败。对于没有 --limit/--offset 的列表（例如 tm testcases list），应改用其筛选标志缩小范围（规则 8）。

快速开始

1. 验证身份验证：运行 uip login status --output json；如果未通过身份验证，运行 uip login。如有需要，使用 uip login tenant set <TENANT_NAME> --output json 设置租户。运行 /uipath-platform 查看更多身份验证详情。
2. 在调用任何 Test Manager 命令之前，先询问项目名称/键；但对于尚未指定项目的新工作，应使用默认项目（参见 Default project）。如果涉及多个项目，在一次提示中收集所有名称/键。使用 uip tm project list --filter <NAME_OR_KEY> --output json 查找每个项目。若没有匹配项，则停止并询问；若有多个匹配项，则展示候选项并请用户选择。后续操作中重复使用已确认的 PROJECT_KEY。
3. 按需使用：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（排查失败的运行：添加 --only-failed，仅返回失败日志，然后运行 testcases list-result-history --test-case-id <TEST_CASE_ID> --only-failed，以区分回归问题和偶发故障 — 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。

故障排查

REST API 返回 401 Unauthorized 时，运行 uip login 重新进行身份验证。如果命令意外失败，先使用 uip tm <command> --help 验证语法，然后使用 uip login status --output json 检查身份验证；是否继续仍由 Critical Rule 10 决定。

导航到工作流

• 阅读、修正（override）、分配或手动记录测试用例日志，以及 Result 与 OriginalResult 的区别：references/testcaselog-guide.md
• 在同一租户内或跨租户和环境备份、复制或移动项目（uip tm project export → import）：references/project-migration-guide.md
• 执行生命周期（手动打开／记录／完成）、筛选读取、取消、删除、导出 xlsx，以及报告日期（uip tm executions）：references/executions-guide.md
• 失败运行的根本原因、断言、步骤日志、证据，以及不稳定与回归分析：references/failure-triage-guide.md
• 根据失败结果提交缺陷，追溯到其测试用例／需求，并关联到跟踪器问题（uip tm defects）：references/defects-guide.md
• 使用 AI 处理需求：提出并创建测试用例、评估需求、查找并取消关联或删除过时的测试用例（uip tm requirements generate-testcases、evaluate、find-obsolete-testcases）：references/requirement-ai-guide.md
• 可供分享的测试人员或发布经理报告：references/test-result-report-guide.md
• 发布项目并将其关联到 Test Manager 测试用例（Studio/RPA）：references/publish-and-link-guide.md
• 打包、导入、标记，并在无服务器环境中运行 Playwright：references/playwright-first-mile-guide.md
• 按计划运行测试集、cron 格式，以及单批次与批量批次的语义（uip tm schedules）：references/schedules-guide.md
• 自定义字段定义、标签和值（uip tm customfield）：references/custom-fields-guide.md
• 测试实体上的对象标签／标记元数据（uip tm objectlabel）：references/object-labels-guide.md
• 项目时区、执行名称格式，以及只读内容（uip tm project settings）：references/project-settings-guide.md

反模式

• **身份验证失败时不要继续操作：**所有 Test Manager API 调用都需要有效的 bearer 令牌；应立即失败，而不是导致后续请求返回 401。
• **不要猜测命令名称：**必须使用动词-名词组合；不存在单独的动词命令。使用 uip tm <resource> --help --output json 确认。
• **不要手动构建软件包运行流程：**要运行已上传软件包中的所有测试，请使用 uip tm run --type package，而不是 link-package → testsets create → testcases add → testsets run → wait → result download。
• **不要运行 project get-default 来查看默认项目：**如果租户尚无默认项目，该命令会创建一个，并向租户的 Everyone 组开放。请改为读取 project list 的第一行。
• **不要对 Playwright 测试用例使用 link-automation：**导入时会自动关联；手动关联仅适用于 Studio/RPA 工作流。