Haal Axe Watcher-resultaten op met axe-watcher-results

axe-watcher-results haalt de resultaten op van een voltooide Axe Watcher-scan van Axe Developer Hub en verandert ze in een slaag-/faalsignaal voor een CI-pijplijn.

Vereisten

Voordat je axe-watcher-results uitvoert, heb je het volgende nodig:

• Een Axe Developer Hub API-sleutel (een UUID).
• De project-ID voor het Axe Developer Hub-project waarnaar de scan is verzonden (een UUID).
• Een voltooide Axe Watcher-scan voor de commit die je wilt controleren.

Installeren

axe-watcher-results wordt verspreid als een zelfstandige binary voor Linux, macOS en Windows. Download de binary voor jouw platform van de Downloads-pagina (toegang vereist een axe DevTools voor Web-recht), volg dan Binaries voorbereiden na downloaden om het uitvoerbaar te maken en, op macOS, de quarantainetoestand te wissen.

Plaats de binary op je PATH (of verwijs ernaar via pad) zodat je het kunt uitvoeren als axe-watcher-results.

Verifiëren

axe-watcher-results leest je Axe Developer Hub API-sleutel uit de AXE_DEVHUB_API_KEY-omgevingsvariabele. Stel deze één keer in voordat je een commando uitvoert — in je shell voor lokaal gebruik, of in de geheimenopslag van je CI-systeem voor een pijplijn:

export AXE_DEVHUB_API_KEY=<your-api-key>

De onderstaande voorbeelden gaan ervan uit dat deze variabele is ingesteld.

Resultaten voor een Commit opzoeken (CI Gating)

Voer axe-watcher-results sessions get uit met je project-ID en een Git-commit SHA:

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

• <project-id>: de UUID van het project.
• <commit-sha>: een Git-commit SHA van 7-40 tekens die al een voltooide Axe Watcher-scan heeft.

Dit is de lookup die een build blokkeert: als het aantal problemen van de uitvoering je toegankelijkheidsdrempel overschrijdt, sluit axe-watcher-results af met code 10 (zie Afsluitcodes). Bijvoorbeeld, met --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."
}

Als je de output in een script verwerkt, gebruik dan --format=json: de hierboven genoemde veldnamen zijn stabiel. De standaard --format=text-output is bedoeld voor mensen die buildlogs lezen, niet voor parsing.

Resultaten voor een Sessie opzoeken

Je kunt ook een specifieke scan opzoeken via zijn sessie-ID in plaats van een commit SHA:

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

<session-id> is een sessie-UUID. axe-watcher-results onderscheidt een sessie-ID van een commit SHA op basis van de vorm (een UUID versus een hexadecimale tekenreeks van 7-40 tekens), dus je geeft het door op dezelfde positie. Het <project-id>-argument is nog steeds vereist en wordt gevalideerd, hoewel een sessiezoekopdracht zijn project afleidt van de sessie en API-sleutel in plaats van van het argument.

Gebruik --detail=summary (de standaard) voor probleemcijfers op ernstige en regelbasis, of --detail=full om het volledige resultaatdocument als ruwe JSON te krijgen (dit negeert --format).

--format=json --detail=summary ziet er als volgt uit:

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

Als de scan nog bezig is, pollt axe-watcher-results de server (tot 5 minuten) en schrijft de voortgang naar stderr; als de scan niet op tijd klaar is, beëindigt het met code 11.

Lijst van sessies voor een project

De sessions list subopdracht geeft een lijst van de opgenomen scansessies van een project, wat nuttig is om een sessie-ID te vinden om op te zoeken:

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

Filter de resultaten met --git-branch, --commit-sha, --git-url, --created-after/--created-before (ISO-8601 timestamps), --created-by-user-email en --is-canonical-source. Gebruik --page-size (1-100) en --after om door resultaten te bladeren. sessions list accepteert ook --format, --network-timeout-seconds, en --verbose/-v, die op dezelfde manier werken als voor sessions get.

Opties

Deze opties zijn van toepassing op de sessions get-opdracht (commit-SHA- en sessie-ID-opzoekingen):

--version (op de hoofd axe-watcher-results opdracht) print de axe-watcher-results versie en beëindigt; --help is beschikbaar bij elke opdracht.

Uitvoer gaat naar stdout als schone tekst of JSON; voortgangs- en foutmeldingen gaan naar stderr, zodat u stdout kunt vastleggen voor bouwlogboeken zonder extra parsing.

CI-beveiligingsvoorbeeld

Voer axe-watcher-results uit als een stap nadat uw Axe Watcher-scan is voltooid, met behulp van een commit SHA zodat de exitcode de a11y-drempel weerspiegelt:

# 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"

Een niet-nul exit laat de aanroepende stap mislukken. Zie Exitcodes voor wat elke code betekent en hoe erop te reageren.

Exitcodes

Herstel van Exit 12

Exit 12 betekent dat de commit scanresultaten heeft, maar Axe Developer Hub niets heeft om ze mee te vergelijken. Axe Developer Hub selecteert een basislijn in deze volgorde:

1. Een eerdere sessie op dezelfde commit SHA.
2. De meest recente sessie op een andere SHA op dezelfde branch.
3. De huidige sessie zelf, maar alleen als de sessie canoniek is (zie Gebruik Axe Watcher in omgevingen voor continue integratie (CI)).

Als geen van deze beschikbaar is en de sessie niet canoniek is, geeft Axe Developer Hub een 404 terug en axe-watcher-results beëindigt met code 12. Om te herstellen:

• Voer de Axe Watcher-scan opnieuw uit met CI=true ingesteld, zodat de sessie canoniek wordt en zichzelf vergelijkt bij een koude start.
• Voer een extra scan uit, tegen deze commit of een eerdere commit op dezelfde branch, om een basislijn te creëren.