Verwendung des Axe DevTools Linter Connector

Der Axe DevTools Linter Connector (auch bekannt als der Connector) ist ein Befehlszeilenwerkzeug für Linux, macOS und Windows. Er bietet eine Befehlszeilenschnittstelle, um Ihre Dateien zu linden, sodass Sie Ihre Barrierefreiheitsprüfung automatisieren können. Sie können ihn beispielsweise für Skripte und CI/CD (Continuous Integration und Continuous Delivery) verwenden. Der Connector muss Ihre Dateien an eine Instanz des Axe Linter Servers senden, sei es von Deque gehostet (SaaS) oder von Ihrer Organisation (on prem oder on premises), oder Sie können die Dateien lokal linden, ohne die Inhalte Ihrer Dateien an einen Server zu senden, indem Sie die --local-Option verwenden (siehe Lokales Linting unten).

Anwendungsfälle des Connectors

Der Axe DevTools Connector kann

• Prüfen Sie die Barrierefreiheit im Rahmen von Jenkins-Builds. Für mehr Informationen siehe Verwendung von Axe DevTools Linter mit Jenkins.
• Scannen Sie Ihre Dateien und übergeben Sie Informationen über Barrierefreiheitsmängel an SonarQube. Siehe Verwendung von Axe DevTools Linter mit SonarQube für Informationen zur Einrichtung.
• In einem GitHub pre-commit-Skript verwendet werden, um Commits, die Barrierefreiheitsfehler enthalten, zu blockieren. Siehe Verwendung eines Git Pre-Commit Hooks mit Axe DevTools Linter.
• Eine Basis zur Überprüfung Ihres Codes auf Barrierefreiheitsfehler für Dienste wie:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Lokales Linting

Der Connector ermöglicht es Ihnen, das Senden Ihrer Dateien an einen Server zu vermeiden, indem Sie lokale Linterierung mit der --local-Befehlszeilenoption verwenden.

• Vorteile der lokalen Linterierung

  • Viel schneller als die Verwendung des Servers.
  • Viel weniger wahrscheinlich, auf Netzwerkprobleme oder Serverüberlastungen zu stoßen. Es ist besonders effizient beim Linterieren großer Mengen an Dateien.

• Nachteile der lokalen Linterierung

  • Erfordert mehr Ressourcen der lokalen Maschine.
  • Aktualisierungen des Axe DevTools Linter Connectors erfordern das Herunterladen und Installieren einer neuen Version von Agora.
  • Keine Nutzungsverfolgung (wenn Sie einen Lizenzschlüssel anstelle eines API-Schlüssels verwenden).

Lizenzschlüssel im Vergleich zu API-Schlüsseln

Lokales Linden erfordert entweder einen API-Schlüssel oder einen Lizenzschlüssel. Sie können Ihre API-Schlüssel im Rahmen Ihres Axe-Kontos verwalten (um Flexibilität zu bieten). Sie müssen jedoch einen Lizenzschlüssel von Deque's Help Desk anfordern. Die Verwendung von lokalem Linden mit Lizenzschlüsseln verfolgt nicht die Nutzung Ihrer Benutzer (gelindete Codezeilen), aber Lizenzschlüssel erfordern auch keine entfernte Authentifizierung.

Installationsoptionen

Es gibt zwei Optionen zur Installation des Axe DevTools Linter Connectors:

• Richten Sie ein Agora-npm-Registry ein und nutzen Sie die von Node.js und npm bereitgestellte Infrastruktur, um den Connector zu installieren, auszuführen und zu aktualisieren. Weitere Informationen finden Sie unter Installation des Axe DevTools Linter Connectors als npm-Paket.
• Die andere Option ist, das Connector-Binary manuell für die Architektur Ihres Computers herunterzuladen und es durch Setzen des Ausführungsbits (Linux und macOS) und das Löschen erweiterter Quarantäneattribute (macOS) für die Nutzung vorzubereiten. Siehe die Download-Seite.

Umgebungsvariablen

Der Connector erkennt die folgenden Umgebungsvariablen:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• AXE_SERVICE_URL
• DEBUG

