Seiten mit Spec-Dateien analysieren

Eine Spezifikationsdatei ist eine JSON- oder YAML-Datei, die eine Liste von Webseiten und die Browseraktionen, die auf jeder Seite ausgeführt werden sollen, bevor sie auf Barrierefreiheitsprobleme analysiert werden, definiert. Verwenden Sie axe spec, um eine einzelne Spezifikationsdatei auszuführen, oder axe bulk-spec, um ein Verzeichnis von Spezifikationsdateien zu verarbeiten.

Der axe spec-Befehl

axe spec <spec-file> <output-dir> [options]

Der <output-dir> gibt an, wo JSON-Ergebnisse gespeichert werden. Wird er weggelassen, werden die Ergebnisse im aktuellen Arbeitsverzeichnis gespeichert.

Beispielnutzung:

axe spec ./axe-workflow.yaml ./axe-results --format html

Spec-Datei-Struktur

Eine Spec-Datei definiert ein oder mehrere Projekte, jedes mit einer Liste von Seiten zur Analyse und optionalen Aktionen, die auf jeder Seite ausgeführt werden.

YAML-Beispiel

projects:
  - name: deque.com
    id: deque.com
    metadata:
      products:
        - CLI
      environment:
        - Prod
    globalActions:
      - dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept"
    pageList:
      - name: Deque search
        url: https://www.deque.com/
        actions:
          - type "axe" into element "#searchform input"
          - click element "#searchform button"
          - wait for element ".m-search-page" to be found
          - analyze
      - name: Axe Dashboard
        url: https://axe.deque.com/

Projekt

Seite

JSON/YAML-Format

Spec-Dateien können in YAML oder JSON geschrieben werden. Die folgende Tabelle zeigt die gleichen Werte in jedem Format. Beachten Sie, dass in JSON Aktionszeichenfolgen, die Anführungszeichen enthalten, mit einem Backslash versehen werden müssen.

Aktionen

Aktionen sind Zeichenfolgen im actions (oder globalActions) Array einer Spezifikationsdatei. Sie führen Aufgaben wie das Klicken von Schaltflächen, das Ausfüllen von Formularen, das Schließen von Dialogen, das Warten auf Seitenzustände und das Durchführen von Barrierefreiheit-Analysen aus. Aktionen werden in der aufgeführten Reihenfolge ausgeführt.

Es gibt zwei Arten von Aktionen:

• Seitenaktionen werden in der Reihenfolge auf einer bestimmten Seite ausgeführt. Die analyze-Aktion muss mindestens einmal pro Seite aufgerufen werden.
• Globale Aktionen werden auf jeder Seite im Projekt als Reaktion auf Zustandsänderungen ausgeführt. Siehe Globale Aktionen.

Vollständiges Aktionsbeispiel

Das folgende Beispiel meldet sich bei Deque University an und analysiert das Dashboard:

projects:
  - name: Deque University login flow
    id: deque-university-login-flow
    pageList:
      - name: homepage
        url: https://dequeuniversity.com/
        actions:
          - click element ".loginLink"
          - wait for element ".loginUsername" to be found
          - type "user@example.com" into element ".loginUsername"
          - type "secretpassword" into element "#loginPassword"
          - click element "input[type=submit]"
          - wait for element ".logoutLink" to be found
          - analyze page

Selektoren

Viele Aktionen benötigen ein Selektor-Argument, das ein Element auf der Seite identifiziert. Ein Selektor kann ein CSS-Selektor oder ein XPath-Selektor sein, angegeben als einzelner String oder eine Liste von Strings.

Um Elemente innerhalb von iframes zu zielen, müssen Sie eine Liste verwenden. Alle Selektoren in der Liste außer dem letzten identifizieren nacheinander <iframe> Elemente, in die navigiert werden soll, und müssen CSS-Selektoren sein. Der letzte Selektor in der Liste identifiziert das Zielelement und kann ein CSS- oder XPath-Selektor sein. Jeder Selektor in der Liste wird relativ zum Dokumentkontext ausgewertet, der durch den vorherigen Eintrag festgelegt wird: Der erste Selektor bezieht sich auf das Wurzel-Dokument, und jeder nachfolgende Iframe-Selektor bezieht sich auf das Dokument innerhalb des vorhergehenden Iframes.

