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 linterieren, damit Sie Ihre Barrierefreiheitsprüfungen automatisieren können. Sie können ihn zum Beispiel 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, entweder gehostet von Deque (SaaS) oder von Ihrer Organisation (on prem oder on premises), oder Sie können die Dateien lokal linterieren, ohne die Inhalte Ihrer Dateien an einen Server zu senden, indem Sie die --local Option verwenden (siehe Lokale Linterierung unten).

Anwendungsfälle des Connectors

Der Axe DevTools Connector kann

• Barrierefreiheit als Teil von Jenkins-Builds überprüfen. Für weitere Informationen siehe Verwendung von Axe DevTools Linter mit Jenkins.
• Ihre Dateien scannen und Informationen über Barrierefreiheitsfehler in SonarQube einspeisen. Siehe Verwendung von Axe DevTools Linter mit SonarQube für Informationen zur Einrichtung.
• In einem GitHub-Pre-Commit-Skript verwendet werden, um Commits zu blockieren, die Barrierefreiheitsfehler enthalten. 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

Lokale Linterierung

Der Connector ermöglicht es Ihnen, Ihre Dateien nicht an einen Server zu senden, 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 Linting erfordert entweder einen API-Schlüssel oder einen Lizenzschlüssel. Sie können Ihre API-Schlüssel im Rahmen Ihres Axe-Kontos verwalten (sie bieten also Flexibilität). Sie müssen jedoch einen Lizenzschlüssel bei Deque's Help Deskanfordern. Die Verwendung von lokalem Linting mit Lizenzschlüsseln verfolgt nicht die Nutzung Ihrer Benutzer (zeilenweise Code-Überprüfung), aber Lizenzschlüssel erfordern auch keine Remote-Authentifizierung.

Installationsoptionen

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

• Richten Sie ein Agora npm-Registry ein und nutzen Sie die Infrastruktur von NodeJS und npm, um den Connector zu installieren, auszuführen und zu aktualisieren. Siehe Installation des Axe DevTools Linter Connectors als npm-Paket für weitere Informationen.
• Die andere Option ist, den Connector-Download für die Architektur Ihres Computers manuell herunterzuladen und ihn durch Festlegen des Ausführungsbits (Linux und macOS) und das Löschen erweiterter Quarantäne-Attribute (macOS) 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 den -u oder --url Befehlszeilenoptioneneinstellen.) AXE_LINTER_SERVER_PORT gibt den Port an, auf dem der Server hört, typischerweise Port 3000.

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

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 unter Linux und macOS die Umgebungsvariablen auch in der gleichen Befehlszeile wie den axe-linter-connector Befehl setzen. Das untenstehende Beispiel zeigt diese Verwendung. (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 ermöglicht es Ihnen, einen alternativen Server zur Überprüfung Ihres API-Schlüssels anzugeben. Diese Umgebungsvariable ist nützlich für Organisationen, die eine private Serverinstanz zur API-Schlüsselvalidierung verwenden. Der Standardwert ist https://axe.deque.com.

Für weitere Informationen zur Verwendung alternativer Server zur API-Schlüsselvalidierung kontaktieren Sie bitte Deque's Help Desk.

DEBUG

Die DEBUG -Umgebungsvariable ermöglicht es Ihnen, detaillierte Debugging-Informationen zur Diagnose von Linting-Fehlern zu protokollieren. Setzen Sie die DEBUG -Umgebungsvariable auf axe-devtools-linter:* , um die Debug-Protokollierung 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 Dateien enthält, die auf Barrierefreiheitsfehler überprüft werden sollen. Auch Unterverzeichnisse werden durchsucht. Um Dateien von der Prüfung auszuschließen, siehe die exclude Option in der Konfigurationsdatei -Sektion.

-d, --destination directory
Das Verzeichnis, in das der Connector den Barrierefreiheitsbericht schreiben wird.

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

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ätzliche Eigenschaften zu Problemen im Barrierefreiheitsbericht hinzu, die bei benutzerdefinierten gemappten Komponentengefunden wurden. Der derzeit einzige unterstützte Wert ist customName. Wenn angegeben, erhält jedes Problem, das eine benutzerdefinierte gemappte Komponente betrifft, 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 einer benutzerdefinierten Zuordnung sind, werden keine customName -Eigenschaft haben.

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

Zum Beispiel, wenn <MyButton> eine benutzerdefinierte gemappte Komponente ist und eine button-name -Verletzung auslöst, wird das Problem im Bericht wie folgt aussehen:

{
    "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 die Abnahme mit der SaaS Axe DevTools Linter-Instanz zu autorisieren oder um lokale Abnahme 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 einen Dateinamen verwenden, und Axe DevTools Connector folgt den Schritten im Suchreihenfolge der Konfigurationsdatei , um die Konfigurationsdatei zu finden. Für Informationen über die Konfigurationsdatei, siehe Konfigurationsdatei.

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

--issue-type type
Wird verwendet, um den Fehlertyp für SonarQube anzugeben, Standard: BUG, erlaubte Werte: VULNERABILITY, oder CODE_SMELL, BUG

--license-key Schlüssel
Gibt den Lizenzschlüssel für die Authentifizierung an. Kontaktieren Sie den Deque Help Desk , um mehr Informationen zum Erhalt eines Lizenzschlüssels zu erhalten. Diese Option erfordert außerdem die --local Option.

--local
Aktiviert das lokale Linting, bei dem der Rechner, auf dem der Axe DevTools Connector läuft, zum Linten Ihrer Dateien verwendet wird, anstatt die Dateien an einen Server zu senden. Benötigt 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
Legt den zu verwendenden Reporter fest, Standard: sonarqube

--retry-backoff-limit Backoff-Limit
Gibt die maximale Zeit in Millisekunden an, die der Connector wartet, bevor er die Serververbindung bei einem Fehler erneut versucht. Der Standardwert beträgt 30.000 Millisekunden (30 Sekunden).

--retry-count Wiederholungsversuche
Legt die Anzahl der Wiederholungsversuche für die Serververbindung nach einem Verbindungsfehler fest. Der Connector wird die Zeit zwischen den Versuchen verdoppeln (beginnend bei 500 Millisekunden oder 0,5 Sekunden), bis er das Backoff-Limit erreicht hat (festgelegt mit --retry-backoff-limit), bei dem er bleibt, bis entweder die angegebene Anzahl von Wiederholungen erfolgt (und fehlschlägt) oder er sich fehlerfrei mit dem Server verbindet.

--severity Level
Legt das Schweregradniveau für SonarQube fest, Standard: MAJOR, zulässige 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 gelintet. 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 das Folgende erlaubt ist:

exclude:
  - tmp/**/*.html

Im obigen Beispiel werden alle HTML-Dateien im tmp Verzeichnis und dessen Unterverzeichnisse.

Für weitere Informationen über die zulässigen Konfigurationsoptionen sehen Sie 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 Linting-Vorgänge lokal auf dem Computer auszuführen, der den Axe DevTools Connector betreibt, verwenden Sie die --local Option:

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