操作方法：从 CLI 运行测试

本页面显示了如何从 CLI 作为 CI 管道的一部分运行 UiPath Test Manager测试集，以及如何正确读取结论。uip tm工具将测试运行拆分为三个动词；即使测试失败，仅使用其中一个也可以生成通过的构建。

黄金守则：启动 → 等待 → 验证

由于测试失败，没有单个uip tm动词出现非零值。要使管道在红色测试运行时失败，需要执行以下三个命令：

1. 启动— uip tm testsets run 。将运行加入队列，并在 Orchestrator 接受请求后立即退出0 。响应中的Status: "Running"反映发布时的状态，而非最终结果。
2. 阻止— uip tm wait 。轮询，直到执行到达终止状态（ Passed 、 Failed 、 Cancelled ）。当0到达任何最终状态时退出 wait，因为“已完成”是的成功信号。在--timeout上退出2 （特定于域的身份验证错误插槽重用，因此脚本可以在“花费太长时间”上分支，而无需解析文本）。
3. 验证— uip tm report get 。读取Data.Failed （和Passed 、 Skipped和PassRate ）。每当成功获取摘要时（无论通过/失败）退出0 — 脚本负责将Data.Failed > 0转换为非零退出。

存在快捷方式模式（例如uip or jobs start --wait-for-completion ，“等待+验证单个作业”），但不适用于测试集。始终写下这三个步骤。

最小可行代码片段

#!/usr/bin/env bash
set -euo pipefail

# 1. Launch
EXECUTION_ID=$(uip tm testsets run \
  --test-set-key DEMO:10 \
  --output-filter "Data.ExecutionId" \
  --output plain)

# 2. Block (default timeout: 30 min; adjust with --timeout)
if ! uip tm wait \
  --execution-id "$EXECUTION_ID" \
  --project-key DEMO \
  --timeout 1800; then
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "test run did not finish within 30 minutes" >&2
    exit 2
  fi
  echo "wait failed (exit $code)" >&2
  exit "$code"
fi

# 3. Verify
FAILED=$(uip tm report get \
  --execution-id "$EXECUTION_ID" \
  --project-key DEMO \
  --output-filter "Data.Failed" \
  --output plain)

if [ "$FAILED" -gt 0 ]; then
  echo "$FAILED test case(s) failed" >&2
  exit 1
fi

echo "all tests passed"

--output plain针对标量筛选结果返回空值；这是在不解析 JSON 的情况下将字段捕获到 shell 变量中的最安全方法。请参阅脚本模式 — 从信封中读取值。

选取命令的输入

uip tm testsets run需要测试集键，而不是 UUID。键的格式为<ProjectKey>:<Number> — 例如， DEMO:10 。两种查找方法：

# From the Test Manager UI — it is the "Key" column in the test set list.

# Or from the CLI:
uip tm testsets list --project-key DEMO --filter smoke \
  --output-filter "Data[*].{key:TestSetKey, name:Name}"

--project-key在list中为必需项； run从测试集密钥的前缀中派生项目（ DEMO:10 → 项目DEMO ）。

如果您需要uip tm executions list --test-set-id数字 UUID，请使用同一列表输出上的Id字段，而不是TestSetKey 。

选择运行哪些案例

uip tm testsets run --execution-type控制运行集合中的测试用例：

• automated （默认） — 仅适用于自动化测试用例。
• manual — 仅适用于手动测试用例。
• mixed — 两者兼而有之。
• none — 无类型筛选器。

对于 CI，请保留默认值 ( automated ) — 手动用例需要人工来标记通过/失败，并且会等待InProgress直到--timeout 。

传递参数覆盖

如果测试集公开参数（例如，目标 URL 或帐户 ID），请在启动时使用--input-path覆盖这些参数：

cat > ./params.json <<'EOF'
[
  {"name": "TargetUrl", "type": "String", "value": "https://staging.example.com"},
  {"name": "AccountId", "type": "String", "value": "acme-staging"}
]
EOF

uip tm testsets run --test-set-key DEMO:10 --input-path ./params.json

通过name （不区分大小写）和type存在）将覆盖与测试集的当前参数定义进行匹配。如果服务器未报告任何参数定义，则按原样发送输入。

详细阅读裁定

uip tm report get是摘要读取器。默认输出为您提供记分卡；传递--query （jq 样式筛选器）以在一次调用中提取子集：

# Pretty scorecard
uip tm report get --execution-id "$EXECUTION_ID" --project-key DEMO

# Script-friendly — JSON with just the counts
uip tm report get --execution-id "$EXECUTION_ID" --project-key DEMO \
  --query '{total: .TotalTests, passed: .Passed, failed: .Failed}'