Die Verwendung eines einzelnen Strings (keiner Liste) kann nicht in iframes navigieren.

Beispiel für Iframe-Selektoren

Betrachten Sie diese HTML-Struktur:

<body>
  <!-- root document -->
  <iframe class="payment-widget">
    <!-- document inside the payment-widget iframe -->
    <div class="form-wrapper">
      <iframe id="card-fields">
        <!-- document inside the card-fields iframe -->
        <form>
          <input type="text" name="card-number" class="card-input">
        </form>
      </iframe>
    </div>
  </iframe>
</body>

Um das Kartennummer-Feld anzuklicken, verwenden Sie eine Selektorliste. Jeder CSS-Selektor wird innerhalb des durch den vorherigen Eintrag festgelegten Dokumentkontexts bewertet:

# "iframe.payment-widget" is evaluated in the root document
# "#card-fields" is evaluated in the document inside iframe.payment-widget
# ".card-input" is evaluated in the document inside #card-fields
click element [ "iframe.payment-widget", "#card-fields", ".card-input" ]

Um XPath für das letzte Ziel-Element zu verwenden (die iframe-Selektoren müssen weiterhin CSS sein):

click element [ "iframe.payment-widget", "#card-fields", "//input[@name='card-number']" ]

In JSON:

"click element [\"iframe.payment-widget\", \"#card-fields\", \".card-input\"]"

Seitenaktionen

Das CLI unterstützt neun Seitenaktionen:

1. analyze: führe eine Barrierefreiheitsanalyse durch
2. change: ändere den Wert eines <input>, <textarea> oder <select> über JavaScript
3. click: klicke auf ein Element
4. dismiss: schließe ein Popup oder Modal
5. eval: führe beliebiges JavaScript aus
6. press: drücke eine Taste (mit oder ohne Modifikatoren)
7. select: wähle eine Option in einem <select>
8. type: tippe in ein <input>
9. wait: warte auf einen bestimmten Zustand oder schlafe

analyze

Die analyze-Aktion führt eine Barrierefreiheitsanalyse durch. Sie muss mindestens einmal pro Seite aufgerufen werden. Sie können sie mehrmals aufrufen, um eine Seite zu verschiedenen Zeitpunkten in einem Arbeitsablauf zu analysieren (verwenden Sie die with title-Variante, um die Ergebnisse zu unterscheiden).

Der optionale ruleset Parameter gibt an, welches Regelwerk verwendet werden soll. Der Standard ist WCAG 2.1 AA. Verfügbare Regelwerke:

Für Informationen zum Ein- oder Ausschließen von Elementen siehe den axe-core-API-Dokumentation zum Context-Parameter.

# Analyze using the WCAG 2.1 AA ruleset (default) — all three forms are equivalent
analyze
analyze the page
analyze page

# Analyze using the Section 508 ruleset
analyze page with ruleset "508"

# Analyze with a custom title (useful when analyzing a page multiple times)
analyze the page with title "after login"

# Analyze only a specific element
analyze only element "#main-content"

# Analyze only specific elements
analyze only element "#idOfElement" and element ".classToAnalyze"

# Analyze everything except images that are immediate children of paragraphs
analyze the page excluding element "p > img"

# Analyze everything except elements inside a frame with a specific class
analyze the page excluding element [ ".classOfFrameToExclude", "#idOfElement" ]

# Save results to a specific directory
analyze the page and save in "./homepage-team/"

# Save a copy to an additional directory while also saving to the default location
analyze the page and save a copy in "./homepage-team/"

# Use the axe-core library's built-in default ruleset
analyze the page with the source default ruleset

Beispiel für die Kombination mehrerer Optionen: analysiert nur Bilder innerhalb von Elementen mit der Klasse third-party und Formulare, die nicht bei der Übermittlung validiert werden, unter Ausschluss von Elementen mit der Klasse old-api, unter Verwendung des Regelwerks 508, mit einem benutzerdefinierten Titel und einem benutzerdefinierten Speicherort.

