Abrufen der Axe Watcher-Ergebnisse mit axe-watcher-results

axe-watcher-results ruft die Ergebnisse eines abgeschlossenen Axe Watcher-Scans von Axe Developer Hub ab und wandelt sie in ein Bestehen-/Nichtbestehen-Signal für eine CI-Pipeline um.

Voraussetzungen

Bevor Sie axe-watcher-results ausführen, benötigen Sie:

• Eine Axe Developer Hub API-Schlüssel (eine UUID).
• Die Projekt-ID für das Axe Developer Hub-Projekt, an das der Scan gesendet wurde (eine UUID).
• Einen abgeschlossenen Axe Watcher-Scan für den zu überprüfenden Commit.

Installation

axe-watcher-results wird als eigenständige Binärdatei für Linux, macOS und Windows verteilt. Laden Sie die Binärdatei für Ihre Plattform von der Downloads-Seite herunter (Zugriff erfordert eine axe DevTools for Web-Berechtigung) und folgen Sie Vorbereitung der Binärdateien nach dem Download, um sie ausführbar zu machen und unter macOS das Quarantäne-Attribut zu entfernen.

Legen Sie die Binärdatei auf Ihrem PATH ab (oder verweisen Sie über den Pfad darauf), damit Sie sie als axe-watcher-results ausführen können.

Authentifizierung

axe-watcher-results liest Ihren Axe Developer Hub API-Schlüssel aus der AXE_DEVHUB_API_KEY-Umgebungsvariable. Setzen Sie diese einmal, bevor Sie einen Befehl ausführen — in Ihrer Shell für die lokale Nutzung oder im Geheimnisspeicher Ihres CI-Systems für eine Pipeline:

export AXE_DEVHUB_API_KEY=<your-api-key>

Die folgenden Beispiele gehen davon aus, dass diese Variable gesetzt ist.

Ergebnisse für einen Commit nachschlagen (CI-Gating)

Führen Sie axe-watcher-results sessions get mit Ihrer Projekt-ID und einem Git-Commit-SHA aus:

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

• <project-id>: die UUID des Projekts.
• <commit-sha>: eine 7-40 Zeichen lange Git-Commit-SHA, die bereits einen abgeschlossenen Axe Watcher-Scan hat.

Dies ist das Lookup, das einen Build steuert: Wenn die Anzahl der Probleme des Laufs Ihre Projekt-Barrierefreiheitsgrenze überschreitet, beendet axe-watcher-results mit Code 10 (siehe Exit-Codes). Zum Beispiel mit --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."
}

Wenn Sie die Ausgabe in einem Skript parsen, verwenden Sie --format=json: Die obigen Feldnamen sind stabil. Die standardmäßige --format=text-Ausgabe ist für Menschen gedacht, die Build-Protokolle lesen, nicht für das Parsen.

Ergebnisse für eine Sitzung nachschlagen

Sie können auch einen bestimmten Scan über seine Sitzungs-ID anstelle eines Commit-SHA nachschlagen:

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

<session-id> ist eine Sitzungs-UUID. axe-watcher-results unterscheidet eine Sitzungs-ID von einem Commit-SHA durch ihre Form (eine UUID im Vergleich zu einem 7-40 Zeichen langen Hex-String), sodass Sie sie an der gleichen Stelle übergeben. Das <project-id>-Argument ist weiterhin erforderlich und wird validiert, auch wenn ein Sitzungs-Lookup sein Projekt aus der Sitzung und dem API-Schlüssel und nicht aus dem Argument auflöst.

Verwenden Sie --detail=summary (standardmäßig) für Problemzählungen nach Schweregrad und Regel, oder --detail=full, um das vollständige Ergebnisdokument als rohes JSON zu erhalten (dies ignoriert --format).

--format=json --detail=summary sieht so aus:

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

Wenn der Scan noch verarbeitet wird, führt axe-watcher-results eine Abfrage des Servers durch (bis zu 5 Minuten) und schreibt den Fortschritt in stderr; wenn der Scan nicht rechtzeitig abgeschlossen wird, endet er mit Code 11.

Sitzungen für ein Projekt auflisten

Der sessions list-Unterbefehl listet die aufgezeichneten Scan-Sitzungen eines Projekts auf, was nützlich ist, um eine Sitzungs-ID zum Nachschlagen zu finden:

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

Filtern Sie die Ergebnisse mit --git-branch, --commit-sha, --git-url, --created-after/--created-before (ISO-8601-Zeitstempel), --created-by-user-email und --is-canonical-source. Verwenden Sie --page-size (1-100) und --after, um durch die Ergebnisse zu blättern. sessions list akzeptiert auch --format, --network-timeout-seconds und --verbose/-v, die sich gleich wie bei sessions get verhalten.

Optionen

Diese Optionen gelten für den sessions get-Befehl (Commit-SHA- und Sitzungs-ID-Nachschlagen):

--version (auf dem root axe-watcher-results Befehl) druckt die axe-watcher-results-Version und beendet; --help ist bei jedem Befehl verfügbar.

Die Ausgabe geht als Klartext oder JSON an stdout; Fortschritts- und Fehlermeldungen gehen an stderr, sodass Sie stdout für Build-Logs ohne zusätzliche Verarbeitung erfassen können.

CI-Gating-Beispiel

Führen Sie axe-watcher-results als Schritt aus, nachdem Ihr Axe-Watcher-Scan abgeschlossen ist, und verwenden Sie einen Commit-SHA, damit der exit-Code den a11y-Schwellenwert widerspiegelt:

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

Ein nicht-null-Exit schlägt den aufrufenden Schritt fehl. Siehe Exit-Codes, um zu verstehen, was jeder Code bedeutet und wie darauf zu reagieren ist.

Exit-Codes

Wiederherstellung von Exit 12

Exit 12 bedeutet, dass der Commit Scan-Ergebnisse hat, aber im Axe Developer Hub gibt es nichts, womit sie verglichen werden können. Axe Developer Hub wählt eine Basislinie in folgender Reihenfolge aus:

1. Eine frühere Sitzung mit demselben Commit-SHA.
2. Die jüngste Sitzung mit einem anderen SHA im selben Branch.
3. Die aktuelle Sitzung selbst, aber nur, wenn die Sitzung kanonisch ist (siehe Verwendung von Axe Watcher in Continuous-Integration-(CI)-Umgebungen).

Wenn keiner dieser Fälle verfügbar ist und die Sitzung nicht kanonisch ist, gibt Axe Developer Hub einen 404 aus und axe-watcher-results endet mit Code 12. Zur Wiederherstellung:

• Führen Sie den Axe Watcher-Scan erneut mit festgelegtem CI=true aus, damit die Sitzung kanonisch wird und sich bei einem Kaltstart selbst vergleicht.
• Führen Sie einen zusätzlichen Scan durch, entweder gegen diesen oder einen früheren Commit im selben Branch, um eine Basislinie zu erstellen.