Verwendung der GitHub Action für Axe Developer Hub

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Automatische Überprüfung von PRs und Commits auf Barrierefreiheitsfehler

Not for use with personal data

Erfordert:

Ein Webprojekt mit Axe Watcher-Integration

Axe Developer Hub-Projekt-ID

Axe Developer Hub API-Schlüssel

Eine Test-Suite, die Sie modifiziert haben, indem Sie den Setup-Anweisungen im Axe Developer Hub gefolgt sind

Ein GitHub-Workflow, der Ihre Test-Suite bei jedem Commit in Ihr Repository ausführt

note

Für andere CI/CD-Pipelines (wie jene auf GitLab, Bitbucket oder CircleCI) oder bei der Verwendung von Axe DevTools für Web-APIs/CLI können Sie den Axe Developer Hub REST-Dienst als Basis für Ihre eigene Integration verwenden.

Übersicht

Die Axe Developer Hub GitHub Action ermöglicht es Ihnen, GitHub-Workflows für Webprojekte einzurichten, die Axe Watcher integrieren, um Commits und Pull-Requests zu blockieren, wenn sie Zugänglichkeitsfehler enthalten.

Wenn Ihr modifizierte Test-Suite läuft, verknüpft er die Zugänglichkeitsergebnisse mit einer Git-Commit-SHA und sendet diese Informationen an die Server von Deque. Die GitHub-Aktion läuft nach Ihr Test-Set läuft und fragt die Server von Deque nach den Zugänglichkeitsergebnissen, die mit dem neuesten Commit-SHA des aktuellen Branches verknüpft sind.

Die neuen und abgeschlossenen Problemzählungen, die die Aktionsberichte verwenden, nutzen die Basislinie des vorherigen Commits, der einen Scan auf demselben Branch hat, nicht auf dem Standard-Branch. Nur für Commits, gegen die Ihre Test-Suite tatsächlich gelaufen ist, gibt es einen Scan, daher kann dieser Basis-Commit mehrere Commits zurückliegen. Wenn dieser Commit einen anderen Satz von Tests durchführte, spiegeln die Zählungen den Abdeckungsunterschied wider, anstatt eine echte Änderung; siehe Beste Praktiken für genaue Vergleiche.

Einrichtung

Erstellen Sie eine Umgebungsvariable für Ihre Projekt-ID - Wir empfehlen, dass Sie Ihre Projekt-ID in einer Umgebungsvariable oder einer anderen GitHub-Variable speichern. Für dieses Beispiel speichern wir die Projekt-ID als Umgebungsvariable namens PROJECT_ID.
Erstellen Sie ein Geheimnis für Ihren API-Schlüssel - In diesem Beispiel wird das erstellte Geheimnis AXE_DEV_HUB_API_KEY genannt, mit Ihrem persönlichen API-Schlüssel als Wert. Sie können das Geheimnis aber benennen, wie Sie möchten. Es muss im Workflow-Job unter demselben Namen referenziert werden. Ihr API-Schlüssel ist eine Anmeldeinformation: Speichern Sie ihn immer als GitHub Actions-Geheimnis und nicht als fest codierten Wert in der Workflow-Datei.
Fügen Sie Barrierefreiheitsprüfungen zu Ihrer Test-Suite hinzu - Stellen Sie sicher, dass Sie die Schritte in Projekt-Setup abgeschlossen haben, um Zugänglichkeitsüberprüfungen in die verwendete Test-Suite Ihrer (Axe Watcher) CI/CD-Pipeline zu integrieren.
Modifizieren Sie Ihren aktuellen Workflow - Sie müssen Ihren aktuellen Testrunner-Workflow in .github/workflows modifizieren und die GitHub-Aktion nach dem Job, der Ihre Test-Suite ausführt, hinzufügen.

Beispieljob

Der Job, der Ihrer Test-Suite-Aktion folgt, sollte die GitHub Action für Axe Developer Hub ausführen. Lesen Sie das folgende Beispiel:

jobs:

# ...
# your-CI-test
# ...

# Add the following new job:
# Be sure to replace <choose_latest_tag> with the appropriate version tag
  axe-dev-hub:
    runs-on: ubuntu-latest
    needs: your-CI-test
    steps:
      - uses: actions/checkout@v5
      - uses: dequelabs/axe-devhub-action@<choose_latest_tag>
        with:
          api_key: ${{ secrets.axe_DEV_HUB_API_KEY }}
          project_id: ${{ env.PROJECT_ID }}