analyze only element [ ".third-party", "img"] and element "form[novalidate]" excluding element ".old-api" with ruleset "508" with title "What is this testing" and save in "Results for Some test"

In JSON:

"analyze only element [\".third-party\", \"img\"] and element \"form[novalidate]\" excluding element \".old-api\" with ruleset \"508\" with title \"What is this testing\" and save in \"Results for Some test\""

change

Die change-Aktion ändert den Wert eines <input>, <textarea> oder <select> Elements über JavaScript. Verwenden Sie change, wenn normale DOM-Ereignisse nicht verfügbar sind.

# Change the value of an input
change the value of "input[name=song]" to "too many puppies"

click

Die click-Aktion klickt auf das erste Element, das dem angegebenen Selektor entspricht.

# Click a button by class selector
click element ".myButton"

# Click the body element
click "body"

dismiss

Die dismiss-Aktion schließt ein Popup oder Modal, indem sie auf die Schaltfläche zum Schließen klickt. Geben Sie einen CSS-Selektor für den Modal-Container und einen weiteren für die Schaltfläche zum Schließen an. Die Aktion schlägt ohne Fehler fehl, wenn eines der Elemente nicht vorhanden ist.

# Dismiss a modal using separate selectors for the container and close button
dismiss modal ".myModal" with close button ".myModal .close"

eval

Die eval-Aktion führt beliebiges JavaScript auf der Seite aus. Verwenden Sie es, um das DOM zu manipulieren oder benutzerdefinierte Aktionen auszuführen.

# Change the page title
eval "document.title = 'hello world'"

# Scroll an element into view
eval "document.querySelector('.someElement').scrollIntoView()"

# Scroll to the bottom of the page
eval "window.scrollTo(0, document.body.scrollHeight)"

press

Die press-Aktion sendet einen Tastendruck an ein Element (optional mit Modifikatortasten). Für unterstützte Tastenbezeichnungen siehe die Selenium-Schlüsseldokumentation.

# Press H on the body element
press "H" on "body"

# Press Shift+Tab on the navigation element
press "shift+tab" on element ".navigation"

# Press Shift+Control+7 on an element
press "shift+control+7" on element ".foo"

select

Die select-Aktion wählt ein <option> eines <select>-Elements nach seinem sichtbaren Textes (nicht seinem value-Attribut) aus.

Gegeben ist dieses HTML:

<select class="mySelect">
  <option></option>
  <option value="1">dog</option>
  <option value="2">cat</option>
  <option value="3">fish</option>
</select>

# Select by visible option text
select the "dog" option in ".mySelect"
select the "cat" option in element ".mySelect"

type

Die type-Aktion tippt einen String in ein <input> oder <textarea>-Element. Verwenden Sie sie, um Formulare auszufüllen und Suchfelder zu befüllen.

# Type into an email input
type "user@example.com" into element "input[type=email]"

# Type into a textarea
type "hello world" into "textarea.Message"

# Type with a delay between keystrokes to simulate human typing
type "sloth" into "input[type=search]" with a 150ms key delay

wait

Die wait-Aktion wartet entweder darauf, dass ein Element einen bestimmten Zustand erreicht, oder schläft für eine bestimmte Dauer.

Unterstützte Elementzustände: visible, hidden, selected, enabled, disabled, found.

Für Elementzustand-Warteschleifen wird die Aktion standardmäßig bis zu 3 mal-mal wiederholt (insgesamt 4 Versuche), bevor sie fehlschlägt. Um länger auf ein langsam ladendes Element zu warten, fügen Sie with <n> retries hinzu, um die Anzahl der Versuche zu erhöhen.

Für die Schlafdauer werden numerische Werte als Millisekunden interpretiert. Zeichenfolgen werden mit dem ms-Paket konvertiert, zum Beispiel: 1m = 60.000 ms, 1s = 1.000 ms.

# Wait for an element to appear
wait for element ".myElement" to be found

# Wait for an element to become hidden
wait for element ".myElement" to be hidden

# Allow more retries for a slow-loading element
wait for element ".myElement" to be found with 9 retries

# Sleep for 1 minute
wait for 1m

# Sleep for 1 second
wait for 1s

