Verwenden des Axe DevTools Linter Connectors

axe DevTools Linter Connector (auch bekannt als der Connector) ist ein Befehlszeilentool für Linux, macOS und Windows. Es bietet eine Befehlszeilenschnittstelle zum Linten Ihrer Dateien, sodass Sie Ihre Zugänglichkeitsprüfung automatisieren können. Sie können es beispielsweise für Skripting und CI/CD (Continuous Integration und Continuous Delivery) verwenden. Der Connector muss Ihre Dateien an eine Instanz des axe Linter Servers senden (unabhängig davon, ob dieser von Deque oder Ihrer Organisation gehostet wird). Alternativ können Sie die Dateien lokal linten, ohne den Inhalt Ihrer Dateien an einen Server zu senden, indem Sie die Option --local verwenden, siehe Lokales Linting unten.

Anwendungsfälle für den Connector

Der axe DevTools Connector kann

• Überprüfe die Zugänglichkeit als Teil von Jenkins-Builds. Weitere Informationen finden Sie unter Verwenden von axe DevTools Linter mit Jenkins.
• Scanne deine Dateien und gebe Informationen zu Zugänglichkeitsmängeln in SonarQube ein. Informationen zur Einrichtung finden Sie unter Verwenden von axe DevTools Linter mit SonarQube .

– In einem GitHub-Pre-Commit-Skript verwenden, um Commits zu blockieren, die Zugänglichkeitsfehler enthalten. Siehe Verwenden eines Git Pre-Commit-Hook mit axe DevTools Linter.

• Schaffen Sie eine Grundlage für die Überprüfung Ihres Codes auf Zugänglichkeitsmängel für Dienste wie:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps-Dienste

Lokales Linting

Mit dem Connector können Sie das Senden Ihrer Dateien an einen Server vermeiden, indem Sie lokales Linting mit der --local Befehlszeilenoption verwenden.

• Vorteile des lokalen Lintings

  • Viel schneller als die Verwendung des Servers.
  • Es ist wesentlich unwahrscheinlicher, dass Netzwerkprobleme oder Probleme mit der Serverauslastung auftreten. Es ist besonders effizient beim Linting einer großen Anzahl von Dateien.

• Nachteile des lokalen Lintings

  – Erfordert mehr Ressourcen des lokalen Rechners.

  • Für Updates des axe DevTools Linter Connector muss eine neue Version von Agora heruntergeladen und installiert werden.
  • Keine Nutzungsverfolgung (wenn Sie einen Lizenzschlüssel anstelle eines API-Schlüssels verwenden).

Lizenzschlüssel im Vergleich zu API-Schlüsseln

Für das lokale Linting ist entweder ein API-Schlüssel oder ein Lizenzschlüssel erforderlich. Sie können Ihre API-Schlüssel als Teil Ihres axe-Kontos verwalten , was Flexibilität bietet. Sie müssen jedoch einen Lizenzschlüssel vom Deque-Helpdesk anfordern. Durch die Verwendung von lokalem Linting mit Lizenzschlüsseln wird die Nutzung (gelintete Codezeilen) nicht verfolgt, Lizenzschlüssel erfordern jedoch auch keine Remote-Authentifizierung.

Einrichtung

Informationen zum Herunterladen des axe DevTools Linter Connector finden Sie unter Herunterladen des axe DevTools Linter Connector.

Unter Linux und macOS muss das Ausführungsflag der Befehlsdatei wie unten gezeigt gesetzt sein:

chmod +x axe-linter-connector-linux
chmod +x axe-linter-connector-macos

Beim Herunterladen der ausführbaren Datei auf macOS wird das Quarantäne-Attribut gesetzt, das Sie löschen müssen, bevor Sie den Connector verwenden können:

xattr -d com.apple.quarantine axe-linter-connector-macos