Der axe-dev-hub-Job im Beispiel hängt vom Job ab, der Ihre Test-Suite ausführt, spezifiziert mit der needs: your-CI-test-Zeile. Achten Sie darauf, diese Zeile zu aktualisieren, um den Namen des Jobs, der Ihre Test-Suite ausführt, widerzuspiegeln.

Sie können mehrere Eingabeparameter für die GitHub Action verwenden. So können Sie beispielsweise die a11y-Schwelle aktivieren, indem Sie enable_a11y_threshold: true verwenden. Eine vollständige Liste der Eingabeparameter finden Sie im Axe Developer Hub GitHub Action README.

note

Sie müssen den server_url-Parameter nicht festlegen, wenn Sie Ihr Projekt auf axe.deque.com erstellt haben. Wenn Ihre Organisation eine regionale Instanz, eine private Cloud oder eine lokale Bereitstellung von Axe Developer Hub verwendet, müssen Sie server_url auf die Basis-URL dieser Instanz setzen (zum Beispiel https://axe-eu.deque.com).

Ergebnisse

Die GitHub Action setzt mehrere Ausgabeparameter, einschließlich einer Anzahl von entdeckten Barrierefreiheitsproblemen, behobenen Problemen und Problemen, die den a11y-Schwellenwert überschreiten.

Wenn Sie den a11y-Schwellenwert nicht aktiviert haben, wird die GitHub Action fehlschlagen, wenn mehr als null Zugänglichkeitsfehler vorhanden sind. Wenn aktiviert, führen nur Verstöße, die den a11y-Schwellenwert überschreiten, dazu, dass die GitHub Action fehlschlägt. Erfahren Sie mehr über die Verwendung des a11y-Schwellenwerts, um Axe Developer Hub individuell für die Prioritäten Ihrer Organisation zu gestalten.

Das Fehlschlagen der GitHub Action wird einen Kommentar ähnlich dem untenstehenden an Ihre Pull-Anfrage anhängen und kann das Zusammenführen blockieren.

Klicken Sie auf den Link im Pull-Anfrage-Kommentar, um Informationen zu Barrierefreiheitsdefekten für diesen Commit im Axe Developer Hub zu überprüfen.

Fehlerbehebung

Möglicherweise erhalten Sie einen Fehler wie den folgenden:

Error: Resource not accessible by integration

Überprüfen Sie, ob Sie die notwendigen Berechtigungen auf der Einstellungsseite für Aktionen haben. Sie benötigen Lese- und und Schreibberechtigungen, damit die Aktion Kommentare zu Pull Requests hinzufügen kann. Für mehr Granularität können Sie wählen, ein anderes GITHUB_TOKEN für die GitHub-Aktion zu verwenden. Fügen Sie diesen Wert dem Eingabeparameter github_token hinzu.

Beispiel-Workflow

Wenn Sie noch keinen Workflow haben, der Ihre Test-Suite ausführt, können Sie das Beispiel-Workflow als Ausgangspunkt verwenden, um Ihren eigenen Testrunner zu erstellen.

Das Beispiel-Workflow heißt Tests (tests.yml) und läuft bei jedem Commit oder Pull-Request. Der Job, der die modifizierte Test-Suite ausführt, cypress, zeigt, wie man eine Cypress-Test-Suite ausführt. Der folgende Job im Beispiel, axe-dev-hub, ist ein Aufruf der Axe Developer Hub GitHub Action.

Ihr Test-Suite-Job sollte immer vor die Axe Developer Hub GitHub Action laufen.

tip

Das Beispielverzeichnis enthält ein vollständiges Testprojekt, mit dem Sie experimentieren können.

Referenzen

Haupt-Repository für die Axe Developer Hub GitHub Action
- Das README enthält Informationen über die Ein- und Ausgabeparameter
- Finden Sie Metadaten für die GitHub Action in action.yml
- Überprüfen Sie das Beispielaufruf im GitHub-Action-Repo regelmäßig auf die neueste Jobkonfiguration
Weitere Informationen zu den Themen auf dieser Seite finden Sie in der GitHub-Dokumentation