Seiten mit Spec-Dateien analysieren

Eine Spec-Datei ist eine JSON- oder YAML-Datei, die eine Liste von Webseiten und die Browseraktionen definiert, die auf jeder Seite vor der Analyse auf Barrierefreiheitsprobleme ausgeführt werden sollen. Verwenden Sie axe spec , um eine einzelne Spec-Datei auszuführen, oder axe bulk-spec , um ein Verzeichnis von Spec-Dateien zu verarbeiten.

• Der axe spec Befehle
• Struktur der Spec-Datei
• Aktionen
• Selektoren
• Globale Aktionen
• Stapelverarbeitung mit axe bulk-spec
• Optionen

Der axe spec Befehl

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

Der Speicherort <output-dir> ist, wo JSON-Ergebnisse gespeichert werden. Wenn ausgelassen, werden die Ergebnisse im aktuellen Arbeitsverzeichnis gespeichert.

Beispielverwendung:

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

Struktur der Spec-Datei

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

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

Spezifikationsdateien können in YAML oder JSON geschrieben werden. Die folgende Tabelle zeigt die gleichen Werte in jedem Format. Beachten Sie, dass in JSON Aktionsstrings, die doppelte Anführungszeichen enthalten, sie mit einem Backslash maskieren müssen.

Aktionen

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

Es gibt zwei Arten von Aktionen:

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

Komplettes Aktionsbeispiel

Das folgende Beispiel loggt sich in die Deque University ein 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 erfordern 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 als Liste von Strings.

Um Elemente innerhalb von iframes anzusprechen, müssen Sie eine Liste verwenden. Alle Selektoren in der Liste, außer dem letzten, identifizieren aufeinanderfolgende <iframe> Elemente, in die navigiert werden muss, 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 ist relativ zum Root-Dokument, und jeder nachfolgende iframe-Selektor ist relativ zum Dokument innerhalb des vorhergehenden iframes.

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

Iframe-Selektor-Beispiel

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-Eingabefeld zu klicken, verwenden Sie eine Selektorliste. Jeder CSS-Selektor wird innerhalb des Dokumentkontexts ausgewertet, der durch den vorherigen Eintrag festgelegt wird:

# "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 endgültige Zielelement 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

Die CLI unterstützt neun Seitenaktionen:

1. analyze: eine Barrierefreiheitsanalyse durchführen
2. change: den Wert eines <input>, <textarea>oder <select> über JavaScript ändern
3. click: ein Element klicken
4. dismiss: ein Popup oder Modal schließen
5. eval: beliebigen JavaScript-Code ausführen
6. press: eine Taste drücken (mit oder ohne Modifikatoren)
7. select: eine Option in einem <select>
8. type: in ein <input>
9. wait: auf einen bestimmten Zustand warten oder schlafen

analyze

Die analyze Aktion führt eine Barrierefreiheitsanalyse durch. Sie muss mindestens einmal pro Seite aufgerufen werden. Sie können sie mehrfach aufrufen, um eine Seite an verschiedenen Punkten in einem Workflow 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 Regelsätze:

Für Informationen über das Ein- oder Ausschließen von Elementen siehe die Axe-Core-API-Dokumentation zum Kontext-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 zur Kombination mehrerer Optionen: Analysiere nur Bilder innerhalb von Elementen mit der Klasse third-party und Formulare, die bei der Übermittlung nicht validiert werden, unter Ausschluss von Elementen mit der Klasse old-api, unter Verwendung des 508 Regelsatzes, 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. Verwende 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 mit dem angegebenen Selektor übereinstimmt.

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

# Click the body element
click "body"

dismiss

Die dismiss Aktion schließt ein Pop-up oder Modal, indem sie auf dessen Schaltfläche „Schließen“ klickt. Gib einen CSS-Selektor für das Modal-Container und einen weiteren für die Schaltfläche „Schließen“ an. Die Aktion schlägt fehl, ohne dass ein Fehler angezeigt wird, 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. Verwende sie, um das DOM zu manipulieren oder benutzerdefinierte Aktionen durchzufü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-Dokumentation für Tasten.

# 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 anhand seines sichtbaren Textes (nicht anhand seines value Attributes).

Angenommen folgendes 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 eine Zeichenkette in ein ", "context": "paragraph <input> oder ", "context": "paragraph <textarea> Element. Verwenden Sie es, um Formulare auszufüllen und Suchfelder zu befüllen.", "context": "paragraph

# 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 ", "context": "paragraph wait Aktion wartet entweder darauf, dass ein Element einen bestimmten Zustand erreicht, oder pausiert für eine angegebene Dauer.", "context": "paragraph

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

