Rédiger des tests Selenium

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

Écrire des tests d'accessibilité avec Selenium WebDriver utilisant Axe DevTools pour le Web en Java

Not for use with personal data

Cette configuration Axe DevTools n'est pas liée de manière inhérente à une bibliothèque d'assertion. Cela permet des tests d'accessibilité simplifiés ainsi qu'une personnalisation complète des tests et l'utilisation avec des assertions personnalisées.

Prérequis

Pour utiliser Axe DevTools Java Selenium et en produire des résultats, vous devez avoir déjà créé un fichier de test avec Axe DevTools et avoir importé et initialisé votre choix de Selenium WebDriver. Si vous n'avez pas effectué cette étape, lisez d'abord ce guide pour savoir comment procéder.

Exécuter un scan

Avec cette configuration, l'exécution d'un scan d'accessibilité de base nécessite seulement trois lignes de code. Dans votre fichier de test, remplacez <URL> par l'adresse web souhaitée de la page que vous voulez tester. Les résultats du scan sont sauvegardés dans la variable results.

webdriver.get("<URL>");
Results results = axeSelenium.run(axedriver);
webdriver.quit();

Utiliser les résultats du scan

Une fois le scan effectué, vous voudrez peut-être faire quelque chose avec les résultats. L'option la plus simple est d'imprimer les résultats sur la console.

System.out.print(results);

Vous pouvez également utiliser les résultats pour vérifier les violations d'accessibilité. La façon la plus simple de le faire est avec une déclaration comme celle-ci :

if (!results.violationFree()) { 
    //do something, like throw an exception
}

Pour plus d'informations sur la façon d'utiliser l'objet des résultats pour écrire des tests personnalisés, consultez la page sur en utilisant les résultats.

Fichier de test d'exemple

Ce fichier de test fonctionne avec les mêmes blocs de construction couverts dans importer et initialiser ainsi que le guide d'écriture des tests sur cette page.

import com.deque.html.axedevtools.selenium.*;
import com.deque.html.axedevtools.selenium.results.*;

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class Example {
    public static void main(final String[] args) {
        AxeSelenium axeselenium = new AxeSelenium();
        WebDriver webdriver = new ChromeDriver();
        AxeDriver axedriver = new AxeDriver(wd);

        webdriver.get("<URL>");

        Results results = axeselenium.run(axedriver);

        webdriver.quit();

        if (!results.violationFree()) {
            int violationCount = results.getViolations().size();
            System.out.printf("Found %d violations!\n", violationCount);
            System.exit(1);
        }

        System.out.println("No violations found!");
    }
}

Dans cet exemple, Chrome et ChromeDriver sont utilisés. Cela peut être remplacé par tout autre pilote de navigateur selenium et navigateur. Si ce fichier de test trouve des problèmes d'accessibilité, il imprime le nombre de violations trouvées et se termine avec le code de sortie 1 (erreur). Pour utiliser ce fichier de test dans votre propre environnement, vous devrez ajouter une URL à la ligne.

webdriver.get("<URL>");

Référence supplémentaire

En plus de l'utilisation de base décrite ci-dessus, Axe DevTools Java Selenium propose plusieurs méthodes de chaînage pour modifier la façon dont l'analyse est exécutée. Ces méthodes peuvent modifier la portée et le jeu de règles de l'analyse pour toute configuration souhaitée. Par défaut, la page entière est analysée et vérifiée pour les violations d'accessibilité selon les directives du niveau AA de la norme WCAG 2.1, avec les règles de bonnes pratiques et expérimentales désactivées. Les paramètres de ces méthodes de chaînage restent sur l'objet AxeSelenium, et include et exclude ajoutent aux zones précédentes chaque fois que vous les appelez, donc réutiliser un objet pour une seconde analyse configurée différemment conserve les paramètres de la première analyse. Créez un nouveau AxeSelenium pour chaque analyse configurée différemment.

Délimitation

Par défaut, la page entière est analysée. Cependant, Axe DevTools prend en charge la possibilité d'analyser des parties spécifiques d'une page grâce à ses méthodes de chaînage de portée. Ces méthodes de portée modifient efficacement la « surface » de la page à analyser pour la ou les zones cibles souhaitées. De plus, une méthode d'ignorance des violations est disponible. Cette méthode ne réduit pas la zone de l'analyse ; elle ignore les violations d'une règle lorsqu'elle échoue sur un élément spécifique, et le reste de la page est toujours vérifié comme d'habitude. Toutes ces méthodes fonctionnent à partir des zones de sélecteurs CSS. La zone de chaque sélecteur CSS sur une page donnée peut être déterminée en utilisant l'outil "inspecter l'élément" des outils de développement de votre navigateur.

