Holarch

Referência

Receita: resultados de teste por meio do Claude

Traga resultados de um sistema de teste para casos de teste do Holarch, com um script REST para CI ou com o Claude, que executa os testes, propõe os resultados para revisão e informa o que a RVTM mostra; configuração, um script, um exemplo prático e solução de problemas.

Como usá-lo →

Nesta página
  1. Visão geral
  2. Pré-requisitos
  3. Como usá-lo
    1. Quando e por quê
    2. Nomear o caso de teste em cada teste
    3. Registrar resultados da CI
    4. Executar os testes e propor os resultados com o Claude
    5. Exemplo prático: a demonstração CubeSat EO-1
    6. Dicas
  4. Solução de problemas
  5. Páginas relacionadas

Visão geral

Esta receita registra resultados de um sistema de teste automatizado nos casos de teste correspondentes do Holarch, para que a RVTM mostre quais requisitos passam. Ela tem duas partes:

  • Resultados da CI (API REST): um script lê o relatório JUnit XML que a maioria dos executores de teste grava e registra cada resultado no caso de teste correspondente: Status, Resultado real, Testado por, Data do teste e uma entrada no registro de execução.
  • Resultados pelo Claude (MCP): o Claude Code executa os testes, associa os resultados aos casos de teste e propõe os resultados para você revisar no Holarch. Depois ele lê a RVTM e informa quais requisitos ainda falham.

Para importar um arquivo de resultados à mão, use Verificação → Central de testes → Importar resultados… (Importar resultados de outro sistema de teste). A API REST e o MCP registram os resultados da mesma forma: Testado por, Data do teste e uma entrada no registro de execução de cada caso de teste.

Pré-requisitos

  • Um plano com a API e o MCP: Individual ou Team, ou a avaliação do Individual. No plano Free, uma conta com um endereço de e-mail acadêmico verificado ou em uma organização de turma ativa também os tem (Planos e limites).
  • Um projeto do Holarch com casos de teste cujos números os testes possam citar, como TC-14. Você precisa do papel de editor ou proprietário.
  • Para o script: um token Leitura e escrita limitado ao projeto (Ajustes da conta → Tokens de API → Novo token, Criar um token), e Python 3.9 ou posterior com o pacote requests (python3 -m pip install requests).
  • Para a parte do Claude: o Claude Code conectado ao Holarch com acesso Ler e propor alterações (Conectar o Holarch ao Claude), no repositório que contém os testes.
  • Um executor de testes que grave JUnit XML, como pytest --junitxml=results.xml, ou a maioria das etapas de teste de CI.

Como usá-lo

Quando e por quê

A verificação fecha o ciclo do requisito até a evidência. Quando os testes rodam automaticamente, digitar os resultados no Holarch é lento e sujeito a erros. Use o script quando os resultados devem entrar sem revisão, como em execuções de regressão noturnas. Use o Claude quando uma pessoa deve ver os resultados antes de serem registrados, como em uma execução de qualificação.

Nomear o caso de teste em cada teste

O script e o Claude associam um teste a um caso de teste do Holarch pelo número do caso de teste no nome do teste.

  1. Coloque o número no nome do teste: test_TC_14_off_nadir_imaging no pytest, ou TC-14 off-nadir imaging em outros executores.
  2. Mantenha um caso de teste do Holarch por teste. Um caso de teste com casos de teste filhos recebe o status dos filhos; registre os resultados nos filhos.

Registrar resultados da CI

O script registra Passed ou Failed em cada caso de teste associado, em uma solicitação. Para uma falha, ele também registra a mensagem de falha como Resultado real. Testes pulados ficam inalterados.

# 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. Defina as variáveis de ambiente HOLARCH_TOKEN (o token) e HOLARCH_PROJECT (o id do projeto obtido com GET /api/v1/projects).
  2. Execute os seus testes com um relatório JUnit, como pytest --junitxml=results.xml.
  3. Execute python3 junit_to_holarch.py results.xml.

    Você vê uma linha por resultado registrado, como TC-14 Off-Nadir Imaging Test: Passed.

  4. No Holarch, abra Verificação → RVTM.

    Os requisitos que esses casos de teste verificam mostram o novo status.

Como funciona:

  • POST /api/v1/projects/<project>/test-results registra todos os resultados do relatório como uma alteração, como faz Importar resultados…: Status, Resultado real para as falhas, Testado por (aqui CI; o nome da sua conta quando omitido), Data do teste (o horário da solicitação) e uma entrada no registro de execução com source definido como o nome do arquivo do relatório (Resultados de teste).
  • testCase indica o caso de teste pelo número, como TC-14; um id ou um nome também funcionam. Status recebe aqui Passed ou Failed; o endpoint também aceita Blocked, In Progress e Not Run, e palavras de ferramentas de teste como pass e fail.
  • Um resultado que não pode ser registrado, como um número que o Holarch não tem, é listado em skipped com o motivo; os outros são registrados mesmo assim.
  • A alteração é registrada com o seu nome e vista na hora por todos com o projeto aberto.