AXE_LINTER_SERVER_URL und AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL setzt die URL für Ihre Axe DevTools Linter Serverinstanz. (Sie können die Server-URL auch mit der -u oder --url Befehlszeilenoptionen festlegen.) AXE_LINTER_SERVER_PORT gibt den Port an, den der Server überwacht, normalerweise Port 3000.

Siehe Einrichtung des Axe DevTools Linters für weitere Informationen über die Einrichtung Ihres Servers, und siehe URL-Referenz für die URL zur Verwendung mit der SaaS-Version des Axe DevTools Linter. (Für die Verwendung der SaaS-Version des Axe DevTools Linter müssen Sie keinen Port angeben.)

Das folgende Beispiel zeigt die Einstellung der Umgebungsvariablen für den Axe DevTools Linter, der auf der lokalen Maschine unter Linux oder macOS läuft (obwohl keine dieser Umgebungsvariablen hier erforderlich ist, da dies die Standardwerte sind):

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

Alternativ können Sie auf Linux und macOS die Umgebungsvariablen auch auf derselben Befehlszeile wie den axe-linter-connector-Befehl setzen. Das untenstehende Beispiel zeigt diese Nutzung. (Da dies jedoch die Standardwerte für den Server und den Port sind, müssen Sie sie nicht setzen.)

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

AXE_SERVICE_URL

Die AXE_SERVICE_URL-Umgebungsvariable erlaubt es Ihnen, einen alternativen Server anzugeben, um Ihren API-Schlüssel zu validieren. Der Standardwert ist https://axe.deque.com.

Private-Cloud-Kunden haben einen dedizierten Authentifizierungsserver an einer kundenspezifischen URL. Um lokales Linden zu verwenden, setzen Sie AXE_SERVICE_URL auf die URL Ihrer Private-Cloud-Instanz, bevor Sie den Connector ausführen:

export AXE_SERVICE_URL=https://your-org-axedevtools.dequecloud.com
axe-linter-connector -s . -d . --api-key <your-api-key> --local

Die URL Ihrer Private-Cloud-Instanz wurde Ihnen bei der Einrichtung Ihrer Private-Cloud-Instanz bereitgestellt. Wenn Sie diese nicht haben, kontaktieren Sie Deque's Help Desk.

DEBUG

Die DEBUG-Umgebungsvariable erlaubt es Ihnen, detaillierte Debug-Informationen zum Diagnostizieren von Lindungsfehlern zu protokollieren. Setzen Sie die DEBUG-Umgebungsvariable auf axe-devtools-linter:*, um das Debug-Logging zu aktivieren, wie unten gezeigt:

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

Befehlszeilenoptionen

Erforderliche Befehlszeilenoptionen

Axe DevTools Linter Connector erfordert die folgenden zwei Optionen:

-s, --source directory-or-file
Gibt eine Datei oder ein Verzeichnis an, das überprüft werden soll, ob Barrierefreiheitsfehler vorliegen. Unterverzeichnisse werden ebenfalls durchsucht. Um Dateien vom Linden auszuschließen, siehe die exclude-Option im Konfigurationsdatei-Abschnitt.

-d, --destination directory
Das Verzeichnis, in dem der Connector den Barrierefreiheitsbericht speichern wird.

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

Optionale Befehlszeilenoptionen

Je nach dem Server, mit dem Sie sich verbinden, und welchen weiteren Funktionen oder Berichtsformaten Sie verwenden möchten, könnten mehrere Optionen erforderlich sein.

--additional-properties property
Fügt zusätzlichen Eigenschaften zu Problemen im Barrierefreiheitsbericht für auf benutzerdefinierten gemappten Komponenten gefundene Verstöße hinzu. Der derzeit einzige unterstützte Wert ist customName. Wenn angegeben, erhält jedes Problem, das ein benutzerdefiniertes Mapping-Komponent enthält, eine customName-Eigenschaft im Bericht, deren Wert der Tag-Name der benutzerdefinierten Komponente ist, die den Verstoß ausgelöst hat. Probleme von Komponenten, die nicht Teil eines benutzerdefinierten Mappings sind, erhalten keine customName-Eigenschaft.

