Holarch

Referencia

Receta: resultados de prueba a través de Claude

Lleve los resultados de un sistema de pruebas a los casos de prueba de Holarch, con un script REST para CI o con Claude, que ejecuta las pruebas, propone los resultados para su revisión e informa de lo que muestra la RVTM; configuración, un script, un ejemplo práctico y solución de problemas.

Cómo usarlo →

En esta página
  1. Resumen
  2. Requisitos previos
  3. Cómo usarlo
    1. Cuándo y por qué
    2. Nombrar el caso de prueba en cada prueba
    3. Registrar resultados desde CI
    4. Ejecutar las pruebas y proponer los resultados con Claude
    5. Ejemplo práctico: la demostración CubeSat EO-1
    6. Consejos
  4. Solución de problemas
  5. Páginas relacionadas

Resumen

Esta receta registra los resultados de un sistema de pruebas automatizado en los casos de prueba correspondientes de Holarch, para que la RVTM muestre qué requisitos se cumplen. Tiene dos partes:

  • Resultados desde CI (API REST): un script lee el informe JUnit XML que escriben la mayoría de los ejecutores de pruebas y registra cada resultado en el caso de prueba correspondiente: Estado, Resultado real, Probado por, Fecha de prueba y una entrada en el registro de ejecuciones.
  • Resultados a través de Claude (MCP): Claude Code ejecuta las pruebas, asocia los resultados a los casos de prueba y propone los resultados para que usted los revise en Holarch. Después lee la RVTM y le indica qué requisitos siguen fallando.

Para importar a mano un archivo de resultados, use en su lugar Verificación → Centro de pruebas → Importar resultados… (Importar resultados de otro sistema de pruebas). La API REST y MCP registran los resultados de la misma forma: Probado por, Fecha de prueba y una entrada en el registro de ejecuciones de cada caso de prueba.

Requisitos previos

  • Un plan con la API y MCP: Individual o Team, o la prueba de Individual. En el plan Free, una cuenta con una dirección de correo académica verificada o en una organización de clase activa también los tiene (Planes y límites).
  • Un proyecto de Holarch con casos de prueba cuyos números puedan nombrar las pruebas, como TC-14. Necesita el rol de editor o de propietario.
  • Para el script: un token de Lectura y escritura limitado al proyecto (Ajustes de la cuenta → Tokens de API → Nuevo token, Crear un token), y Python 3.9 o posterior con el paquete requests (python3 -m pip install requests).
  • Para la parte de Claude: Claude Code conectado a Holarch con el acceso Leer y proponer cambios (Conectar Holarch a Claude), en el repositorio que contiene las pruebas.
  • Un ejecutor de pruebas que escriba JUnit XML, como pytest --junitxml=results.xml, o la mayoría de los pasos de prueba de CI.

Cómo usarlo

Cuándo y por qué

La verificación cierra el ciclo del requisito a la evidencia. Cuando las pruebas se ejecutan automáticamente, escribir sus resultados en Holarch a mano es lento y propenso a errores. Use el script cuando los resultados deban entrar sin revisión, como en las ejecuciones de regresión nocturnas. Use Claude cuando una persona deba ver los resultados antes de que se registren, como en una ejecución de cualificación.

Nombrar el caso de prueba en cada prueba

El script y Claude asocian una prueba a un caso de prueba de Holarch por el número del caso de prueba que figura en el nombre de la prueba.

  1. Ponga el número en el nombre de la prueba: test_TC_14_off_nadir_imaging en pytest, o TC-14 off-nadir imaging en otros ejecutores.
  2. Mantenga un caso de prueba de Holarch por prueba. Un caso de prueba con casos de prueba hijos toma su estado de sus hijos; registre los resultados en los hijos.

Registrar resultados desde CI

El script registra Passed o Failed en cada caso de prueba asociado, en una sola solicitud. Para un fallo también registra el mensaje de fallo como Resultado real. Las pruebas omitidas no se modifican.

# 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. Establezca las variables de entorno HOLARCH_TOKEN (el token) y HOLARCH_PROJECT (el id del proyecto de GET /api/v1/projects).
  2. Ejecute sus pruebas con un informe JUnit, como pytest --junitxml=results.xml.
  3. Ejecute python3 junit_to_holarch.py results.xml.

    Verá una línea por cada resultado registrado, como TC-14 Off-Nadir Imaging Test: Passed.

  4. En Holarch, abra Verificación → RVTM.

    Los requisitos que verifican esos casos de prueba muestran el estado nuevo.

Cómo funciona:

  • POST /api/v1/projects/<project>/test-results registra todos los resultados del informe como un solo cambio, como hace Importar resultados…: Estado, Resultado real para los fallos, Probado por (aquí CI; el nombre de su cuenta si se omite), Fecha de prueba (la hora de la solicitud) y una entrada en el registro de ejecuciones con source establecido en el nombre de archivo del informe (Resultados de prueba).
  • testCase nombra el caso de prueba por su número, como TC-14; también sirven un id o un nombre. Estado toma aquí Passed o Failed; el endpoint también acepta Blocked, In Progress y Not Run, y palabras de las herramientas de pruebas como pass y fail.
  • Un resultado que no se puede registrar, como un número que Holarch no tiene, se enumera en skipped con su motivo; los demás se registran igualmente.
  • El cambio se registra con su nombre y todos los que tienen el proyecto abierto lo ven al instante.

