Recuperar resultados de Axe Watcher con axe-watcher-results

axe-watcher-results recupera los resultados de un escaneo completado de Axe Watcher desde Axe Developer Hub y los convierte en una señal de aprobación/rechazo para una tubería de CI.

Prerrequisitos

Antes de ejecutar axe-watcher-results, necesita:

• Un Clave API de Axe Developer Hub (un UUID).
• El ID de proyecto para el proyecto de Axe Developer Hub al que se envió el escaneo (un UUID).
• Un escaneo de Axe Watcher completado para el commit que desea verificar.

Instalación

axe-watcher-results se distribuye como un binario autónomo para Linux, macOS y Windows. Descargue el binario para su plataforma desde la página de Descargas (el acceso requiere una licencia de axe DevTools for Web), luego siga Preparación de Binarios después de la Descarga para hacerlo ejecutable y, en macOS, eliminar el atributo de cuarentena.

Coloque el binario en su PATH (o refiéralo por su ruta) para que pueda ejecutarlo como axe-watcher-results.

Autenticación

axe-watcher-results lee su clave API de Axe Developer Hub de la variable de entorno AXE_DEVHUB_API_KEY. Establézcala una vez antes de ejecutar cualquier comando: en su consola para uso local, o en el almacén de secretos de su sistema CI para una tubería:

export AXE_DEVHUB_API_KEY=<your-api-key>

Los ejemplos a continuación suponen que esta variable está establecida.

Buscar Resultados para un Commit (Bloqueo de CI)

Ejecute axe-watcher-results sessions get con su ID de proyecto y un SHA de commit de Git:

axe-watcher-results sessions get <project-id> <commit-sha>

• <project-id>: el UUID del proyecto.
• <commit-sha>: un SHA de commit de Git de 7 a 40 caracteres que ya tiene un escaneo de Axe Watcher completado.

Esta es la búsqueda que bloquea una construcción: si el conteo de problemas del run supera el umbral de accesibilidad de su proyecto, axe-watcher-results sale con el código 10 (consulte Códigos de salida). Por ejemplo, con --format=json:

{
  "project": "your-project-name",
  "project-id": "7347af86-ff4e-4e14-8957-8fc2255ed4ec",
  "commit-sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
  "run-url": "https://axe.deque.com/axe-watcher/projects/7347af86-ff4e-4e14-8957-8fc2255ed4ec/branches/main/compare/0d4a85a2-9e6f-44ef-b814-fee8412abeb0/0d4a85a2-9e6f-44ef-b814-fee8412abeb0?settings_hash=0757ca72c5e10951ddbb2ede4edab06e&issues_over_a11y_threshold=2",
  "issues": 17,
  "new-issues": 17,
  "resolved-issues": 0,
  "issues-over-a11y-threshold": 2,
  "page-states": 2,
  "difference-in-page-states": 0,
  "created-at": "2026-07-07T18:13:00.641Z",
  "message": "Run exceeded the a11y threshold by 2."
}

Si analiza la salida en un script, use --format=json: los nombres de campo anteriores son estables. La salida --format=text predeterminada está destinada para que los humanos lean los registros de construcción, no para su análisis.

Buscar Resultados para una Sesión

También puede buscar un escaneo específico por su ID de sesión en lugar de un SHA de commit:

axe-watcher-results sessions get <project-id> <session-id>

<session-id> es un UUID de sesión. axe-watcher-results distingue un ID de sesión de un SHA de commit por su forma (un UUID frente a un string hexadecimal de 7 a 40 caracteres), por lo que puede pasarlo en la misma posición. El argumento <project-id> todavía se requiere y valida, aunque una búsqueda de sesión resuelve su proyecto desde la sesión y clave API en lugar de desde el argumento.

Use --detail=summary (el predeterminado) para conteos de problemas por severidad y regla, o --detail=full para obtener el documento completo de resultados como JSON bruto (esto ignora --format).

--format=json --detail=summary se ve así:

{
  "report_id": "14c16b50-a6ce-46ab-9974-0ad3b94eafde",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "4.0.0"
  },
  "test_details": {
    "test_id": "0d4a85a2-9e6f-44ef-b814-fee8412abeb0",
    "start_date": "2026-07-07T18:13:00.641Z",
    "end_date": "2026-07-07T18:13:05.472Z"
  },
  "commit": {
    "sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
    "author": "Jane Doe",
    "author_email": "jane@example.com",
    "message": "fix: correct login form labels",
    "branch_name": "main",
    "tag": "",
    "repository_url": "https://github.com/your-org/your-repo"
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.11/color-contrast?application=axeAPI",
        "count": 2
      }
    ]
  }
}

Si el análisis todavía se está procesando, axe-watcher-results consulta el servidor (hasta 5 minutos) y escribe el avance en stderr; si el análisis no finaliza el procesamiento a tiempo, sale con el código 11.

Listar sesiones para un proyecto

El subcomando sessions list lista las sesiones de análisis registradas de un proyecto, lo que es útil para encontrar un ID de sesión para buscar:

axe-watcher-results sessions list <project-id>

Filtra los resultados con --git-branch, --commit-sha, --git-url, --created-after/--created-before (timestamps ISO-8601), --created-by-user-email y --is-canonical-source. Usa --page-size (1-100) y --after para paginar los resultados. sessions list también acepta --format, --network-timeout-seconds y --verbose/-v, que se comportan igual que para sessions get.

Opciones

Estas opciones se aplican al comando sessions get (búsquedas por commit-SHA y ID de sesión):

--version (en el comando raíz axe-watcher-results) imprime la versión de axe-watcher-results y sale; --help está disponible en todos los comandos.

La salida se envía a stdout como texto limpio o JSON; los mensajes de progreso y error se envían a stderr, para que puedas capturar stdout para registros de compilación sin análisis adicional.

Ejemplo de control en CI

Ejecuta axe-watcher-results como un paso después de que tu análisis de Axe Watcher se complete, utilizando un commit SHA para que el código de salida refleje el umbral de accesibilidad:

# AXE_DEVHUB_API_KEY is provided by your CI system's secret store
axe-watcher-results sessions get --format=json "$PROJECT_ID" "$GIT_COMMIT_SHA"

Un código de salida distinto de cero falla en el paso que lo llama. Consulta Códigos de salida para entender qué significa cada código y cómo responder.

Códigos de salida

Recuperación del Salida 12

Salida 12 significa que el commit tiene resultados de escaneo, pero Axe Developer Hub no tiene nada con qué compararlos. Axe Developer Hub selecciona una línea base en este orden:

1. Una sesión anterior en el mismo SHA del commit.
2. La sesión más reciente en un SHA diferente dentro de la misma rama.
3. La sesión actual en sí misma, pero solo si la sesión es canónica (ver Use Axe Watcher en entornos de Integración Continua (CI)).

Si ninguno de estos está disponible y la sesión no es canónica, Axe Developer Hub devuelve un 404 y axe-watcher-results sale con el código 12. Para recuperar:

• Vuelva a ejecutar el escaneo de Axe Watcher con CI=true configurado, para que la sesión se vuelva canónica y se compare consigo misma en un inicio en frío.
• Ejecute un escaneo adicional, contra este commit o un commit anterior en la misma rama, para generar una línea base.