Holarch

参考

实践示例:通过 AI 应用导入测试结果

将测试系统的结果导入 Holarch 测试用例,可使用用于 CI 的 REST 脚本,也可使用 AI 应用:它运行测试、提出供评审的结果并报告 RVTM 的显示内容;涵盖设置、脚本、完整示例和故障排除。

使用方法 →

本页内容
  1. 概述
  2. 前提条件
  3. 如何使用
    1. 何时使用及原因
    2. 在每个测试中指明测试用例
    3. 记录来自 CI 的结果
    4. 借助 AI 应用运行测试并提议结果
    5. 实例:CubeSat EO-1 演示
    6. 提示
  4. 故障排除
  5. 相关页面

概述

本实践示例将自动化测试系统的结果记录到相应的 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 测试用例匹配。

  1. 将编号放入测试名称中:在 pytest 中为 test_TC_14_off_nadir_imaging,在其他运行器中为 TC-14 off-nadir imaging。
  2. 每个测试对应一个 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']})")
  1. 设置环境变量 HOLARCH_TOKEN(令牌)和 HOLARCH_PROJECT(来自 GET /api/v1/projects 的项目 ID)。
  2. 运行测试并生成 JUnit 报告,例如 pytest --junitxml=results.xml。
  3. 运行 python3 junit_to_holarch.py results.xml。

    每个已记录的结果显示一行,例如 TC-14 Off-Nadir Imaging Test: Passed。

  4. 在 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 应用运行测试并提议结果

  1. 在存放测试的仓库中,例如向命令行 AI 工具询问:“运行指向测试并生成 JUnit 报告。然后在 Holarch CubeSat 项目中提议其结果:在相应的测试用例上设置 Status,失败时还设置 Actual Result。”
  2. 命令行 AI 工具运行测试。在 Holarch 中,它用 record_test_results 将结果添加到提议中(每个结果一项更改,包含状态、实际结果、测试人和测试日期)。然后用 propose_changes 发送提议。

    命令行 AI 工具会回复提议的标题、它提议的结果以及评审链接。

  3. 在 Holarch 中打开 ✦ AI ▾ → 评审“<title>”…,或铃铛下的通知。

    对话框显示每个测试用例及其当前值和提议值。

  4. 取消勾选您不接受的结果,然后点击应用所选项。

    结果会被记录,在历史中记录您的名字,每项都带有一条运行日志记录,与导入结果…相同;一次撤销即可全部撤回。

  5. 向命令行 AI 工具询问:“CubeSat 项目中哪些需求仍未通过验证?”

    命令行 AI 工具用 get_matrix(matrix rvtm,status Failed)读取 RVTM,并列出每个需求及其失败的测试用例。

命令行 AI 工具也可以基于您的 CI 已生成的报告工作:附加 results.xml 或告诉它其位置,而不是让它运行测试。

实例:CubeSat EO-1 演示

  1. 通过管理项目 → 项目文件 ▾ → 新建演示项目创建演示。

    在验证 → 测试中心中,TC-14 Off-Nadir Imaging Test 为未运行,TC-04 Pointing Accuracy Test 为失败。

  2. 编写一个包含两个测试的 JUnit 报告:test_TC_14_off_nadir_imaging 通过,test_TC_04_pointing_accuracy 失败,消息为 0.12 degrees on 2 of 20 targets。
  3. 运行 python3 junit_to_holarch.py results.xml。

    您会看到 TC-14 Off-Nadir Imaging Test: Passed 和 TC-04 Pointing Accuracy Test: Failed。

  4. 打开验证 → RVTM。

    1.6.2 Off-Nadir Imaging 现在显示通过。2.1 Pointing Accuracy 仍未通过,TC-04 的实际结果为 0.12 degrees on 2 of 20 targets。

  5. 使用 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,然后开始新的对话。