Méthodes de délimitation

Comme expliqué ci-dessus, ces méthodes modifient efficacement la surface de la page à scanner. Il existe deux méthodes dans cette catégorie, une méthode "inclusive" et une méthode "exclusive". Elles peuvent être chaînées mutuellement pour créer plusieurs enclaves et exclaves de surface de scan.

Délimitation - Inclusion

La méthode de chaînage de portée include modifie l'analyse pour ne s'exécuter que dans la zone de page spécifiée par le ou les sélecteurs CSS qui lui sont passés. Il existe plusieurs façons d'utiliser la méthode include : portée unique, portée multiple, portée composée et portée IFrame.

Cette méthode peut être utilisée avec un seul sélecteur de la manière suivante :

axeselenium.include("#selector1").run(axedriver);

Ce scan ne s'exécutera que dans le périmètre de sélection 1.

Vous pouvez configurer un scan avec plusieurs portées :

axeselenium.include("#selector1").include("#selector2").run(axedriver);

Cet appel analysera dans le champ du sélecteur 1 et du sélecteur 2. Ils peuvent soit être séparés par des virgules, soit déclarés dans un appel include séparé.

Une délimitation composée peut être réalisée avec la syntaxe suivante :

axeselenium.include("#selector1 .selector2").run(axedriver);

Cette délimitation composée entraîne uniquement le scan des éléments avec le sélecteur 2 à l'intérieur du sélecteur 1. Cela est configuré en ne séparant pas les sélecteurs par des virgules.

Pour délimiter à l'intérieur d'un IFrame, un List<String> peut être passé. Le périmètre à scanner à l'intérieur de l'IFrame est passé comme paramètre supplémentaire.

axeselenium.include(Arrays.asList(new String[] {"#frame1", "#selector1"})).run(axedriver);

Ce scan s'exécute sur les éléments dans le sélecteur 1, qui est à l'intérieur du cadre 1.

La délimitation à l'intérieur de plusieurs IFrames fonctionne de la même manière que la sélection multiple standard. Appelez simplement include à nouveau.

axeselenium.include(Arrays.asList(new String[] {"#frame1", "#selector1"}))
    .include(Arrays.asList(new String[] {"#frame2", "#selector2"})).run(axedriver);

Ce scan ne s'exécute qu'à l'intérieur du sélecteur 1 dans le cadre 1, et du sélecteur 2 dans le cadre 2.

Il est également possible de délimiter à l'intérieur d'IFrames imbriqués :

axeselenium.include(Arrays.asList(new String[] {"#frame1", "#frame2", "#selector1"})).run(axedriver);

Ce scan s'exécute dans le périmètre du sélecteur 1 à l'intérieur du cadre 2, qui se trouve lui-même à l'intérieur du cadre 1.

Délimitation - Exclusion

En plus de la méthode de chaîne include, cette API a une méthode exclude. Cette méthode modifie l'analyse de sorte que seuls les éléments en dehors de la portée spécifiée soient analysés. Son installation et son utilisation sont identiques à la méthode include, alors reportez-vous à la section ci-dessus pour plus de détails et d'exemples sur son utilisation. Un détail important à retenir est que les méthodes include et exclude peuvent être chaînées entre elles pour créer des portées complexes beaucoup plus simplement qu'en utilisant uniquement include ou exclude.

Cet exemple montre une façon de coupler les méthodes include et exclude :

axeselenium.include("#selector1").exclude("#selector2").run(axedriver);

Ce scan ne s'exécute que sur la partie de la page qui est dans le sélecteur 1 qui n'est pas également dans le sélecteur 2.

Délimitation - Ignorer les violations

La dernière méthode de chaîne liée à la portée est la méthode d'ignorance des résultats. Cette méthode n'altère pas la portée globale de l'analyse ; elle ignore les violations d'une règle lorsque cette règle échoue sur un élément spécifique. Elle fonctionne en passant l'target de l'élément que vous souhaitez ignorer, tel qu'il apparaît dans les résultats, associé à la règle dont il viole. La cible est écrite de la manière dont Java énumère une liste, avec le sélecteur entre crochets, tel que "[.sidebar]". Un appel ignoring par règle est suffisant, car une correspondance supprime l'entrée entière de la règle. Ne l'appelez pas deux fois pour la même règle : si les deux cibles correspondent à des éléments défaillants, l'analyse lance un IllegalStateException.

axeselenium.ignoring("[.sidebar]", "color-contrast").ignoring("[#branded-content]", "image-alt").run(axedriver);