En un trabajo de CI, ejecute el script como un paso después de las pruebas, con el token como secreto. En GitHub Actions, por ejemplo:

      - 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 los resultados también cuando las pruebas fallan, que es cuando más importan.

Ejecutar las pruebas y proponer los resultados con Claude

  1. En el repositorio que contiene las pruebas, pida a Claude Code, por ejemplo: «Ejecuta las pruebas de apuntamiento con un informe JUnit. Después propón sus resultados en el proyecto CubeSat de Holarch: establece Status y, para los fallos, Actual Result en los casos de prueba correspondientes.»
  2. Claude Code ejecuta las pruebas. En Holarch añade los resultados a una propuesta con record_test_results (un cambio por resultado, con Estado, Resultado real, Probado por y Fecha de prueba). Después envía la propuesta con propose_changes.

    Claude Code responde con el título de la propuesta, los resultados que propone y un enlace para revisarla.

  3. En Holarch, abra ✦ IA ▾ → Revisar «<título>»…, o la notificación de la campana.

    El cuadro de diálogo muestra cada caso de prueba con sus valores actuales y propuestos.

  4. Desmarque cualquier resultado que no acepte y haga clic en Aplicar seleccionados.

    Los resultados se registran con su nombre en el historial, cada uno con una entrada en el registro de ejecuciones como desde Importar resultados…, y un solo Deshacer lo revierte todo.

  5. Pregunte a Claude Code: «¿Qué requisitos del proyecto CubeSat siguen sin superar la verificación?»

    Claude Code lee la RVTM con get_matrix (matrix rvtm, status Failed) y enumera cada requisito con sus casos de prueba fallidos.

Claude Code también puede trabajar a partir de un informe que su CI ya escribió: adjúntele results.xml o indíquele dónde está en lugar de pedirle que ejecute las pruebas.

Ejemplo práctico: la demostración CubeSat EO-1

  1. Cree la demo con Gestionar proyectos → Archivos de proyecto ▾ → Nuevo proyecto de demostración.

    En Verificación → Centro de pruebas, TC-14 Off-Nadir Imaging Test está en Not Run y TC-04 Pointing Accuracy Test en Failed.

  2. Escriba un informe JUnit con dos pruebas: test_TC_14_off_nadir_imaging superada, y test_TC_04_pointing_accuracy fallida con el mensaje 0.12 degrees on 2 of 20 targets.
  3. Ejecute python3 junit_to_holarch.py results.xml.

    Verá TC-14 Off-Nadir Imaging Test: Passed y TC-04 Pointing Accuracy Test: Failed.

  4. Abra Verificación → RVTM.

    1.6.2 Off-Nadir Imaging muestra ahora Passed. 2.1 Pointing Accuracy sigue fallando, y el Resultado real de TC-04 dice 0.12 degrees on 2 of 20 targets.

  5. Con Claude, los mismos resultados llegan primero como propuesta. Después de Aplicar seleccionados, la RVTM muestra lo mismo.

Consejos

  • Registre los resultados en los casos de prueba de nivel más bajo. Los padres se agregan a partir de sus hijos.
  • Mantenga el token del script limitado a ese único proyecto, y revóquelo cuando la canalización se retire.
  • Una prueba que nombra un número que Holarch no tiene aparece como «no test case with this number» (ningún caso de prueba con este número). Corrija el nombre de la prueba o cree el caso de prueba.
  • Guarde un ciclo de prueba en el Centro de pruebas cuando termine una campaña, para que sus resultados se mantengan separados de la siguiente ejecución (Guardar un ciclo de prueba).

Solución de problemas

Mensaje o síntomaCausa y solución
Holarch answered 401 token-invalidEl token es incorrecto, está revocado o caducado. Cree uno nuevo en Ajustes de la cuenta → Tokens de API.
Holarch answered 403 plan-apiEl plan de la cuenta no incluye la API ni MCP. Inicie la prueba de Individual o elija un plan; el token vuelve entonces a funcionar.
Holarch answered 403 read-only-tokenEl script escribe resultados. Cree un token de Lectura y escritura.
Holarch answered 403 forbiddenSu rol en el proyecto es lector o revisor. Un propietario puede hacerle editor.
TC-14: not recorded (…)Holarch no pudo registrar ese resultado, por ejemplo porque el caso de prueba está bloqueado o tiene casos de prueba hijos. El motivo indica cuál; los demás resultados se registran.
TC-04: not recorded (… configuration control …)El caso de prueba está bajo control de configuración. Registre su resultado en la aplicación mediante una solicitud de cambio.
Holarch answered 429 rate-limitedDemasiadas solicitudes por minuto. Espere los segundos indicados en Retry-After y vuelva a ejecutar el script.
Un caso de prueba conserva su estado anteriorUn caso de prueba con hijos muestra el estado agregado de sus hijos. Registre el resultado en un hijo.
Claude Code no ofrece las herramientas de escritura de HolarchLa conexión es de solo lectura. Ejecute /mcp, vuelva a conectar holarch con Leer y proponer cambios y después inicie una conversación nueva.