Für Pausendauern werden numerische Werte als Millisekunden interpretiert. Zeichenketten werden mithilfe des ", "context": "paragraph **ms**", "context": "strong text Pakets konvertiert — zum Beispiel, ", "context": "paragraph 1m = 60.000 ms, ", "context": "paragraph 1s = 1.000 ms.", "context": "paragraph

# 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

# Sleep for 1 minute
wait for 1m

# Sleep for 1 second
wait for 1s

# Sleep for 30 milliseconds
wait for 30

Globale Aktionen", "context": "heading level 2

Globale Aktionen laufen auf jeder Seite eines Projekts als Reaktion auf Zustandsänderungen, anstatt prozedural wie Seitenaktionen zu laufen. Derzeit wird nur eine globale Aktion unterstützt: ", "context": "paragraph dismiss modal.", "context": "paragraph

• Globale Aktionen funktionieren sowohl im ", "context": "paragraph spec Modus als auch im Headless-URI-Modus.", "context": "paragraph
• Globale Aktionen sind nicht prozedural — sie werden durch Ereignisse auf der Seite ausgelöst, nicht in einer festen Reihenfolge.", "context": "paragraph
• Die ", "context": "paragraph dismiss modal globale Aktion wartet darauf, dass ein bestimmtes Modal erscheint und schließt es, bevor Seitenaktionen fortgesetzt werden.", "context": "paragraph

Fügen Sie globale Aktionen zu einem Projekt hinzu nach ", "context": "paragraph name/", "context": "paragraphid und vor ", "context": "paragraph pageList:", "context": "paragraph

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"

Stapelverarbeitung mit ", "context": "heading level 2 axe bulk-spec

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

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

Die ", "context": "paragraph <output-directory> ist optional — falls weggelassen, werden die Ergebnisse im aktuellen Arbeitsverzeichnis gespeichert.", "context": "paragraph

Fortschrittsaktualisierungen werden während des Ablaufs an ", "context": "paragraph stdout ausgegeben.", "context": "paragraph

Ergebnisse werden im Ausgabeverzeichnis gespeichert: eine JSON-Datei pro ", "context": "paragraph analyze Aktion, plus eine Protokolldatei, die alle fehlgeschlagenen Spezifikationsdateien und den Grund für das Scheitern auflistet.", "context": "paragraph

Optionen", "context": "heading level 2

Die folgenden Optionen sind verfügbar für ", "context": "paragraph axe spec:", "context": "paragraph

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

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

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

Gibt die Projekt-ID des Axe Developer Hub an. Erforderlich (zusammen mit ", "context": "paragraph --axe-devhub-api-key), um Ergebnisse an Axe Developer Hub zu senden. Siehe ", "context": "paragraph Ergebnisse an Axe Developer Hub senden", "context": "link text.", "context": "paragraph

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

Gibt die URL des Axe Developer Hub Servers an. Standardmäßig ", "context": "paragraph https://axe.deque.com. Entspricht der AXE_DEVHUB_SERVER_URL Umgebungsvariable. Siehe Ergebnisse an Axe Developer Hub senden.

-c, --custom <path>

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

--descendant-links

Sammelt die Links auf jeder Seite und fügt sie den Ergebnissen hinzu. Erfordert --verbose.

--dismiss-alerts

Blendet automatisch Browser- alert(), confirm()und prompt() Dialogfelder, bevor gescannt wird.

--enable-tracking <state>

Ermöglicht das Senden von Daten an die Metrikbibliothek.

--filter <type(s)>

Filtert Ergebnistypen aus dem Output: passes, violations, incomplete, inapplicable. Erfordert --format csv.

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

Berichtsformate: html, junit, csv, oder eine kommagetrennte Kombination. Standard: html.

--no-git-data

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

--page-name <name>

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

--page-source

Fügt den gescannten HTML-Quellcode den Ergebnissen hinzu. Erfordert --verbose.

--page-title

Fügt den Seitentitel den Ergebnissen hinzu. Erfordert --verbose.

--remote-proxy <proxy-server>

Leitet den Datenverkehr über den angegebenen Remote-Proxyserver.

--resume-from <name>

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

--scanned-url

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

--set-distinct-id <id>

Überschreibt den Wert der eindeutigen ID.

--set-legacy-mode

Aktiviert den veralteten Legacy-Scanmodus, der in Version 5.0 entfernt wird.

--set-tracking-url <url>

Überschreibt die URL, an die Metrikdaten gesendet werden.

-t, --tags

Filtert das Standardregelset nach Tag.

--user-agent

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

--validate

Überprüft Ihre Spezifikationsdatei, ohne sie auszuführen.

-v, --verbose

Beinhaltet zusätzliche Ausgaben: Axe-Ergebnisse und Metadaten wie Toolname, Version und Umgebung.

Für zusätzliche Konfigurationsoptionen siehe Konfigurieren.