Benennen Sie die ausführbare Datei um (um das Betriebssystem und den Bindestrich am Ende des Dateinamens zu entfernen) und kopieren oder verknüpfen Sie sie in ein Verzeichnis in Ihrem Pfad, damit sie mit anderen Tools verwendet werden kann (z. B. mit einem Git-Pre-Commit-Hook, siehe Verwenden eines Git-Pre-Commit-Hooks mit axe DevTools Linter).

Umgebungsvariablen

Der Connector erkennt die folgenden Umgebungsvariablen:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• DEBUG

AXE_LINTER_SERVER_URL und AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL legt die URL für Ihre axe DevTools Linter-Serverinstanz fest. (Sie können die Server-URL auch mit den -u oder --url Befehlszeilenoptionen festlegen.) AXE_LINTER_SERVER_PORT gibt den Port an, auf dem der Server lauscht, normalerweise Port 3000.

Weitere Informationen zum Einrichten Ihres Servers finden Sie unter Einrichten von axe DevTools Linter . Die URL zur Verwendung mit der SaaS-Version von axe DevTools Linter finden Sie in der URL-Kurzreferenz . (Sie müssen keinen Port angeben, wenn Sie die SaaS-Version von axe DevTools Linter verwenden.)

Das folgende Beispiel zeigt das Festlegen von Umgebungsvariablen für axe DevTools Linter, das auf dem lokalen Computer unter Linux oder macOS ausgeführt wird (obwohl hier keine der Umgebungsvariablen erforderlich ist, da dies die Standardwerte sind):

export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000

Alternativ können Sie unter Linux und macOS die Umgebungsvariablen auch in derselben Befehlszeile wie axe-linter-connector festlegen. Das folgende Beispiel zeigt diese Verwendung. (Da es sich hierbei jedoch um die Standardwerte für Server und Port handelt, müssen Sie diese nicht festlegen.)

AXE_LINTER_SERVER_PORT=3000 AXE_LINTER_SERVER_URL=http://localhost axe-linter-connector -s . -d .

DEBUG

Mit der Umgebungsvariable DEBUG können Sie ausführliche Debuginformationen zur Diagnose von Lint-Fehlern protokollieren. Setzen Sie die Umgebungsvariable DEBUG auf „axe-devtools-linter:*“, um die Debug-Protokollierung wie unten gezeigt zu aktivieren:

DEBUG=axe-devtools-linter:* axe-linter-connector -s . -d .

Befehlszeilenoptionen

Erforderliche Befehlszeilenoptionen

Der axe DevTools Linter Connector erfordert die folgenden zwei Optionen:

-s, --source Verzeichnis-oder-Datei
Gibt eine Datei oder das Verzeichnis mit den Dateien an, die auf Zugänglichkeitsfehler überprüft werden sollen. Es werden auch Unterverzeichnisse durchsucht. Informationen zum Ausschließen von Dateien von der Lint-Prüfung finden Sie unter der Option Ausschließen im Abschnitt Konfigurationsdatei .

-d, --Zielverzeichnis **
Verzeichnis, in das Connector den Zugänglichkeitsbericht schreibt.

-u, --url URL
Gibt den zu verwendenden Server an. Der Standardwert ist http://localhost. Um den SaaS-Server zu verwenden, spezifizieren Sie --url https://axe-linter.deque.com/

Optionale Befehlszeilenoptionen

Je nachdem, mit welchem Server Sie eine Verbindung herstellen und welche anderen Funktionen oder Berichtsformate Sie verwenden möchten, sind möglicherweise mehrere Optionen erforderlich.

--api-key API-Schlüssel
Gibt den API-Schlüssel an, um das Linting mit der SaaS axe DevTools Linter-Instanz zu autorisieren oder lokales Linting zu verwenden. Weitere Informationen finden Sie unter Erhalten eines axe DevTools Linter SaaS-API-Schlüssels .

--config Dateiname
Gibt den Namen einer YAML-Datei an, die Konfigurationsinformationen enthält. Sie können diese Option auch ohne Dateinamen verwenden. Der axe DevTools Connector befolgt dann die Schritte unter Mehrere Konfigurationsdateien , um die Konfigurationsdateien zu finden. Informationen zur Konfigurationsdatei finden Sie unter Konfigurationsdatei.

