参考
实践示例:通过 AI 应用导入测试结果
将测试系统的结果导入 Holarch 测试用例,可使用用于 CI 的 REST 脚本,也可使用 AI 应用:它运行测试、提出供评审的结果并报告 RVTM 的显示内容;涵盖设置、脚本、完整示例和故障排除。
概述
本实践示例将自动化测试系统的结果记录到相应的 Holarch 测试用例上,使 RVTM 显示哪些需求通过。它分为两部分:
- 来自 CI 的结果(REST API):脚本读取大多数测试运行器生成的 JUnit XML 报告,并将每个结果记录到相应的测试用例上:状态、实际结果、测试人、测试日期以及一条运行日志记录。
- 通过 AI 应用的结果(MCP):命令行 AI 工具运行测试,将结果与测试用例匹配,并提议结果供您在 Holarch 中评审。然后它读取 RVTM,告诉您哪些需求仍未通过。
要手动导入结果文件,请改用验证 → 测试中心 → 导入结果…(从其他测试系统导入结果)。REST API 和 MCP 以同样方式记录结果:在每个测试用例上记录测试人、测试日期以及一条运行日志记录。
前提条件
- 包含 API 和 MCP 的方案:Individual 或 Team,或 Individual 试用。在 Free 方案中,拥有已验证学术邮箱地址或属于活跃班级组织的账户也可使用它们(方案和限制)。
- 一个包含测试用例的 Holarch 项目,测试可以指明其编号,例如 TC-14。您需要编辑者或所有者角色。
- 脚本部分:一个限制在该项目内的读写令牌(账户设置 → API 令牌 → 新令牌,创建令牌),以及 Python 3.9 或更高版本和
requests包(python3 -m pip install requests)。 - AI 应用部分:以读取并提出更改访问权限连接到 Holarch 的命令行 AI 工具(将 Holarch 连接到 AI 应用),在存放测试的仓库中使用。
- 能生成 JUnit XML 的测试运行器,例如
pytest --junitxml=results.xml,或大多数 CI 测试步骤。
如何使用
何时使用及原因
验证完成了从需求到证据的闭环。当测试自动运行时,将其结果手动输入 Holarch 既慢又容易出错。当结果应无需评审直接记录时(例如夜间回归运行),请使用脚本。当应有人在记录前查看结果时(例如鉴定运行),请使用 AI 应用。
在每个测试中指明测试用例
脚本和 AI 应用根据测试名称中的测试用例编号将测试与 Holarch 测试用例匹配。
- 将编号放入测试名称中:在 pytest 中为
test_TC_14_off_nadir_imaging,在其他运行器中为TC-14 off-nadir imaging。 - 每个测试对应一个 Holarch 测试用例。有子测试用例的测试用例从其子项获取状态;请将结果记录到子项上。
记录来自 CI 的结果
脚本在一个请求中为每个匹配的测试用例记录 Passed 或 Failed。对于失败,它还将失败消息记录为实际结果。跳过的测试保持不变。
# junit_to_holarch.py: record JUnit XML results on Holarch test cases.
# Usage: python3 junit_to_holarch.py results.xml
import os
import re
import sys
import xml.etree.ElementTree as ET
import requests
HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
NUMBER = re.compile(r"TC[-_ ](\d+)") # TC-14 or test_TC_14_…; change it to match your numbering
def holarch(method, path, **kw):
r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
if r.status_code >= 400:
d = r.json()
raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
return r.json()
results = []
for test in ET.parse(sys.argv[1]).getroot().iter("testcase"):
m = NUMBER.search(test.get("name", ""))
if not m or test.find("skipped") is not None:
continue
failure = test.find("failure")
if failure is None:
failure = test.find("error")
result = {"testCase": "TC-" + m.group(1), "status": "Passed" if failure is None else "Failed"}
if failure is not None:
result["actualResult"] = (failure.get("message") or failure.text or "Failed").strip()[:4000]
results.append(result)
answer = holarch("POST", f"/projects/{PROJECT}/test-results",
json={"source": os.path.basename(sys.argv[1]), "testedBy": "CI", "results": results})
for r in answer["recorded"]:
print(f"{r['number']} {r['name']}: {r['status']}")
for r in answer["skipped"]:
if r["code"] == "not-found":
print(f"{r['testCase']}: no test case with this number in Holarch")
else:
print(f"{r['testCase']}: not recorded ({r['reason']})")
- 设置环境变量
HOLARCH_TOKEN(令牌)和HOLARCH_PROJECT(来自GET /api/v1/projects的项目 ID)。 - 运行测试并生成 JUnit 报告,例如
pytest --junitxml=results.xml。 - 运行
python3 junit_to_holarch.py results.xml。每个已记录的结果显示一行,例如
TC-14 Off-Nadir Imaging Test: Passed。 - 在 Holarch 中打开验证 → RVTM。
这些测试用例所验证的需求显示新的状态。
工作原理:
POST /api/v1/projects/<project>/test-results将报告的所有结果作为一次更改记录,与导入结果…相同:状态、失败时的实际结果、测试人(此处为 CI;省略时为您的账户名称)、测试日期(请求时间),以及一条source设为报告文件名的运行日志记录(测试结果)。testCase按编号指定测试用例,例如TC-14;ID 或名称也可以。此处状态取 Passed 或 Failed;该端点还接受 Blocked、In Progress 和 Not Run,以及测试工具的用词,例如 pass 和 fail。- 无法记录的结果(例如 Holarch 中没有的编号)会连同原因列在
skipped中;其他结果仍会记录。 - 该更改以您的名义记录,所有打开该项目的人会立即看到。
在 CI 作业中,将脚本作为测试之后的一个步骤运行,并将令牌作为密钥。例如在 GitHub Actions 中:
- name: Record results in Holarch
if: always()
env:
HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
run: |
python3 -m pip install requests
python3 junit_to_holarch.py results.xml
if: always() 使测试失败时也会记录结果,而这正是结果最重要的时候。
借助 AI 应用运行测试并提议结果
- 在存放测试的仓库中,例如向命令行 AI 工具询问:“运行指向测试并生成 JUnit 报告。然后在 Holarch CubeSat 项目中提议其结果:在相应的测试用例上设置 Status,失败时还设置 Actual Result。”
- 命令行 AI 工具运行测试。在 Holarch 中,它用
record_test_results将结果添加到提议中(每个结果一项更改,包含状态、实际结果、测试人和测试日期)。然后用propose_changes发送提议。命令行 AI 工具会回复提议的标题、它提议的结果以及评审链接。
- 在 Holarch 中打开 ✦ AI ▾ → 评审“<title>”…,或铃铛下的通知。
对话框显示每个测试用例及其当前值和提议值。
- 取消勾选您不接受的结果,然后点击应用所选项。
结果会被记录,在历史中记录您的名字,每项都带有一条运行日志记录,与导入结果…相同;一次撤销即可全部撤回。
- 向命令行 AI 工具询问:“CubeSat 项目中哪些需求仍未通过验证?”
命令行 AI 工具用
get_matrix(matrixrvtm,statusFailed)读取 RVTM,并列出每个需求及其失败的测试用例。
命令行 AI 工具也可以基于您的 CI 已生成的报告工作:附加 results.xml 或告诉它其位置,而不是让它运行测试。
实例:CubeSat EO-1 演示
- 通过管理项目 → 项目文件 ▾ → 新建演示项目创建演示。
在验证 → 测试中心中,TC-14 Off-Nadir Imaging Test 为未运行,TC-04 Pointing Accuracy Test 为失败。
- 编写一个包含两个测试的 JUnit 报告:
test_TC_14_off_nadir_imaging通过,test_TC_04_pointing_accuracy失败,消息为 0.12 degrees on 2 of 20 targets。 - 运行
python3 junit_to_holarch.py results.xml。您会看到
TC-14 Off-Nadir Imaging Test: Passed和TC-04 Pointing Accuracy Test: Failed。 - 打开验证 → RVTM。
1.6.2 Off-Nadir Imaging 现在显示通过。2.1 Pointing Accuracy 仍未通过,TC-04 的实际结果为 0.12 degrees on 2 of 20 targets。
- 使用 AI 应用时,相同的结果会先作为提议到达。点击应用所选项后,RVTM 显示相同的内容。
提示
- 将结果记录在最底层的测试用例上。父项由其子项汇总得出。
- 将脚本的令牌限制在这一个项目内,并在流水线停用时将其撤销。
- 指明了 Holarch 中没有的编号的测试会列为“no test case with this number”(没有此编号的测试用例)。请修正测试名称或创建该测试用例。
- 测试活动结束时,请在测试中心保存测试周期,使其结果与下一次运行分开保存(保存测试周期)。
故障排除
| 消息或症状 | 原因和解决方法 |
|---|---|
Holarch answered 401 token-invalid | 令牌错误、已撤销或已到期。请在账户设置 → API 令牌下创建新令牌。 |
Holarch answered 403 plan-api | 账户的方案不包含 API 和 MCP。请开始 Individual 试用或选择方案;之后令牌即可再次使用。 |
Holarch answered 403 read-only-token | 脚本会写入结果。请创建读写令牌。 |
Holarch answered 403 forbidden | 您在项目中的角色是查看者或评审者。所有者可以将您设为编辑者。 |
TC-14: not recorded (…) | Holarch 无法记录该结果,例如因为测试用例已锁定或有子测试用例。原因会说明是哪种情况;其他结果已记录。 |
TC-04: not recorded (… configuration control …) | 该测试用例处于配置控制之下。请在应用中通过变更请求记录其结果。 |
Holarch answered 429 rate-limited | 每分钟请求过多。请等待 Retry-After 中的秒数,然后再次运行脚本。 |
| 测试用例保持其旧状态 | 有子项的测试用例显示其子项汇总后的状态。请将结果记录到子项上。 |
| 命令行 AI 工具不提供 Holarch 写入工具 | 该连接为只读。请运行 /mcp,以读取并提出更改重新连接 holarch,然后开始新的对话。 |