# Sleep for 30 milliseconds
wait for 30

Globale Aktionen

Globale Aktionen werden auf jeder Seite in einem Projekt als Reaktion auf Zustandsänderungen ausgeführt, anstatt wie Seitenaktionen prozedural zu laufen. Aktuell wird nur eine globale Aktion unterstützt: dismiss modal.

• Globale Aktionen funktionieren sowohl im spec-Modus als auch im headless-URI-Modus.
• Globale Aktionen sind nicht prozedural: Sie werden als Reaktion auf Seitenevents ausgelöst, nicht in einer festen Reihenfolge.
• Die dismiss modal-globale Aktion wartet darauf, dass ein spezifiziertes Modal erscheint und schließt es, bevor Seitenaktionen fortgesetzt werden.

Fügen Sie globale Aktionen zu einem Projekt nach name/id und vor pageList hinzu:

projects:
  - id: demo
    name: CLI demo
    globalActions:
      - dismiss modal "#__next .survey" with close button ".survey button.close"
    pageList:
      - name: homepage
        url: https://dequelabs.github.io/aget-demo-site
      - name: popup
        url: https://dequelabs.github.io/aget-demo-site
        actions:
          - wait for element "#__next header nav" to be visible
          - click element "#__next header nav a[href*=popup]"
          - wait for element ".content button" to be found
          - analyze with title "before popup"
          - click element ".content button"
          - analyze with title "with popup"
          - dismiss modal ".ReactModal__Content" with close button ".ReactModal__Content .close"
          - analyze with title "after popup"
      - name: contact
        url: https://dequelabs.github.io/aget-demo-site/contact
        actions:
          - analyze with title "form disabled"
          - wait for element "#__next .toggle" to be found
          - click element ".toggle button"
          - wait for element "input[name=name]" to be enabled
          - analyze with title "form enabled"
          - type "stephen" into element "input[name=name]"
          - type "555-555-5555" into element "input[name=phone]"
          - type "stephen@deque.com" into element "input[name=email]"
          - type "hello world" into element "textarea[name=message]"
          - click element "button[type=submit]"
          - wait for element ".thanks" to be found
          - analyze with title "thanks message"

Aufnahme von Screenshots

Um einen Screenshot jeder Seite nach der Analyse zu erfassen, fügen Sie ein screenshot-Objekt zu einem Projekt in Ihrer Spezifikationsdatei hinzu. Jede Seite erzeugt eine PNG-Datei, die <page-id>-screenshot.png benannt ist (jedes / oder \ in der Seiten-id wird durch _ ersetzt). Wenn eine Seite keine id hat, wird eine aus ihrer name abgeleitet, indem alle Leerzeichen entfernt werden.

Wenn Sie axe spec mit --verbose ausführen, muss jedes Ergebnis auch ein screenshotPath-Feld mit dem vollständigen Pfad zur Screenshot-Datei dieser Seite enthalten.

projects:
  - name: My App
    id: my-app
    screenshot:
      enabled: true
      fullPage: true
      boundingBoxes: true
      dir: ./screenshots
    pageList:
      - name: Home
        url: https://example.com/

Stapelverarbeitung mit axe bulk-spec

Um mehrere Spezifikationsdateien in einem Durchgang zu verarbeiten, verwenden Sie axe bulk-spec mit einem Verzeichnis, das Spezifikationsdateien enthält. Die CLI durchsucht rekursiv das Verzeichnis und seine Unterverzeichnisse nach Spezifikationsdateien.

axe bulk-spec <spec-files-directory> <output-directory>

Der <output-directory> ist optional — wird er weggelassen, werden die Ergebnisse im aktuellen Arbeitsverzeichnis gespeichert.

Fortschrittsmeldungen werden während des Durchlaufs in stdout gedruckt.

Ergebnisse werden im Ausgabeordner abgelegt: eine JSON-Datei pro analyze-Aktion, plus eine Protokolldatei, die alle fehlgeschlagenen Spezifikationsdateien und den Grund für das Scheitern listet.

Optionen

Die folgenden Optionen sind für axe spec verfügbar:

--axe-devhub-api-key <api-key>

