Récupérer les Résultats de Axe Watcher avec axe-watcher-results

axe-watcher-results récupère les résultats d'une analyse complète de Axe Watcher depuis le Axe Developer Hub et les transforme en un signal de réussite/échec pour un pipeline CI.

Pré-requis

Avant d'exécuter axe-watcher-results, vous avez besoin de :

• Un Clé API Axe Developer Hub (un UUID).
• Le ID de projet pour le projet Axe Developer Hub auquel l'analyse a été envoyée (un UUID).
• Une analyse complète de Axe Watcher pour le commit que vous souhaitez vérifier.

Installation

axe-watcher-results est distribué sous forme de binaire autonome pour Linux, macOS et Windows. Téléchargez le binaire pour votre plateforme depuis la page Téléchargements (l'accès nécessite un droit axe DevTools pour le Web), puis suivez Préparation des Binaries après Téléchargement pour le rendre exécutable et, sur macOS, pour effacer l'attribut de quarantaine.

Placez le binaire sur votre PATH (ou référencez-le par son chemin) afin de pouvoir l'exécuter en tant que axe-watcher-results.

Authentification

axe-watcher-results lit votre clé API Axe Developer Hub depuis la variable d'environnement AXE_DEVHUB_API_KEY. Réglez-la une fois avant d'exécuter une commande : dans votre shell pour une utilisation locale, ou dans le magasin de secrets de votre système CI pour un pipeline :

export AXE_DEVHUB_API_KEY=<your-api-key>

Les exemples ci-dessous supposent que cette variable est définie.

Consulter les Résultats pour un Commit (Blocage CI)

Exécutez axe-watcher-results sessions get avec votre ID de projet et un SHA de commit Git :

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

• <project-id> : l'UUID du projet.
• <commit-sha> : un SHA de commit Git de 7 à 40 caractères qui a déjà une analyse complète de Axe Watcher.

Il s'agit de la consultation qui bloque une construction : si le nombre de problèmes du run dépasse le seuil d'accessibilité de votre projet, axe-watcher-results se termine avec le code 10 (voir Codes de Sortie). Par exemple, avec --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 vous analysez la sortie dans un script, utilisez --format=json : les noms de champs ci-dessus sont stables. La sortie par défaut --format=text est destinée aux humains lisant les journaux de construction, pas pour analyse.

Consulter les Résultats pour une Session

Vous pouvez également consulter une analyse spécifique par son ID de session au lieu d'un SHA de commit :

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

<session-id> est un UUID de session. axe-watcher-results distingue un ID de session d'un SHA de commit par sa forme (un UUID contre une chaîne hexadécimale de 7 à 40 caractères), vous le passez donc dans la même position. L'argument <project-id> est toujours nécessaire et validé, même si une consultation de session résout son projet depuis la session et la clé API plutôt que depuis l'argument.

Utilisez --detail=summary (par défaut) pour obtenir le dénombrement des problèmes par gravité et règle, ou --detail=full pour obtenir le document de résultats complet en tant que JSON brut (cela ignore --format).

--format=json --detail=summary ressemble à ceci :

{
  "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 l'analyse est encore en cours de traitement, axe-watcher-results interroge le serveur (jusqu'à 5 minutes) et écrit l'avancement sur stderr ; si l'analyse ne se termine pas à temps, elle se termine avec le code 11.

Lister les sessions pour un projet

La sous-commande sessions list liste les sessions d'analyse enregistrées pour un projet, ce qui est utile pour trouver un ID de session à consulter :

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

Filtrez les résultats avec --git-branch, --commit-sha, --git-url, --created-after/--created-before (timestamps ISO-8601), --created-by-user-email, et --is-canonical-source. Utilisez --page-size (1-100) et --after pour parcourir les résultats. sessions list accepte également --format, --network-timeout-seconds et --verbose/-v, qui se comportent de la même manière pour sessions get.

Options

Ces options s'appliquent à la commande sessions get (recherches de commit-SHA et ID de session) :

--version (sur la commande axe-watcher-results principale) imprime la version axe-watcher-results et sort ; --help est disponible sur toutes les commandes.

La sortie va sur stdout en texte clair ou JSON ; les messages de progression et d'erreur vont sur stderr, afin que vous puissiez capturer stdout pour les journaux de construction sans analyse supplémentaire.

Exemple de validation CI

Exécutez axe-watcher-results comme une étape après que votre analyse Axe Watcher soit terminée, en utilisant un SHA de validation afin que le code de sortie reflète le seuil d'accessibilité :

# 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 code de sortie non nul échoue à l'étape appelante. Voir Codes de sortie pour savoir ce que signifie chaque code et comment y répondre.

Codes de sortie

Récupération de l'erreur 12

L'erreur 12 signifie que le commit a des résultats d'analyse, mais Axe Developer Hub n'a rien à comparer. Axe Developer Hub sélectionne une référence dans cet ordre :

1. Une session antérieure sur le même SHA de commit.
2. La session la plus récente sur un SHA différent dans la même branche.
3. La session actuelle elle-même, mais uniquement si la session est canonique (voir Utiliser Axe Watcher dans des environnements d'intégration continue (CI)).

Si aucune de ces options n'est disponible et que la session n'est pas canonique, Axe Developer Hub renvoie un 404 et axe-watcher-results se termine avec le code 12. Pour récupérer :

• Rerunnez l'analyse Axe Watcher avec CI=true activé, afin que la session devienne canonique et se compare elle-même au démarrage à froid.
• Effectuez une analyse supplémentaire, sur ce commit ou un commit antérieur dans la même branche, pour créer une référence.