Cette analyse ignorera la violation du contraste des couleurs sur la barre latérale et la violation du texte alternatif sur l'image de contenu marquée. Si la cible correspond à un élément qui échoue la règle, l'entrée entière de la règle est retirée des violations, y compris les échecs sur d'autres éléments. Voir AxeSelenium.ignoring(String, String) dans la référence API.

Règles

Il existe trois façons de modifier votre configuration de règles pour chaque analyse. Ces différentes méthodes permettent une granularité différente lors de la sélection des règles à tester. La méthode des jeux de règles la moins granulaire sélectionne un jeu de règles ou un groupe plus large de règles basé sur les normes d'accessibilité communes. La méthode des normes de jeux de règles légèrement plus granulaire, également connue sous le nom de balises, sélectionne les règles en fonction des domaines d'une norme d'accessibilité plus large dans lesquels elles s'insèrent. Enfin, il existe trois options de configuration avec une règle à la fois. Ensemble, ces méthodes de chaîne vous permettent de régler votre analyse pour exécuter précisément les règles que vous souhaitez.

Pour des informations sur les règles axe-core, visitez la page de vue d'ensemble des règles.

Sélection de règles

Cette méthode sélectionne des règles par leur association la plus agrégée - un ensemble de règles. Un ensemble de règles est une collection de toutes les règles qui se rapportent à une norme d'accessibilité reconnue dans l'industrie. Ensembles de règles pour WCAG 2.0, 2.1 et 2.2; ADA Section 508; Trusted Tester v5; EN 301 549; et RGAA. De plus, des règles de bonnes pratiques peuvent être activées avec un indicateur booléen.

Les ensembles de règles sont souvent composés de plusieurs tags, qui sont des règles groupées par des distinctions plus spécifiques. Par exemple, l'ensemble wcag2 contient toutes les règles étiquetées wcag2a règles de niveau A pour WCAG 2.0, wcag2aa pour les règles de niveau AA pour WCAG 2.0, et wcag2aaa pour les règles de niveau AAA pour WCAG 2.0.

Utilisez cette option lorsque vous souhaitez sélectionner un ensemble de règles non modifié.

axeselenium.forRuleset("wcag2.1").run(axedriver);

Ce test sera exécuté uniquement avec les règles de WCAG 2.1.

Pour activer les règles de bonnes pratiques, utilisez la deuxième forme de forRuleset.

axeselenium.forRuleset("wcag2.1", true).run(axedriver);

Sélection de la norme

La méthode de chaîne de normes d'accessibilité ou de tags permet une granularité légèrement plus fine au sein des ensembles de règles d'axe-core. Pour les règles basées sur WCAG, cette méthode vous permet de sélectionner uniquement les règles étiquetées A simple ou AA double. Cette liste détaille les noms de tags disponibles et leurs normes correspondantes.

Cette option est particulièrement utile lors du test d'une partie spécifique d'un ensemble de règles, par exemple, uniquement les règles A simple sous WCAG 2.0.

Nom de tag Norme d'accessibilité
wcag2a WCAG 2.0 Niveau A
wcag2aa WCAG 2.0 Niveau AA
wcag2aaa WCAG 2.0 Niveau AAA
wcag21a WCAG 2.1 Niveau A
wcag21aa WCAG 2.1 Niveau AA
wcag21aaa WCAG 2.1 Niveau AAA
wcag22a WCAG 2.2 Niveau A
wcag22aa WCAG 2.2 Niveau AA
wcag22aaa WCAG 2.2 Niveau AAA
section508 Section 508
EN-301-549 EN 301 549
RGAAv4 RGAA Version 4
TTv5 Trusted Tester v5
meilleures-pratiques Meilleures pratiques approuvées par Deque

Bien qu'elles ne soient pas définies explicitement comme une partie de toute norme d'accessibilité, nous proposons un certain nombre de règles que nous appelons « meilleures pratiques ». Bien que non strictement nécessaires, tester avec ces règles aidera votre site web à être aussi équitable que possible dans son utilisation.

Une seule norme peut être sélectionnée de la manière suivante :

axeselenium.accordingTo("wcag2a").run(axedriver);

Ce test sera exécuté uniquement avec les règles étiquetées sous WCAG 2.0 niveau A.

En outre, plusieurs tags peuvent être spécifiés pour sélectionner plusieurs normes d'accessibilité :

axeselenium.accordingTo("wcag2a", "section508").run(axedriver);

Ces tests exécuteront à la fois les règles étiquetées sous WCAG 2.0 niveau A et ADA Section 508.

Sélection de la règle