Gibt den API-Schlüssel des Axe Developer Hub an. Erforderlich (zusammen mit --axe-devhub-project-id), um Ergebnisse an den Axe Developer Hub zu senden. Siehe Ergebnisse an Axe Developer Hub senden.

--axe-devhub-project-id <project-id>

Gibt die Projekt-ID des Axe Developer Hub an. Erforderlich (zusammen mit --axe-devhub-api-key), um Ergebnisse an den Axe Developer Hub zu senden. Siehe Ergebnisse an Axe Developer Hub senden.

--axe-devhub-server-url <url>

Gibt die URL des Axe Developer Hub-Servers an. Standardwert: https://axe.deque.com. Entspricht der AXE_DEVHUB_SERVER_URL-Umgebungsvariable. Siehe Ergebnisse an Axe Developer Hub senden.

-a, --axe-source <path>

Pfad zu einer alternativen axe.js-Datei. Die meisten Benutzer benötigen diese Option nicht. Sie ist für fortgeschrittene Anwendungsfälle gedacht, wie z. B. das Testen gegen eine spezifische oder gepatchte Version von axe-core.

--chrome-options [options]

Übermittelt eine kommagetrennte Liste von Chrome-Befehlszeilenargumenten an ChromeDriver. Verwenden Sie dies, um Browserfunktionen zu aktivieren oder Einschränkungen in bestimmten Umgebungen zu umgehen, z. B. in containerisierten CI-Umgebungen, in denen der Sandbox-Modus deaktiviert werden muss.

axe spec workflow.yml --chrome-options="no-sandbox,disable-gpu"

-c, --custom <path>

Gibt eine benutzerdefinierte Regeldatei an, die die Standardregeldatei überschreibt.

--descendant-links

Sammlung der Links auf jeder Seite und deren Anfügung an die Ergebnisse. Erfordert --verbose.

--dismiss-alerts

Setzt Browser-alert(), confirm() und prompt()-Dialoge automatisch zurück, bevor die Untersuchung beginnt.

--enable-tracking <state>

Ermöglicht das Senden von Daten an die Metrikbibliothek.

--filter <type(s)>

Filtert Ergebnistypen aus der Ausgabe: passes, violations, incomplete, inapplicable. Erfordert --format csv.

-f, --format <type(s)>

Berichtsformat(e): html, junit, csv, universal oder eine durch Komma getrennte Kombination. Standard: html. Siehe --universal-ruleset und --universal-best-practices für Optionen, die bei der Verwendung von universal gelten.

--no-analyze

Entfernt die Anforderung für eine analyze-Aktion in der Aktionsliste jeder Seite. Standardmäßig muss jede Seite in einer Spezifikationsdatei mindestens eine analyze-Aktion enthalten; dieses Flag deaktiviert diese Prüfung, was nützlich ist, wenn ein Workflow ausgeführt wird, der nur Aktionen durchführt, ohne einen Barrierefreiheitsscan durchzuführen.

--no-exit

Erzwingt, dass die CLI mit Code 0 beendet wird, selbst wenn Verstöße festgestellt werden. Standardmäßig beendet axe spec mit Code 1, wenn Verstöße erkannt werden. Verwenden Sie dies, wenn Sie Ergebnisse sammeln möchten, ohne einen CI-Build zu scheitern.

--no-git-data

Schließt Git-Branch- und Commit-Informationen aus, wenn Ergebnisse an den Axe Developer Hub gesendet werden. Siehe Ergebnisse an Axe Developer Hub senden.

--no-html

Verhindert, dass die CLI einen HTML-Bericht generiert. Verwenden Sie dies zusammen mit --format, um zu steuern, welche Berichtsformate erstellt werden, oder wenn Sie nur JSON-Ergebnisse ohne HTML-Zusammenfassung wünschen.

--no-reports

Verhindert, dass die CLI irgendeine Berichtdatei erzeugt. Ergebnisse werden weiterhin im Terminal angezeigt, aber nichts wird auf die Festplatte geschrieben. Nützlich für schnelle Überprüfungen, bei denen keine Ausgabedateien benötigt werden.

--no-wait

