Holarch

참조

레시피: Claude를 통한 테스트 결과

테스트 시스템의 결과를 Holarch 테스트 케이스로 가져옵니다. CI용 REST 스크립트를 사용하거나, 테스트를 실행하고 결과를 검토용으로 제안하고 RVTM에 표시되는 내용을 보고하는 Claude를 사용합니다. 설정, 스크립트, 실습 예제, 문제 해결을 다룹니다.

사용 방법 →

이 페이지의 내용
  1. 개요
  2. 사전 요구 사항
  3. 사용 방법
    1. 사용 시기와 이유
    2. 각 테스트에 테스트 케이스 이름 지정
    3. CI의 결과 기록
    4. Claude로 테스트를 실행하고 결과 제안
    5. 실습 예제: CubeSat EO-1 데모
    6. 팁
  4. 문제 해결
  5. 관련 페이지

개요

이 레시피는 자동화된 테스트 시스템의 결과를 해당하는 Holarch 테스트 케이스에 기록하여 RVTM이 어떤 요구사항이 통과하는지 보여 주게 합니다. 두 부분으로 이루어져 있습니다.

  • CI의 결과(REST API): 스크립트가 대부분의 테스트 러너가 작성하는 JUnit XML 보고서를 읽고 각 결과를 해당 테스트 케이스에 기록합니다. 상태, 실제 결과, 테스트 수행자, 테스트 날짜, 실행 로그 항목입니다.
  • Claude를 통한 결과(MCP): Claude Code가 테스트를 실행하고, 결과를 테스트 케이스와 대조하고, Holarch에서 검토할 결과를 제안합니다. 그런 다음 RVTM을 읽고 아직 실패하는 요구사항을 알려 줍니다.

결과 파일을 직접 가져오려면 대신 검증 → 테스트 센터 → 결과 가져오기…를 사용합니다(다른 테스트 시스템에서 결과 가져오기). REST API와 MCP도 같은 방식으로 결과를 기록합니다. 각 테스트 케이스에 테스트 수행자, 테스트 날짜, 실행 로그 항목이 남습니다.

사전 요구 사항

  • API와 MCP가 포함된 요금제: Individual 또는 Team, 또는 Individual 체험판입니다. Free 요금제에서도 확인된 학술 이메일 주소가 있거나 활성 수업 조직에 속한 계정은 이를 사용할 수 있습니다(요금제 및 한도).
  • 테스트가 지정할 수 있는 번호(예: TC-14)를 가진 테스트 케이스가 있는 Holarch 프로젝트. 편집자 또는 소유자 역할이 필요합니다.
  • 스크립트용: 프로젝트로 제한한 읽기 및 쓰기 토큰(계정 설정 → API 토큰 → 새 토큰, 토큰 만들기)과 requests 패키지(python3 -m pip install requests)가 있는 Python 3.9 이상.
  • Claude 부분: 테스트가 들어 있는 저장소에서, 읽기 및 변경 제안 접근 권한으로 Holarch에 연결된 Claude Code(Holarch를 Claude에 연결).
  • pytest --junitxml=results.xml이나 대부분의 CI 테스트 단계처럼 JUnit XML을 작성하는 테스트 러너.

사용 방법

사용 시기와 이유

검증은 요구사항에서 증거까지의 고리를 닫습니다. 테스트가 자동으로 실행될 때 결과를 Holarch에 직접 입력하면 느리고 오류가 생기기 쉽습니다. 야간 회귀 실행처럼 결과가 검토 없이 반영되어야 할 때는 스크립트를 사용합니다. 인증 실행처럼 결과가 기록되기 전에 사람이 봐야 할 때는 Claude를 사용합니다.

각 테스트에 테스트 케이스 이름 지정

스크립트와 Claude는 테스트 이름에 있는 테스트 케이스 번호로 테스트를 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. pytest --junitxml=results.xml처럼 JUnit 보고서와 함께 테스트를 실행합니다.
  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()는 테스트가 실패할 때도 결과를 기록합니다. 결과가 가장 중요한 때가 바로 그때입니다.