Enfin, vous pouvez modifier votre ensemble de règles par une seule règle. Pour des informations sur les noms de toutes les règles d'axe-core et sur ce que teste chaque règle, consultez le documentation des descriptions de règles axe-core.

Ces méthodes fonctionnent bien lorsque le groupe de règles final que vous souhaitez est uniquement différent d'un ensemble de règles ou d'une norme/étiquette existant que par quelques règles individuelles. Pour créer un ensemble de règles entièrement personnalisé, consultez nos options de règles personnalisées.

Vérification de règles supplémentaires

La méthode de chaîne de vérification vous permet d'ajouter des règles supplémentaires pour tester en plus de votre ensemble de règles standard.

Cette méthode peut être utilisée pour vérifier une règle supplémentaire unique :

axeselenium.checking("label").run(axedriver);

où l'analyse est effectuée avec l'ensemble de règles par défaut en plus de la règle « label ».

Pour vérifier plusieurs règles supplémentaires, passez-les toutes en un seul appel. Appeler checking une seconde fois remplace les règles du premier appel au lieu de les ajouter.

axeselenium.checking("label", "tabindex").run(axedriver);

où l'analyse est exécutée avec l'ensemble de règles par défaut ainsi que les règles « label » et « tabindex ».

Elle peut également servir à ajouter une ou plusieurs règles à un tag spécifié :

axeselenium.accordingTo("wcag2a").checking("tabindex").run(axedriver);

où l'analyse est effectuée en testant par rapport aux règles de niveau A de la WCAG 2.0, avec l'ajout de la règle « tabindex ».

Sauter des Règles

Similaire à la méthode de vérification, la méthode de saut modifie les règles par défaut à utiliser par la ou les règles spécifiées. Cependant, au lieu de les ajouter au jeu de règles, la méthode de saut supprime la ou les règles spécifiées de celles utilisées pour tester la page. Son installation et son utilisation sont identiques à la méthode de vérification, alors reportez-vous à la section ci-dessus pour plus de détails et d'exemples sur son utilisation.

axeselenium.accordingTo("wcag2a").skipping("label").run(axedriver);

Cet exemple montre une analyse testant selon les règles du niveau A de la WCAG 2.0, avec la suppression de la règle "label".

Les méthodes de vérification et de saut définissent la même option, donc seule la dernière des deux appels dans une chaîne prend effet. Ne les combinez pas dans la même analyse.

Vérification Uniquement

La méthode de vérification uniquement vérifie seulement la ou les règles spécifiées. Toute règle non spécifiquement indiquée ne sera pas incluse dans l'analyse.

Cette méthode en chaîne peut être utilisée pour spécifier une règle unique :

axeselenium.checkingOnly("tabindex").run(axedriver);

où l'analyse est effectuée avec uniquement la règle « tabindex ».

Pour spécifier plus d'une règle, passez-les toutes en un seul appel. Un second appel checkingOnly remplace les règles du premier. checkingOnly et accordingTo définissent également la même option, donc seule la dernière des deux prend effet.

axeselenium.checkingOnly("label", "tabindex").run(axedriver);

où l'analyse est effectuée avec uniquement les règles « label » et « tabindex ».

Désactivation du iframe

Sur les pages volatiles, les iframes peuvent causer des problèmes. Axe doit être injecté dans chaque cadre et configuré de la même manière dans chacun d'eux. Si des iframes sont ajoutés ou supprimés pendant que AxeSelenium::run teste votre page, il est possible que des exceptions soient levées ou qu'un comportement inattendu se produise. Par mesure de sécurité, AxeSelenium expose une méthode pour désactiver toute interaction avec les iframes, AxeSelenium::disableIframeTesting. Lorsqu'elle est activée, axe-core ne sera pas injecté dans les iframes de la page, ni exécuté dans ces iframes. Seule la page de niveau supérieur sera vérifiée.

Elle peut être utilisée ainsi :

axeselenium.disableIframeTesting().run(axedriver);
note

L'utilisation de cette méthode n'est pas recommandée. Il est toujours préférable d'attendre que votre page se stabilise avant de la transmettre à AxeSelenium::run.

Service d'utilisation

Obtenez un aperçu des tendances d'utilisation d'Axe DevTools au sein de votre organisation

Le service d'utilisation peut être configuré par des variables d'environnement ou par des méthodes lors de l'exécution. Lorsque les deux sont utilisés, les valeurs des méthodes sont prises en compte. Remarque : tous les champs de données du service d'utilisation ne peuvent pas être définis par des méthodes.