--filename filename
Gibt den Namen des SonarQube-Berichts an, Standard: axe-linter-report.json

--issue-type type
Wird verwendet, um den Problemtyp für SonarQube anzugeben, Standard: BUG, zulässige Werte: VULNERABILITY, CODE_SMELL oder BUG

--Lizenzschlüssel **
Gibt den Lizenzschlüssel an, der zur Authentifizierung verwendet werden soll. Wenden Sie sich an den Deque Helpdesk , um weitere Informationen zum Erhalt eines Lizenzschlüssels zu erhalten. Diese Option erfordert auch die Option --local .

--local
Aktiviert das lokale Linting, bei dem die Maschine, auf der der axe DevTools Connector ausgeführt wird, zum Linting Ihrer Dateien verwendet wird, anstatt die Dateien an einen Server zu senden. Erfordert einen API-Schlüssel (--api-key) oder einen Lizenzschlüssel (--license-key). Siehe Lokales Linting.

axe-linter-connector -s . -d . --api-key 1234 --local --url https://axe-linter.deque.com/

-R, --reporter reporter
Gibt den zu verwendenden Reporter an, Standard: sonarqube

--retry-backoff-limit backoff-limit
Gibt die maximale Zeit in Millisekunden an, die der Connector wartet, bevor er im Fehlerfall erneut versucht, die Serververbindung herzustellen. Der Standardwert beträgt 30.000 Millisekunden (30 Sekunden).

--retry-count Versuche
Gibt an, wie oft nach Auftreten eines Verbindungsfehlers erneut versucht werden soll, eine Verbindung zum Server herzustellen. Der Connector verdoppelt die Zeit zwischen den Wiederholungsversuchen (beginnend bei 500 Millisekunden oder 0,5 Sekunden), bis er das Backoff-Limit (angegeben mit --retry-backoff-limit) erreicht. Dort bleibt er, bis er die angegebene Anzahl an Wiederholungsversuchen erreicht (und fehlschlägt) oder ohne Fehler eine Verbindung zum Server herstellt.

--Schweregrad **
Legt den Schweregrad für SonarQube fest, Standard: MAJOR, zulässige Werte: BLOCKER, CRITICAL, MAJOR, MINOR oder INFO

Konfigurationsdatei

Sie können eine YAML-Konfigurationsdatei mit der Option --config verwenden.

Nachfolgend sehen Sie ein Beispiel für eine Konfigurationsdatei:

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

Im obigen Beispiel wird die Regel image-alt ignoriert und die Datei meta-refresh.html wird nicht überprüft. Es werden die Regeln im Tag wcag2a verwendet, wie im Abschnitt tags angegeben. (Weitere Informationen finden Sie unter Tags .)

Der Wert exclude erlaubt Glob-Werte (*) und Globstar (**), also ist Folgendes zulässig:

exclude:
  - tmp/**/*.html

Das obige Beispiel würde alle HTML-Dateien im Verzeichnis tmp oder einem seiner Unterverzeichnisse ausschließen.

Weitere Informationen zu zulässigen Konfigurationsoptionen finden Sie unter Konfigurieren von axe DevTools Linter.

Anwendungsbeispiel

Um Connector mit dem axe DevTools Linter SaaS-Server zu verwenden, können Sie die Option „api-key“ wie unten gezeigt verwenden:

axe-linter-connector -s . -d . --api-key 83cc5831-a35b-4a2d-9c2b-84fd2eec0a4d  --url https://axe-linter.deque.com/

Um die gesamte Lint-Prüfung lokal auf dem Computer durchzuführen, auf dem der axe DevTools Connector ausgeführt wird, verwenden Sie die Option --local :

axe-linter-connector -s . -d . --api-key b5a34bba-7b0f-4ccb-9eb2-195ac6c56aee --local --url https://axe-linter.deque.com/