axe-linter-connector -s . -d . --additional-properties customName

Zum Beispiel, wenn <MyButton> eine benutzerdefinierte Komponente ist und eine button-name-Verletzung auslöst, sieht das Problem im Bericht folgendermaßen aus:

{
    "engineId": "axe-linter-jsx",
    "ruleId": "button-name (https://dequeuniversity.com/rules/axe/4.11/button-name?application=axe-linter)",
    "customName": "MyButton",
    "severity": "MAJOR",
    "type": "BUG",
    "primaryLocation": {
        "filePath": "/path/to/app.jsx",
        "message": "Buttons must have discernible text",
        "textRange": {
            "startLine": 7,
            "endLine": 7,
            "startColumn": 12,
            "endColumn": 20
        }
    }
}

--api-key api-key
Gibt den API-Schlüssel an, um das Linden mit der SaaS Axe DevTools Linter-Instanz zu autorisieren oder lokales Linden zu verwenden. Siehe Beschaffung eines SaaS API-Schlüssels für Axe DevTools Linter für weitere Informationen.

--config filename
Gibt den Namen einer YAML-Datei an, die Konfigurationsinformationen enthält. Sie können diese Option auch ohne Dateinamen verwenden, und der Axe DevTools Connector wird die Schritte in Suchreihenfolge der Konfigurationsdatei befolgen, um die Konfigurationsdatei zu finden. Weitere Informationen zur Konfigurationsdatei finden Sie unter Konfigurationsdatei.

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

--issue-type type
Verwendet zum Angeben des Problemtyps für SonarQube, Standard: BUG, erlaubte Werte: VULNERABILITY, CODE_SMELL oder BUG

--license-key Schlüssel
Gibt den zu verwendenden Lizenzschlüssel für die Authentifizierung an. Kontaktieren Sie den Deque Help Desk für weitere Informationen zum Erwerb eines Lizenzschlüssels. Diese Option erfordert auch die --local-Option.

--local
Aktiviert das lokale Linden, das den Rechner verwendet, auf dem der Axe DevTools Connector läuft, um Ihre Dateien zu linden, anstatt 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
Specifies the maximale time in milliseconds that the Connector will wait before retrying the server connection upon error. The default is 30,000 milliseconds (30 seconds).

--retry-count Wiederholungsversuche
Gibt die Anzahl der Versuche an, die Serververbindung nach einem Verbindungsfehler erneut herzustellen. Der Connector verdoppelt die Zeit zwischen den Versuchen (beginnend bei 500 Millisekunden oder 0,5 Sekunden), bis er die Backoff-Limit (spezifiziert mit --retry-backoff-limit) erreicht, wo er verbleibt, bis er die angegebene Anzahl von Versuchen erreicht (und fehlgeschlägt) oder ohne Fehler eine Verbindung zum Server herstellt.

--severity Level
Setzt das Schweregradniveau für SonarQube, Standard: MAJOR, erlaubte Werte: BLOCKER, CRITICAL, MAJOR, MINOR oder INFO.

Konfigurationsdatei

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

Das folgende Beispiel zeigt 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 gelindet. Die Regeln im wcag2a-Tag werden verwendet, wie im tags-Abschnitt angegeben. (Siehe Tags für weitere Informationen.)

Der exclude-Wert erlaubt Glob-Werte (*) und Globstar (**), sodass Folgendes erlaubt ist:

exclude:
  - tmp/**/*.html

Im obigen Beispiel werden alle HTML-Dateien im tmp-Verzeichnis und seinen Unterverzeichnissen ausgeschlossen.

Für weitere Informationen über erlaubte Konfigurationsoptionen siehe Konfiguration von Axe DevTools Linter.

Beispielverwendung

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

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

Um alle Lindungen lokal auf dem Computer, auf dem der Axe DevTools Connector läuft, durchzuführen, verwenden Sie die --local-Option:

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