Em uma tarefa de CI, execute o script como uma etapa após os testes, com o token como secret. No GitHub Actions, por exemplo:

      - 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() registra os resultados também quando os testes falham, que é quando eles mais importam.

Executar os testes e propor os resultados com o Claude

  1. No repositório que contém os testes, peça ao Claude Code, por exemplo: "Execute os testes de apontamento com um relatório JUnit. Depois proponha os resultados no projeto CubeSat do Holarch: defina Status e, para as falhas, Actual Result nos casos de teste correspondentes."
  2. O Claude Code executa os testes. No Holarch, ele acrescenta os resultados a uma proposta com record_test_results (uma alteração por resultado, com Status, Resultado real, Testado por e Data do teste). Depois envia a proposta com propose_changes.

    O Claude Code responde com o título da proposta, os resultados que propõe e um link para revisá-la.

  3. No Holarch, abra ✦ IA ▾ → Revisar “<título>”…, ou a notificação sob o sino.

    A caixa de diálogo mostra cada caso de teste com seus valores atuais e propostos.

  4. Desmarque qualquer resultado que você não aceite e clique em Aplicar selecionados.

    Os resultados são registrados com o seu nome no histórico, cada um com uma entrada no registro de execução como em Importar resultados…, e um único Desfazer reverte tudo.

  5. Pergunte ao Claude Code: "Quais requisitos do projeto CubeSat ainda falham na verificação?"

    O Claude Code lê a RVTM com get_matrix (matrix rvtm, status Failed) e lista cada requisito com os casos de teste que falham.

O Claude Code também pode trabalhar a partir de um relatório que a sua CI já gravou: anexe results.xml ou indique-o, em vez de pedir que ele execute os testes.

Exemplo prático: a demonstração CubeSat EO-1

  1. Crie a demonstração com Gerenciar projetos → Arquivos de projeto ▾ → Novo projeto de demonstração.

    Em Verificação → Central de testes, TC-14 Off-Nadir Imaging Test está Not Run e TC-04 Pointing Accuracy Test está Failed.

  2. Grave um relatório JUnit com dois testes: test_TC_14_off_nadir_imaging aprovado, e test_TC_04_pointing_accuracy com falha e a mensagem 0.12 degrees on 2 of 20 targets.
  3. Execute python3 junit_to_holarch.py results.xml.

    Você vê TC-14 Off-Nadir Imaging Test: Passed e TC-04 Pointing Accuracy Test: Failed.

  4. Abra Verificação → RVTM.

    1.6.2 Off-Nadir Imaging agora mostra Passed. 2.1 Pointing Accuracy ainda falha, e o Resultado real de TC-04 diz 0.12 degrees on 2 of 20 targets.

  5. Com o Claude, os mesmos resultados chegam primeiro como uma proposta. Depois de Aplicar selecionados, a RVTM mostra o mesmo.

Dicas

  • Registre os resultados nos casos de teste de nível mais baixo. Os pais são consolidados a partir dos filhos.
  • Mantenha o token do script limitado a um projeto e revogue-o quando o pipeline for desativado.
  • Um teste que cita um número que o Holarch não tem é listado como "nenhum caso de teste com este número". Corrija o nome do teste ou crie o caso de teste.
  • Salve um ciclo de teste na Central de testes quando uma campanha terminar, para que seus resultados fiquem separados da próxima execução (Salvar um ciclo de teste).

Solução de problemas

Mensagem ou sintomaCausa e solução
Holarch answered 401 token-invalidO token está errado, revogado ou expirado. Crie um novo em Ajustes da conta → Tokens de API.
Holarch answered 403 plan-apiO plano da conta não inclui a API e o MCP. Inicie a avaliação do Individual ou escolha um plano; o token então volta a funcionar.
Holarch answered 403 read-only-tokenO script grava resultados. Crie um token Leitura e escrita.
Holarch answered 403 forbiddenSeu papel no projeto é leitor ou revisor. Um proprietário pode torná-lo editor.
TC-14: not recorded (…)O Holarch não conseguiu registrar esse resultado, por exemplo porque o caso de teste está bloqueado ou tem casos de teste filhos. O motivo diz qual; os outros resultados são registrados.
TC-04: not recorded (… configuration control …)O caso de teste está sob controle de configuração. Registre o resultado dele no app por meio de uma solicitação de mudança.
Holarch answered 429 rate-limitedSolicitações demais por minuto. Aguarde os segundos indicados em Retry-After e execute o script novamente.
Um caso de teste mantém o status antigoUm caso de teste com filhos mostra o status consolidado dos filhos. Registre o resultado em um filho.
O Claude Code não oferece as ferramentas de escrita do HolarchA conexão é somente leitura. Execute /mcp, reconecte holarch com Ler e propor alterações e inicie uma nova conversa.