Recuperare i Risultati di Axe Watcher con axe-watcher-results

axe-watcher-results recupera i risultati di una scansione completata di Axe Watcher da Axe Developer Hub e li trasforma in un segnale di successo/fallimento per una pipeline CI.

Prerequisiti

Prima di eseguire axe-watcher-results, hai bisogno di:

• Un Chiave API di Axe Developer Hub (un UUID).
• L'ID progetto per il progetto Axe Developer Hub a cui è stata inviata la scansione (un UUID).
• Una scansione di Axe Watcher completata per il commit che desideri controllare.

Installare

axe-watcher-results è distribuito come un binario auto-contenuto per Linux, macOS e Windows. Scarica il binario per la tua piattaforma dalla pagina Download (l'accesso richiede un abbonamento a axe DevTools for Web), poi segui Preparazione dei Binari dopo il Download per renderlo eseguibile e, su macOS, per eliminare l'attributo di quarantena.

Posiziona il binario sul tuo PATH (o riferimento tramite percorso) così da poterlo eseguire come axe-watcher-results.

Autenticazione

axe-watcher-results legge la tua chiave API di Axe Developer Hub dalla variabile di ambiente AXE_DEVHUB_API_KEY. Impostala una volta prima di eseguire qualsiasi comando — nel tuo terminale per uso locale, o nel negozio segreto del tuo sistema CI per una pipeline:

export AXE_DEVHUB_API_KEY=<your-api-key>

Gli esempi sotto assumono che questa variabile sia impostata.

Consulta i Risultati per un Commit (CI Gating)

Esegui axe-watcher-results sessions get con il tuo ID progetto e un SHA di commit Git:

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

• <project-id>: l'UUID del progetto.
• <commit-sha>: un SHA di commit Git di 7-40 caratteri che ha già una scansione di Axe Watcher completata.

Questa è la ricerca che blocca una build: se il numero di problemi dell'esecuzione supera la soglia di accessibilità del tuo progetto, axe-watcher-results termina con il codice 10 (vedi Codici di Uscita). Ad esempio, 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."
}

Se analizzi l'output in uno script, utilizza --format=json: i nomi dei campi sopra sono stabili. L'output predefinito --format=text è destinato agli umani che leggono i log delle build, non per l'analisi.

Consulta i Risultati per una Sessione

Puoi anche consultare una scansione specifica tramite il suo ID sessione invece di uno SHA di commit:

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

<session-id> è un UUID di sessione. axe-watcher-results distingue un ID sessione da uno SHA di commit dalla sua forma (un UUID rispetto a una stringa esadecimale di 7-40 caratteri), quindi lo passi nella stessa posizione. L'argomento <project-id> è comunque richiesto e validato, anche se una ricerca di sessione risolve il suo progetto dalla sessione e dalla chiave API piuttosto che dall'argomento.

Utilizza --detail=summary (l'impostazione predefinita) per i conteggi dei problemi per gravità e regole, o --detail=full per ottenere il documento completo del risultato come JSON grezzo (questo ignora --format).

--format=json --detail=summary appare così:

{
  "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
      }
    ]
  }
}

Se la scansione è ancora in elaborazione, axe-watcher-results interroga il server (fino a 5 minuti) e scrive i progressi su stderr; se la scansione non termina in tempo, esce con il codice 11.

Elenca le sessioni per un progetto

Il sottocomando sessions list elenca le sessioni di scansione registrate di un progetto, utile per trovare un ID sessione da cercare:

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

Filtra i risultati con --git-branch, --commit-sha, --git-url, --created-after/--created-before (timestamp ISO-8601), --created-by-user-email e --is-canonical-source. Utilizza --page-size (1-100) e --after per sfogliare i risultati. sessions list accetta anche --format, --network-timeout-seconds e --verbose/-v, che si comportano allo stesso modo di sessions get.

Opzioni

Queste opzioni si applicano al comando sessions get (ricerche commit-SHA e ID sessione):

--version (sul comando radice axe-watcher-results) stampa la versione axe-watcher-results ed esce; --help è disponibile su ogni comando.

L'output va a stdout come testo pulito o JSON; i messaggi di progresso e errore vanno a stderr, quindi puoi catturare stdout per i log di build senza analisi extra.

Esempio di blocco CI

Esegui axe-watcher-results come passaggio dopo che la tua scansione di Axe Watcher è completata, utilizzando un commit SHA in modo che il codice di uscita rifletta la soglia di 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'uscita non-zero interrompe il passaggio chiamante. Vedi Codici di uscita per cosa significa ogni codice e come rispondervi.

Codici di uscita

Recupero dall'uscita 12

Uscita 12 significa che il commit ha risultati di scansione, ma Axe Developer Hub non ha nulla con cui confrontarli. Axe Developer Hub seleziona una baseline in questo ordine:

1. Una sessione precedente sullo stesso commit SHA.
2. La sessione più recente su un altro SHA dello stesso branch.
3. La sessione attuale stessa, ma solo se la sessione è canonica (vedi Usa Axe Watcher in ambienti di Continuous Integration (CI)).

Se nessuna di queste è disponibile e la sessione non è canonica, Axe Developer Hub restituisce un 404 e axe-watcher-results esce con il codice 12. Per recuperare:

• Rieseguire la scansione di Axe Watcher con CI=true impostato, in modo che la sessione diventi canonica e si confronti autonomamente in un avvio a freddo.
• Eseguire una scansione aggiuntiva, su questo commit o su un commit precedente dello stesso branch, per stabilire una baseline.