Utilisation de l'action GitHub Axe Developer Hub

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Vérifiez automatiquement les PR et les commits pour détecter les défauts d'accessibilité

Not for use with personal data

Exigences :

Un projet web avec intégration Axe Watcher

ID de projet Axe Developer Hub

Clé API Axe Developer Hub

Une suite de tests que vous avez modifiée en suivant les instructions d'installation dans Axe Developer Hub

Un flux de travail GitHub qui exécute votre suite de tests chaque fois que quelqu'un effectue un commit dans votre dépôt

note

Pour d'autres pipelines CI/CD (tels que ceux sur GitLab, Bitbucket ou CircleCI) ou lorsque vous utilisez Axe DevTools pour les API web/CLI, vous pouvez utiliser le service REST Axe Developer Hub comme base pour votre propre intégration.

Vue d'ensemble

Le Axe Developer Hub GitHub Action vous permet de configurer des workflows GitHub pour des projets web intégrant Axe Watcher, afin de bloquer les commits et les pull requests s'ils contiennent des erreurs d'accessibilité.

Lorsque votre suite de tests modifiée s'exécute, il associe les résultats d'accessibilité à un SHA de commit Git et envoie cette information aux serveurs de Deque. L'action GitHub s'exécute après le déroulement de votre suite de tests, et interroge les serveurs de Deque pour les résultats d'accessibilité associés au dernier commit SHA de la branche en cours.

Les nouveaux et résolus problèmes que les rapports d’action comptent utilisent la référence du précédent commit ayant un scan sur cette même branche, pas la branche par défaut. Seuls les commits contre lesquels votre suite de tests a réellement été exécutée ont un scan, donc ce commit de référence peut être plusieurs commits en arrière. Si ce commit a exécuté un ensemble de tests différent, les comptes refléteront la différence de couverture plutôt qu’un changement réel ; voir Bonnes pratiques pour des comparaisons précises.

Configuration

Créer une variable d'environnement pour votre ID de projet - Nous recommandons de stocker l'ID de votre projet dans une variable d'environnement ou une autre variable GitHub. Pour cet exemple, nous stockerons l'ID du projet comme une variable d'environnement appelée PROJECT_ID.
Créer un secret pour votre clé API - Pour cet exemple, le secret créé s'appelle AXE_DEV_HUB_API_KEY, avec votre clé API personnelle comme valeur, mais vous pouvez nommer le secret comme vous le souhaitez. Il doit être référencé par le même nom dans le travail du flux de travail. Votre clé API est une information d'identification : stockez-la toujours comme un secret GitHub Actions plutôt que de l’encoder directement dans le fichier de flux de travail.
Ajouter des vérifications d'accessibilité à votre suite de tests - Assurez-vous d'avoir complété les étapes dans configuration du projet pour intégrer les contrôles d'accessibilité dans la suite de tests utilisée dans votre pipeline CI/CD (Axe Watcher).
Modifier votre workflow actuel - Vous devez modifier votre workflow de test actuel dans .github/workflows et ajouter l'action GitHub après le travail qui exécute votre suite de tests.

Exemple de travail

Le travail suivant votre action de suite de tests doit exécuter l'action GitHub Axe Developer Hub. Reportez-vous à l'exemple suivant :

jobs:

# ...
# your-CI-test
# ...

# Add the following new job:
# Be sure to replace <choose_latest_tag> with the appropriate version tag
  axe-dev-hub:
    runs-on: ubuntu-latest
    needs: your-CI-test
    steps:
      - uses: actions/checkout@v5
      - uses: dequelabs/axe-devhub-action@<choose_latest_tag>
        with:
          api_key: ${{ secrets.axe_DEV_HUB_API_KEY }}
          project_id: ${{ env.PROJECT_ID }}

Le travail axe-dev-hub dans l'exemple dépend du travail qui exécute votre suite de tests, spécifié par la ligne needs: your-CI-test. Assurez-vous de mettre à jour cette ligne pour qu'elle corresponde au nom du travail qui exécute votre suite de tests.

Vous pouvez utiliser plusieurs paramètres d'entrée pour l'action GitHub. Par exemple, vous pouvez activer le seuil a11y en utilisant enable_a11y_threshold: true. Une liste complète des paramètres d'entrée se trouve dans le Axe Developer Hub GitHub Action README.

note

Vous n'avez pas besoin de définir le paramètre server_url si vous avez créé votre projet sur axe.deque.com. Si votre organisation utilise une instance régionale, un cloud privé ou un déploiement sur site de Axe Developer Hub, vous devez configurer server_url sur l'URL de base de cette instance (par exemple, https://axe-eu.deque.com).

Résultats

L'action GitHub définit plusieurs paramètres de sortie, y compris un décompte des problèmes d'accessibilité détectés, des problèmes résolus, et des problèmes dépassant le seuil a11y.

Si vous n'avez pas activé le seuil a11y, l'action GitHub échouera si plus de zéro erreurs d'accessibilité sont présentes. Si activé, uniquement les violations dépassant le seuil a11y provoqueront l'échec de l'action GitHub. En savoir plus sur l'utilisation du seuil a11y pour personnaliser Axe Developer Hub en fonction des priorités de votre organisation.

L'échec de l'action GitHub attachera un commentaire similaire à celui ci-dessous à votre demande de tirage et peut bloquer la fusion.

Cliquez sur le lien dans le commentaire de la demande de tirage pour consulter les informations sur les défauts d'accessibilité de ce commit dans le Hub de développement Axe.

Dépannage

Vous pourriez recevoir une erreur telle que la suivante :

Error: Resource not accessible by integration

Vérifiez que vous avez les autorisations nécessaires sur la page des paramètres pour les actions. Vous avez besoin des autorisations de lecture et écriture pour permettre à l'action d'ajouter des commentaires aux pull requests. Pour plus de granularité, vous pouvez choisir d'utiliser une GITHUB_TOKEN différente pour l'action GitHub. Ajoutez cette valeur au paramètre d’entrée github_token.

Exemple de flux de travail

Si vous n'avez pas déjà de workflow qui exécute votre suite de tests, vous pouvez utiliser le exemple de workflow comme point de départ pour créer votre propre exécuteur de tests.

L'exemple de workflow est appelé Tests (tests.yml) et s'exécute sur tout commit ou pull request. Le travail qui exécute la suite de tests modifiée, cypress, montre comment exécuter une suite de tests Cypress. Le travail suivant dans l'exemple, axe-dev-hub, est une invocation de l'action GitHub Axe Developer Hub.

Le travail de votre suite de tests doit toujours s'exécuter avant l'action GitHub Axe Developer Hub.

tip

Le répertoire d'exemple contient un projet de test complet avec lequel vous pouvez expérimenter.

Références

Dépôt principal pour l'Axe Developer Hub GitHub Action
- Le README contient des informations sur les paramètres d'entrée et de sortie
- Retrouvez les métadonnées pour l'action GitHub dans action.yml
- Consultez périodiquement l'exemple d'invocation dans le dépôt de l'action GitHub pour la configuration la plus récente des travaux
Trouvez plus d'informations sur les sujets de cette page dans la documentation de GitHub