Seiten mit Spec-Dateien analysieren

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

Wie man die Unterbefehle spec und bulk-spec verwendet, um Seiten mithilfe von Spec-Dateien zu analysieren

Not for use with personal data

Eine Spec-Datei ist eine JSON- oder YAML-Datei, die eine Liste von Webseiten und die Browserverhalten angibt, die auf jeder Seite ausgeführt werden sollen, bevor sie auf Barrierefreiheitsprobleme analysiert werden. Verwenden Sie axe spec zum Ausführen einer einzelnen Spec-Datei oder axe bulk-spec zum Verarbeiten eines Verzeichnisses mit Spec-Dateien.

Der axe spec Befehl

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

Der <output-dir> ist, wo JSON-Ergebnisse gespeichert werden. Wenn ausgelassen, 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

Eigenschaft Typ Beschreibung
name Zeichenkette Eindeutiger Anzeigename des Projekts.
id Zeichenkette Eindeutiger Bezeichner des Projekts.
metadata Objekt Optional. Beliebige Metadaten für Ihren Anwendungsfall (z. B. Produktname, Umgebung).
globalActions Array Optional. Aktionen, die auf Zustandsänderungen auf jeder Seite im Projekt reagieren, zum Beispiel das Schließen eines Cookie-Banners oder einer Umfrage-Popup. Siehe Globale Aktionen.
pageList Array Liste der zu analysierenden Seiten. Siehe Seite.

Seite

Eigenschaft Typ Beschreibung
name Zeichenkette Anzeigename der Seite.
url Zeichenkette URL der Seite.
actions Array Optional. Aktionen, die auf der Seite vor oder nach der Analyse ausgeführt werden. Siehe Aktionen.

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.

YAML JSON
type "axe" into element "#searchform input" "type \"axe\" into element \"#searchform input\""
dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept" "dismiss modal \"#CybotCookiebotDialog\" with close button \"#CybotCookiebotDialogBodyButtonAccept\""

Aktionen

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

Es gibt zwei Arten von Aktionen:

  • Seitenaktionen werden in Sequenz 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, muss eine Liste verwendet werden. Alle Selektoren in der Liste außer dem letzten identifizieren aufeinander folgende <iframe> Elemente, in die navigiert werden muss, und müssen CSS-Selektoren sein. Der letzte Selektor in der Liste identifiziert das Ziel-Element und kann CSS oder XPath sein. Jeder Selektor in der Liste wird relativ zum Dokumentkontext bewertet, der durch den vorherigen Eintrag festgelegt wurde: Der erste Selektor ist relativ zum Wurzeldokument, 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.

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: eine Barrierefreiheit-Analyse durchführen
  2. change: den Wert eines <input>, <textarea>, oder <select> über JavaScript ändern
  3. click: ein Element klicken
  4. dismiss: ein Popup oder Modalfenster schließen
  5. eval: beliebiges JavaScript 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 pausieren

analyze

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

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

Regelset-ID Standard
wcag2 WCAG 2.0 AA
wcag2.1 WCAG 2.1 AA (Standard)
wcag2.2 WCAG 2.2 AA
wcag2aaa WCAG 2.0 AAA
wcag2.1aaa WCAG 2.1 AAA
wcag2.2aaa WCAG 2.2 AAA
508 Abschnitt 508
ttv5 Trusted Tester v5
en301549 EN 301 549
rgaav4 RGAA v4

Für Informationen zum Ein- oder Ausschließen von Elementen siehe die 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: Analysiere nur Bilder innerhalb von Elementen mit der Klasse third-party und Formulare, die bei der Übermittlung nicht validiert werden, ausschließend Elemente mit der Klasse old-api, unter Verwendung des 508 Regelwerks, 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 eines <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 dessen Schließen-Button klickt. Geben Sie einen CSS-Selektor für den Modal-Container und einen weiteren für den Schließen-Button an. Die Aktion schlägt fehl, ohne kritische Fehler zu erzeugen, wenn eines der Elemente nicht vorhanden ist.

note

Diese Aktion schließt keine nativen alert() oder confirm() -Dialoge.

# 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 beliebigen JavaScript-Code auf der Seite aus. Verwenden Sie sie, um den 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 anhand seines sichtbaren Textes (nicht anhand seines value -Attributs).

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 eine Zeichenfolge in ein <input> oder <textarea> -Element. Verwenden Sie sie, um Formulare auszufüllen und Suchfelder zu fü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 pausiert für eine bestimmte Dauer.

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

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

# 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 eines Projekts als Reaktion auf Statusänderungen ausgeführt, anstatt prozedural wie Seitenaktionen abzulaufen. Derzeit 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 Seitenereignisse ausgelöst, nicht in einer festen Reihenfolge.
  • Die dismiss modal globale Aktion wartet darauf, dass ein bestimmtes Modal erscheint und schließt es, bevor die Seitenaktionen fortgesetzt werden.

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

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 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 das Verzeichnis und seine Unterverzeichnisse rekursiv nach Spezifikationsdateien.

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

Das <output-directory> ist optional — wenn es weggelassen wird, werden die Ergebnisse im aktuellen Arbeitsverzeichnis gespeichert.

Fortschrittsaktualisierungen werden während des Laufs an stdout gedruckt.

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

Optionen

Die folgenden Optionen stehen für axe spec:

--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 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 Axe Developer Hub zu senden. Siehe Ergebnisse an Axe Developer Hub senden.

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

Gibt die URL des Servers des Axe Developer Hub an. Standardmäßig auf 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

Schließt automatisch Browser- alert(), confirm(), und prompt() Dialogfenster, bevor gescannt wird.

--enable-tracking <state>

Ermöglicht das Senden von Daten an die Metrikbibliothek.

--filter <type(s)>

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

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

Berichtsformate: html, junit, csvoder eine durch Komma getrennte 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 Spec-Datei aus pageList.

--page-source

Hängt den gescannten HTML-Quelltext 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 Spec-Datei pageList.

--scanned-url

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

--set-distinct-id <id>

Überschreibt den eindeutigen ID-Wert.

--set-legacy-mode

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

important

Dies ist eine Option des letzten Auswegs. Es wurde berichtet, dass sie Scans auf Seiten ermöglicht, die window.open()überschreiben, eine nicht empfohlene Praxis.

--set-tracking-url <url>

Überschreibt die URL, an die Metrikdaten gesendet werden.

-t, --tags

Filtert das Standardregelwerk nach Tag.

--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.

Für zusätzliche Konfigurationsoptionen siehe Konfigurieren.

Is this page helpful?

Help us improve this page

Still need help?