Claude로 테스트를 실행하고 결과 제안

  1. 테스트가 들어 있는 저장소에서 Claude Code에게 예를 들어 이렇게 묻습니다. “JUnit 보고서와 함께 지향 테스트를 실행해 줘. 그런 다음 Holarch CubeSat 프로젝트에 결과를 제안해 줘. 해당 테스트 케이스에 Status를 설정하고, 실패한 경우 Actual Result도 설정해 줘.”
  2. Claude Code가 테스트를 실행합니다. Holarch에서는 record_test_results로 결과를 제안에 추가합니다(결과마다 변경 하나, 상태, 실제 결과, 테스트 수행자, 테스트 날짜 포함). 그런 다음 propose_changes로 제안을 보냅니다.

    Claude Code가 제안의 제목, 제안하는 결과, 검토 링크로 답합니다.

  3. Holarch에서 ✦ AI ▾ → “<title>” 검토… 또는 종 아래의 알림을 엽니다.

    대화 상자에 각 테스트 케이스가 현재 값과 제안된 값과 함께 표시됩니다.

  4. 받아들이지 않는 결과는 체크 해제한 다음 선택 항목 적용을 클릭합니다.

    결과가 기록에 내 이름을 남기며 기록되고, 각각 결과 가져오기…에서처럼 실행 로그 항목이 생기며, 실행 취소 한 번으로 모두 되돌립니다.

  5. Claude Code에게 묻습니다. “CubeSat 프로젝트에서 아직 검증에 실패하는 요구사항은?”

    Claude Code가 get_matrix(matrix rvtm, status Failed)로 RVTM을 읽고 각 요구사항을 실패한 테스트 케이스와 함께 나열합니다.

Claude Code는 CI가 이미 작성한 보고서로도 작업할 수 있습니다. 테스트를 실행하도록 요청하는 대신 results.xml을 첨부하거나 가리킵니다.

실습 예제: CubeSat EO-1 데모

  1. 프로젝트 관리 → 프로젝트 파일 ▾ → 새 데모 프로젝트로 데모를 만듭니다.

    검증 → 테스트 센터에서 TC-14 Off-Nadir Imaging Test는 Not Run이고 TC-04 Pointing Accuracy Test는 Failed입니다.

  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에 이제 Passed가 표시됩니다. 2.1 Pointing Accuracy는 여전히 실패하며, TC-04의 실제 결과는 0.12 degrees on 2 of 20 targets입니다.

  5. Claude를 사용하면 같은 결과가 먼저 제안으로 도착합니다. 선택 항목 적용 후 RVTM에 같은 내용이 표시됩니다.

팁

  • 가장 하위의 테스트 케이스에 결과를 기록합니다. 상위 테스트 케이스는 하위에서 집계됩니다.
  • 스크립트의 토큰은 해당 프로젝트 하나로 제한하고, 파이프라인을 폐기할 때 취소합니다.
  • Holarch에 없는 번호를 지정한 테스트는 “이 번호의 테스트 케이스가 없음”으로 나열됩니다. 테스트 이름을 고치거나 테스트 케이스를 만듭니다.
  • 캠페인이 끝나면 테스트 센터에서 테스트 주기를 저장하여 그 결과를 다음 실행과 분리해 보관합니다(테스트 주기 저장).

문제 해결

메시지 또는 증상원인과 해결
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의 초만큼 기다린 다음 스크립트를 다시 실행합니다.
테스트 케이스가 이전 상태를 유지함하위 테스트 케이스가 있는 테스트 케이스는 하위에서 집계된 상태를 보여 줍니다. 하위 테스트 케이스에 결과를 기록합니다.
Claude Code가 Holarch 쓰기 도구를 제공하지 않음연결이 읽기 전용입니다. /mcp를 실행하고 읽기 및 변경 제안으로 holarch를 다시 연결한 다음 새 대화를 시작합니다.