Utilisation du connecteur axe DevTools Linter

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

Cas d'utilisation du connecteur

Le connecteur axe DevTools peut

• Vérifier l'accessibilité dans le cadre des builds Jenkins. Pour plus d'informations, consultez Utilisation d'axe DevTools Linter avec Jenkins.
• Scannez vos fichiers et alimentez SonarQube avec des informations sur les défauts d'accessibilité. Consultez Utilisation d'axe DevTools Linter avec SonarQube pour plus d'informations sur la façon de configurer cela.
• Être utilisé dans un script de pré-validation GitHub pour bloquer les validations contenant des erreurs d'accessibilité. Voir Utilisation d'un hook Git Pre-Commit avec axe DevTools Linter.
• Fournir une base pour vérifier votre code afin de détecter les défauts d'accessibilité pour des services tels que :
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Linting local

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

• Avantages du linting local

  • Beaucoup plus rapide que d'utiliser le serveur.
  • Beaucoup moins susceptible de rencontrer des problèmes de réseau ou de charge de serveur. Il est particulièrement efficace lors de l'analyse d'un grand nombre de fichiers.

• Inconvénients du linting local

  • Nécessite plus de ressources machine locales.
  • Les mises à jour du connecteur axe DevTools Linter nécessitent le téléchargement et l'installation d'une nouvelle version depuis Agora.
  • 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 (elles offrent donc de la flexibilité). Cependant, vous devez demander une clé de licence au Deque's Help Desk. L'utilisation du linting local avec les 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.

Configuration

Pour plus d'informations sur le téléchargement de axe DevTools Linter Connector, consultez Téléchargement de axe DevTools Linter Connector.

Sous Linux et macOS, le fichier de commandes doit avoir son indicateur d’exécution défini, comme indiqué ci-dessous :

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

Lorsque vous téléchargez l'exécutable sur macOS, l'attribut de quarantaine est défini, que vous devez supprimer avant de pouvoir utiliser le connecteur :

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

Renommez l'exécutable (pour supprimer le système d'exploitation et le trait d'union à la fin du nom de fichier) et copiez-le ou liez-le dans un répertoire sur votre chemin afin qu'il puisse être utilisé avec d'autres outils (comme avec un hook de pré-validation Git, voir Utilisation d'un hook de pré-validation Git avec axe DevTools Linter).

Variables d’environnement

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

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• DEBUG

et AXE_LINTER_SERVER_PORT

définit l'URL de votre instance de serveur axe DevTools Linter. (Vous pouvez également définir l'URL du serveur avec les ou [options de ligne de commande].) spécifie le port sur lequel le serveur écoute, généralement le port 3000. -u --url (#required-command-line-options) AXE_LINTER_SERVER_PORT

Consultez Configuration d'axe DevTools Linter pour plus d'informations sur la configuration de votre serveur, et consultez Référence rapide d'URL pour l'URL à utiliser avec la version SaaS d'axe DevTools Linter. (Vous n'avez pas besoin de spécifier un port lorsque vous utilisez la version SaaS d'axe DevTools Linter.)

L'exemple suivant montre la définition de variables d'environnement pour axe DevTools Linter exécuté sur la machine locale sous Linux ou macOS (bien qu'aucune variable 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, sous Linux et macOS, vous pouvez également 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, comme 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 .

DEBUG

La variable d'environnement vous permet d'enregistrer des informations de débogage détaillées pour diagnostiquer les échecs de linting. DEBUG Définissez la variable d'environnement sur axe-devtools-linter: DEBUG pour activer la journalisation de 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

axe DevTools Linter Connector nécessite les deux options suivantes :

-s, --source répertoire-ou-fichier
Indique un fichier ou le répertoire contenant les fichiers à vérifier pour les erreurs d'accessibilité. Les sous-répertoires sont également recherchés. Pour exclure des fichiers de l'analyse, consultez l'option exclure dans la section Fichier de configuration .

-d, --destination répertoire
Répertoire dans lequel Connector écrira le rapport d'accessibilité.

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

Options de ligne de commande optionnelles

Plusieurs options peuvent être nécessaires, selon le serveur auquel vous vous connectez et les autres fonctionnalités ou formats de rapport que vous souhaitez utiliser.

--clé API clé API
Spécifie la clé API pour autoriser le linting avec l'instance SaaS axe DevTools Linter ou pour utiliser le linting local. Consultez Obtention d'une clé API axe DevTools Linter SaaS 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 axe DevTools Connector suivra les étapes de Fichiers de configuration multiples pour localiser les fichiers de configuration. Pour plus d'informations sur le fichier de configuration, voir Fichier de configuration.

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

--type-problème type
Utilisé pour indiquer le type de problème pour SonarQube, par défaut : BUG, valeurs autorisées : VULNÉRABILITÉ, MAUVAISE PRATIQUE ou BUG

--license-key key
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 s'exécute axe DevTools Connector pour analyser vos fichiers plutôt que d'envoyer des fichiers à un serveur. Nécessite une clé API (--api-key) ou une clé de licence (--license-key). Voir Local Linting.

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

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

--retry-backoff-limit backoff-limit
Spécifie le temps maximal en millisecondes pendant lequel 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).

--nombre-de-réessais réessais
Spécifie le nombre de fois où il faut réessayer la connexion au serveur après avoir rencontré une erreur de connexion. Le connecteur doublera le temps entre les tentatives (à partir de 500 millisecondes ou 0,5 seconde) jusqu'à ce qu'il atteigne la limite de temporisation (spécifiée par --retry-backoff-limit), où il restera jusqu'à ce qu'il atteigne le nombre de tentatives spécifié (et échoue) ou se connecte au serveur sans erreur.

--severity ** Définit le niveau de gravité de SonarQube, par défaut : MAJEUR, valeurs autorisées : BLOQUEUR, CRITIQUE, MAJEUR, MINEUR ou INFO

Fichier de configuration

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

Voici 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 analysé par le linter. Les règles de la balise wcag2a seront utilisées, comme spécifié dans la section tags . (Voir Tags pour plus d'informations.)

La valeur exclude autorise les valeurs glob (*) et globstar (**), donc ce qui suit est autorisé :

exclude:
  - tmp/**/*.html

L'exemple ci-dessus exclurait tous les fichiers HTML dans le répertoire tmp ou l'un de ses sous-répertoires.

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

Exemple d'utilisation

Pour utiliser Connector 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 toutes les analyses localement sur l'ordinateur exécutant axe DevTools Connector, utilisez l'option --local  :

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