Data信封包含以下字段（完整架构请参见report get参考）：

• TotalTests 、 Passed 、 Failed 、 Skipped 、 PassRate （ "80%" ）、 Duration （ HH:MM:SS ）。
• FailedTests — 每个失败的测试用例一个条目，带有TestCaseName和Error字符串（日志的info字段或失败断言消息的级联列表）。

当您需要 CI 测试仪表板可以提取的 JUnit-XML 文件时，请使用uip tm result download代替（或与） report get一起使用。

在 CI 日志中显示失败的案例

在退出管道之前，每次失败时将FailedTests数组转换为人类可读的行：

if [ "$FAILED" -gt 0 ]; then
  uip tm report get \
    --execution-id "$EXECUTION_ID" \
    --project-key DEMO \
    --output-filter "Data.FailedTests[*].[TestCaseName, Error]" \
    --output plain >&2
  echo "$FAILED test case(s) failed" >&2
  exit 1
fi

要进行更深入的故障分析（单个失败案例中的逐个断言详细信息），请对uip tm testcaselogs list-assertions返回的日志 ID 使用uip tm executions testcaselogs list --only-failed 。

重试不稳定案例

如果运行发生可能是不稳定的（时间、环境）故障，请仅就地重试失败的案例：

uip tm executions retry \
  --execution-id "$EXECUTION_ID" \
  --project-key DEMO

uip tm executions retry重用相同的执行 ID — 不会创建新的执行 ID。如果没有重试失败，它会打印一条信息消息并退出0 （无意中不是错误）。

在retry后，对同一执行 ID 遍历wait + report get 。

常见错误

• 正在解析testsets run输出以决定通过/失败。启动时的Status字段通常为Running — 这意味着运行已加入队列，但并不是所有测试都已通过。始终先调用wait ，然后调用report get 。
• 忘记--timeout上的wait 。默认值为 1800 秒（30 分钟）。传递0以无限期等待（在 CI 中很少出现）；对于长套件，请传递更大的数字。
• 正在将2的退出wait视为身份验证失败。具体来说，在wait中， 2表示超时，而非AuthenticationError — 请参阅uip tm wait退出代码。
• 使用testsets动词创建测试。测试用例及其到 Orchestrator 自动化的链接来自uip tm testcases ； testsets只会对它们进行分组。

完整的 CI 就绪示例

管道步骤的 bash 代码片段 — 在任何测试失败、超时或错误时，构建都会失败：

#!/usr/bin/env bash
set -euo pipefail

TEST_SET_KEY="${TEST_SET_KEY:?TEST_SET_KEY is required}"
PROJECT_KEY="${PROJECT_KEY:?PROJECT_KEY is required}"
TIMEOUT="${TEST_TIMEOUT:-1800}"

EXECUTION_ID=$(uip tm testsets run \
  --test-set-key "$TEST_SET_KEY" \
  --output-filter "Data.ExecutionId" \
  --output plain)

echo "started execution $EXECUTION_ID" >&2

if ! uip tm wait \
  --execution-id "$EXECUTION_ID" \
  --project-key "$PROJECT_KEY" \
  --timeout "$TIMEOUT"; then
  code=$?
  case "$code" in
    2) echo "execution $EXECUTION_ID did not finish within ${TIMEOUT}s" >&2; exit 2 ;;
    *) echo "wait failed with exit $code" >&2; exit "$code" ;;
  esac
fi

# Get the scorecard and the names of any failed cases in one shot
uip tm report get \
  --execution-id "$EXECUTION_ID" \
  --project-key "$PROJECT_KEY"

FAILED=$(uip tm report get \
  --execution-id "$EXECUTION_ID" \
  --project-key "$PROJECT_KEY" \
  --output-filter "Data.Failed" \
  --output plain)

if [ "$FAILED" -gt 0 ]; then
  echo "$FAILED test case(s) failed" >&2
  exit 1
fi

echo "all tests passed"

在任何CI 方法中的解决方案部署步骤之后运行此脚本。唯一特定于环境的配置为TEST_SET_KEY / PROJECT_KEY — 根据管道中的每个环境进行设置，同一脚本可在 dev/stage/prod 之间干净提升。

另请参阅

• uip tm概述— 完整的命令界面。
• uip tm testsets run 、 uip tm wait 、 uip tm report get — 上面使用的三个动词。
• uip tm result download — 用于 CI 仪表板的 JUnit XML 导出。
• 脚本模式— 轮询、JSON 筛选、幂等管道。
• 退出代码— 共享合同和wait的特定域2 。