Par défaut, le service d'utilisation est activé et les résultats sont envoyés à https://usage.deque.com. Définissez la variable d'environnement AXE_TRACK_USAGE sur false pour le désactiver. Si vos événements d'utilisation n'atteignent pas Deque, définissez explicitement la variable d'environnement AXE_METRICS_URL.

Variables d'environnement

Ces variables d'environnement vous permettent de configurer le service d'utilisation et de modifier les propriétés des événements signalés.

Nom Type Peut remplacer Description
AXE_DISTINCT_ID Chaîne de caractères — Un identifiant UUID qui reste le même pour l'utilisateur connecté (sauf s'il est régénéré). En Ruby, cette variable est nommée DEQUE_DISTINCT_ID.
AXE_INCLUDE_TEST_RESULTS Booléen — Définir sur true pour inclure les résultats complets de axe-core dans l'objet testResults de chaque événement (la valeur par défaut est false). Pris en charge uniquement par la CLI et les API Node.js.
AXE_METRICS_URL Chaîne de caractères — L'URL du point de terminaison de l'utilisation REST (la valeur par défaut est https://usage.deque.com)
AXE_TRACK_USAGE Booléen — Définir sur false pour désactiver le rapport de service d'utilisation. Le rapport est activé par défaut.
AXE_ACTOR Chaîne de caractères — Définissez sur human ou automation pour remplacer si les événements enregistrent une personne ou un pipeline automatisé comme exécutant les tests. Par défaut, automation est détecté à partir des variables d'environnement CI courantes. Pris en charge uniquement par le CLI, les API Node.js et l'API Ruby.
AXE_APPLICATION Chaîne de caractères faux L'application qui a été utilisée pour vérifier les erreurs d'accessibilité
AXE_DEV_INSTANCE Booléen vrai Indique si cet événement provient d'actions d'un développeur logiciel. Utile pour marquer et supprimer ensuite les événements enregistrés pendant le développement ou les tests.
AXE_DEPARTMENT Chaîne de caractères vrai Le département de l'utilisateur au sein de l'organisation
AXE_KEYCLOAK_ID Chaîne de caractères faux L'ID Keycloak de l'utilisateur
AXE_LOGGED_IN Booléen faux Enregistre si l'utilisateur est connecté à l'application en test
AXE_ORGANIZATION Chaîne de caractères vrai L'organisation de l'utilisateur. Pour que votre utilisation apparaisse dans Axe Reports, définissez ceci sur l'ID de votre organisation (contactez Deque pour l'obtenir).
AXE_SESSION_ID Chaîne de caractères faux Un UUID identifiant la session de l'utilisateur
AXE_TEAMS Chaîne de caractères faux Les équipes exécutant les tests, sous la forme d'un tableau JSON d'objets { "id": "...", "name": "..." } ou du chemin vers un fichier JSON en contenant un. Une valeur passée à l'option --set-teams du CLI, à la méthode setTeams d'une API Node.js, ou à la clause for_teams ou la propriété de configuration teams de l'API Ruby a priorité. Pris en charge uniquement par le CLI, les API Node.js et l'API Ruby.
AXE_USER_ID Chaîne de caractères faux L'identité d'un utilisateur spécifique, telle qu'une adresse e-mail, un nom ou un identifiant de connexion. Axe Reports compte les utilisateurs uniques à partir de cette valeur.
AXE_USER_JOB_ROLE Chaîne de caractères faux Le rôle professionnel de l'utilisateur
AXE_USER_STATUS Chaîne de caractères faux Informations de statut que vous souhaitez associer à l'utilisateur

Activer le suivi

Cette méthode permet aux utilisateurs de choisir d'envoyer ou non des données au service d'utilisation. L'envoi est activé par défaut.

.enableTracking(boolean state)

Définir l'URL de suivi

Cette méthode permet aux utilisateurs de modifier l'endroit où les données de métriques d'utilisation sont envoyées. Par défaut, cela revient à https://usage.deque.com

.setTrackingUrl(String url)

Définir l'ID distinct

Cette méthode permet aux utilisateurs de modifier l'identifiant distinct stocké/utilisé

.setDistinctId(String distinctId)

Prochaines étapes

Une fois que vous écrivez des tests avec Axe DevTools, lisez-en plus sur utilisation des résultats pour écrire des tests personnalisés plus détaillés, ou lisez-en plus sur utilisation du rapporteur pour générer des rapports des analyses d'accessibilité.

Dépannage

Si vous rencontrez des problèmes pour configurer vos tests d'accessibilité, contactez directement votre représentant Deque, joignez-nous via notre service d'assistance, ou envoyez-nous un email. Nous sommes heureux de vous aider à lancer vos efforts de tests d'accessibilité.