Deaktiviert die automatische Pause zwischen Workflow-Aktionen. Standardmäßig gelten die mit --post-get-pause, --post-script-pause und --post-analyze-pause konfigurierten Pausen zwischen Aktionen (siehe Konfigurieren); dieses Flag umgeht alle.

--page-name <name>

Führt nur die Seite mit dem angegebenen Namen aus der pageList der Spezifikationsdatei aus.

--page-source

Hängt den gescannten HTML-Quellcode an die Ergebnisse an. Erfordert --verbose.

--page-title

Hängt den Seitentitel an die Ergebnisse an. Erfordert --verbose.

--remote-proxy <proxy-server>

Leitet den Datenverkehr über den angegebenen Remote-Proxy-Server.

--resume-from <name>

Überspringt alle Seiten vor der benannten Seite in der pageList der Spezifikationsdatei.

--scanned-url

Fügt die Basis-URL und die aktuelle Scan-URL zu den ausführlichen Ergebnissen hinzu. Nur für Chrome. Erfordert --verbose.

--set-distinct-id <id>

Überschreibt den eindeutigen ID-Wert.

--set-legacy-mode

Aktiviert das veraltete Legacy-Scan-Modus, das in Version 5.0 entfernt wird.

--set-tracking-url <url>

Überschreibt die URL, an die Metrikdaten gesendet werden.

--silent-mode

Unterdrückt allen dekorativen Text aus der CLI-Ausgabe. Ergebnisse werden nur angezeigt, wenn --verbose ebenfalls aktiv ist. Verwenden Sie dies in Skripten oder CI-Pipelines, bei denen Sie eine saubere Ausgabe ohne Fortschrittsbanner oder Statusnachrichten wünschen.

-t, --tags

Filtert das Standardregelwerk nach Tag.

--universal-best-practices

Notiert bestPracticesEnabled=true in den Metadaten der universellen Formatausgabe. Erfordert --format universal.

--universal-ruleset <id>

Gibt die Ruleset-ID an, die in den Metadaten der universellen Formatausgabe vermerkt werden soll. Standardwert: wcag2.1. Erfordert --format universal. Siehe Regelwerktabelle für gültige Werte.

--user-agent

Setzt einen benutzerdefinierten User-Agent-String für den Browser.

--validate

Validiert Ihre Spec-Datei, ohne sie auszuführen.

-v, --verbose

Enthält zusätzlichen Output: Axe-Ergebnisse und Metadaten wie Tool-Name, Version und Umgebung.

--wait-network-idle-new-connections [number]

Die Anzahl neuer Netzwerkverbindungen, die hergestellt werden dürfen, bevor das Netzwerk als untätig gilt. Sobald neue Verbindungen auf diesen Schwellenwert fallen oder darunter liegen, fährt die CLI mit dem Scan fort. Verwenden Sie dies zusammen mit --wait-network-idle-timeout, um zu bestimmen, wann die CLI auf Seiten mit laufender Hintergrund-Netzwerkaktivität läuft.

--wait-network-idle-open-connections [number]

Die Anzahl offener Netzwerkverbindungen, die bestehen bleiben dürfen, bevor das Netzwerk als inaktiv betrachtet wird. Sobald offene Verbindungen auf diesen Schwellenwert fallen oder darunter liegen, führt die CLI den Scan durch.

--wait-network-idle-polling-every [ms]

Das Intervall in Millisekunden, in dem die CLI überprüft, ob das Netzwerk inaktiv geworden ist. Verringern Sie diesen Wert für eine schnellere Erkennung auf Kosten einer höheren CPU-Auslastung.

--wait-network-idle-timeout [ms]

Die maximale Wartezeit in Millisekunden, bis die Netzwerkaktivität sich beruhigt hat, bevor der Scan gestartet wird. Nach dem Laden der Seite überwacht die CLI aktive Netzwerkverbindungen und wartet, bis die Anzahl der Verbindungen den konfigurierten Schwellenwert erreicht. Wenn das Zeitlimit abgelaufen ist, bevor das Netzwerk inaktiv wird, führt die CLI den Scan trotzdem durch.

Für zusätzliche Konfigurationsoptionen siehe Konfigurieren.