Utilisation du connecteur Axe DevTools Linter

Le connecteur Axe DevTools Linter (également connu sous le nom de le Connecteur) est un outil en ligne de commande pour Linux, macOS et Windows. Il fournit une interface en ligne de commande pour linting vos fichiers afin que vous puissiez automatiser votre vérification d'accessibilité. Vous pouvez, par exemple, l'utiliser pour le scripting et la CI/CD (intégration continue et livraison continue). Le connecteur doit envoyer vos fichiers à une instance d'Axe Linter Server, qu'elle soit hébergée par Deque (SaaS) ou par votre organisation (sur site ou en local), ou vous pouvez effectuer le linting des fichiers localement sans envoyer le contenu de vos fichiers à un serveur en utilisant l'option --local (voir Analyse Locale ci-dessous).

Cas d'utilisation du Connecteur

Le connecteur Axe DevTools peut

• Vérifiez l'accessibilité dans le cadre des builds de Jenkins. Pour plus d'informations, voir Utilisation d'Axe DevTools Linter avec Jenkins.
• Analysez vos fichiers et injectez des informations sur les défauts d'accessibilité dans SonarQube. Voir Utilisation d'Axe DevTools Linter avec SonarQube pour savoir comment configurer cela.
• Être utilisé dans un script de pré-engagement GitHub pour bloquer les engagements qui contiennent des erreurs d'accessibilité. Voir Utilisation d'un hook de pré-commit Git avec Axe DevTools Linter.
• Fournir une base pour vérifier votre code à la recherche de défauts d'accessibilité pour des services tels que :
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Analyse Locale

Le connecteur vous permet d'éviter d'envoyer vos fichiers à un serveur en utilisant analyse locale avec l'option --local en ligne de commande.

• Beaucoup plus rapide que l'utilisation du serveur.

  • Beaucoup moins susceptible de rencontrer des problèmes de réseau ou de charge du serveur. Particulièrement efficace pour analyser un grand nombre de fichiers.
  • Inconvénients de l'analyse locale

• Nécessite plus de ressources de la machine locale.

  • Les mises à jour du connecteur Axe DevTools Linter nécessitent de télécharger et d'installer une nouvelle version depuis Agora.
  • Les mises à jour du connecteur Axe DevTools Linter nécessitent de télécharger une nouvelle version depuis Agora et de l'installer.
  • Aucun suivi d'utilisation (si vous utilisez une clé de licence au lieu d'une clé API).

Clés de licence comparées aux clés API

Le linting local nécessite soit une clé API, soit une clé de licence. Vous pouvez gérer vos clés API dans le cadre de votre compte Axe (ce qui offre de la flexibilité). Cependant, vous devez demander une clé de licence à service d'assistance de Deque. L'utilisation du linting local avec des clés de licence ne suit pas l'utilisation de vos utilisateurs (lignes de code lintées), mais les clés de licence ne nécessitent pas non plus d'authentification à distance.

Options d'installation

Il existe deux options pour installer le connecteur Axe DevTools Linter :

• Configurez un registre npm Agora et utilisez l'infrastructure fournie par Node.js et npm pour installer, exécuter et mettre à jour le Connecteur. Consultez Installation du connecteur Axe DevTools Linter en tant que package npm pour plus d'informations.
• L'autre option consiste à télécharger manuellement le binaire du connecteur pour l'architecture de votre ordinateur et à le préparer à l'utilisation en définissant son bit d'exécution (Linux et macOS) et en supprimant les attributs de quarantaine étendus (macOS). Voir la page de téléchargements.

Variables d'environnement

Le connecteur reconnaît les variables d'environnement suivantes :

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• AXE_SERVICE_URL
• DEBUG

AXE_LINTER_SERVER_URL et AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL définit l'URL de votre instance serveur Axe DevTools Linter. (Vous pouvez aussi définir l'URL du serveur avec -u ou --url options de ligne de commande.) AXE_LINTER_SERVER_PORT spécifie le port sur lequel le serveur écoute, typiquement le port 3000.

