參考資料
範例做法:透過 AI 應用程式匯入測試結果
將測試系統的結果帶入 Holarch 測試案例,可使用適用於 CI 的 REST 指令碼,或使用 AI 應用程式:由它執行測試、提出結果供審查,並報告 RVTM 顯示的內容;設定、指令碼、實作範例與疑難排解。
概觀
此範例做法會將自動化測試系統的結果記錄到對應的 Holarch 測試案例上,讓 RVTM 顯示哪些需求通過。它分為兩個部分:
- 來自 CI 的結果(REST API):指令碼會讀取大多數測試執行器所產生的 JUnit XML 報告,並將每筆結果記錄到對應的測試案例上:Status、Actual Result、Tested By、Test Date,以及一筆執行記錄項目。
- 透過 AI 應用程式的結果(MCP):命令列 AI 工具會執行測試、將結果對應到測試案例,並提議結果供您在 Holarch 中審查。接著它會讀取 RVTM,告訴您哪些需求仍然失敗。
若要手動匯入結果檔案,請改用驗證 → 測試中心 → 匯入結果…(從其他測試系統匯入結果)。REST API 與 MCP 以相同方式記錄結果:在每個測試案例上記錄 Tested By、Test Date 與一筆執行記錄項目。
先決條件
- 含 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。失敗時,它也會將失敗訊息記錄為 Actual Result。略過的測試維持不變。
# 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會將報告的所有結果記錄為一次變更,如同匯入結果…:Status、失敗時的 Actual Result、Tested By(此處為 CI;省略時為您的帳戶名稱)、Test Date(請求的時間),以及一筆source設為報告檔案名稱的執行記錄項目(測試結果)。testCase以編號指定測試案例,例如TC-14;id 或名稱也可以。Status 在此接受 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將結果加入提議(每筆結果一項變更,含 Status、Actual Result、Tested By 與 Test Date)。接著以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 為 Not Run,TC-04 Pointing Accuracy Test 為 Failed。
- 撰寫一份含兩個測試的 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 現在顯示 Passed。2.1 Pointing Accuracy 仍然失敗,而 TC-04 的 Actual Result 顯示 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,然後開始新的對話。 |