Voir Configuration de l'Axe DevTools Linter pour plus d'informations sur la configuration de votre serveur, et voir Référence rapide des URL pour l'URL à utiliser avec la version SaaS de l'Axe DevTools Linter. (Vous n'avez pas besoin de spécifier un port lors de l'utilisation de la version SaaS de l'Axe DevTools Linter.)

L'exemple suivant montre comment définir les variables d'environnement pour l'Axe DevTools Linter fonctionnant sur la machine locale sous Linux ou macOS (bien qu'aucune des variables d'environnement ne soit requise ici car ce sont les valeurs par défaut) :

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

Alternativement, sur Linux et macOS, vous pouvez aussi définir les variables d'environnement sur la même ligne de commande que la commande axe-linter-connector. L'exemple ci-dessous montre cette utilisation. (Cependant, puisque ce sont les valeurs par défaut pour le serveur et le port, vous n'avez pas besoin de les définir.)

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

AXE_SERVICE_URL

La variable d'environnement AXE_SERVICE_URL vous permet de spécifier un serveur alternatif pour valider votre clé API. La valeur par défaut est https://axe.deque.com.

Les clients du cloud privé ont un serveur d'authentification dédié à une URL spécifique au client. Pour utiliser le linting local, définissez AXE_SERVICE_URL comme l'URL de votre instance de cloud privé avant d'exécuter le connecteur :

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

L'URL de votre instance de cloud privé a été fournie lorsque votre instance de cloud privé a été mise en place. Si vous ne l'avez pas, contactez service d'assistance de Deque.

DEBUG

La variable d'environnement DEBUG vous permet de consigner des informations de débogage détaillées pour diagnostiquer des échecs de linting. Définissez la variable d'environnement DEBUG sur axe-devtools-linter:* pour activer la journalisation du débogage, comme indiqué ci-dessous :

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

Options de ligne de commande

Options de ligne de commande requises

Le connecteur Axe DevTools Linter nécessite les deux options suivantes:

-s, --source répertoire-ou-fichier
Indique un fichier ou un répertoire contenant des fichiers à vérifier pour des erreurs d'accessibilité. Les sous-répertoires sont également recherchés. Pour exclure des fichiers du linting, voir l'option exclude dans la section Fichier de Configuration.

-d, --destination répertoire
Le répertoire où le connecteur écrira le rapport d'accessibilité.

-u, --url URL
Spécifie le serveur à utiliser. Le défaut est http://localhost. Pour utiliser le serveur SaaS, spécifiez --url https://axe-linter.deque.com/

Options de ligne de commande facultatives

Plusieurs options peuvent être requises en fonction du serveur auquel vous vous connectez et des autres fonctionnalités ou formats de rapport que vous souhaitez utiliser.

--additional-properties propriété
Ajoute des propriétés supplémentaires aux problèmes dans le rapport d'accessibilité pour les violations trouvées sur composants mappés sur mesure. La seule valeur actuellement prise en charge est customName. Lorsqu'elle est spécifiée, chaque problème impliquant un composant mappé personnalisé acquiert une propriété customName dans le rapport dont la valeur est le nom de la balise du composant personnalisé qui a déclenché la violation. Les problèmes provenant de composants qui ne font pas partie d'un mappage personnalisé n'auront pas de propriété customName.

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

Par exemple, si <MyButton> est un composant mappé personnalisé et déclenche une violation button-name, le problème dans le rapport ressemblera à :

{
    "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 clé API
Spécifie la clé API pour autoriser le linting avec l'instance SaaS Axe DevTools Linter ou pour utiliser le linting local. Voir Obtention d'une clé API SaaS Axe DevTools Linter pour plus d'informations.

--config nom de fichier
Spécifie le nom d'un fichier YAML contenant des informations de configuration. Vous pouvez également utiliser cette option sans nom de fichier, et le connecteur Axe DevTools suivra les étapes dans Fichier de configuration pour localiser le fichier de configuration. Pour des informations sur le fichier de configuration, voir Fichier de Configuration.

--filename nom de fichier
Spécifie le nom du rapport SonarQube, par défaut : axe-linter-report.json

--issue-type type
Utilisé pour indiquer le type de problème pour SonarQube, par défaut : BUG, valeurs autorisées : VULNERABILITY, CODE_SMELL, ou BUG

--license-key clé
Spécifie la clé de licence à utiliser pour l'authentification. Contactez le service d'assistance Deque pour plus d'informations sur l'obtention d'une clé de licence. Cette option nécessite également l'option --local.

--local
Active le linting local, qui utilise la machine sur laquelle le connecteur Axe DevTools est exécuté pour linting vos fichiers plutôt que d'envoyer les fichiers à un serveur. Nécessite une clé API (--api-key) ou une clé de licence (--license-key). Voir Analyse Locale.

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

-R, --reporter rapporteur
Spécifie le rapporteur à utiliser, par défaut : sonarqube

--retry-backoff-limit limite de recul
Spécifie le temps maximum en millisecondes que le connecteur attendra avant de réessayer la connexion au serveur en cas d'erreur. La valeur par défaut est de 30 000 millisecondes (30 secondes).

--retry-count réessais
Spécifie le nombre de fois pour réessayer la connexion au serveur après avoir rencontré une erreur de connexion. Le connecteur doublera le temps entre les essais (en commençant à 500 millisecondes ou 0,5 seconde) jusqu'à atteindre limite de recul (spécifié avec --retry-backoff-limit), où il restera jusqu'à atteindre le nombre de tentatives spécifié (et échoue) ou se connecte au serveur sans erreur.

--severity niveau
Définit le niveau de sévérité pour SonarQube, par défaut : MAJOR, valeurs autorisées : BLOCKER, CRITICAL, MAJOR, MINOR, ou INFO.

Fichier de Configuration

Vous pouvez utiliser un fichier de configuration YAML avec l'option --config.

Ce qui suit montre un exemple de fichier de configuration :

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

Dans l'exemple ci-dessus, la règle image-alt sera ignorée, et le fichier meta-refresh.html ne sera pas linté. Les règles dans la balise wcag2a seront utilisées, comme spécifié dans la section tags. (Voir Tags pour plus d'informations.)

La valeur exclude permet des valeurs glob (*) et globstar (**), c'est donc autorisé :

exclude:
  - tmp/**/*.html

L'exemple ci-dessus exclut tous les fichiers HTML dans le répertoire tmp et ses sous-répertoires.

Pour plus d'informations sur les options de configuration autorisées, voir Configuration d'Axe DevTools Linter.

Exemple d'utilisation

Pour utiliser le connecteur avec le serveur SaaS Axe DevTools Linter, vous pouvez utiliser l'option --api-key comme indiqué ci-dessous :

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

Pour effectuer tout le linting localement sur l'ordinateur exécutant le connecteur Axe DevTools, utilisez l'option --local :

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