Référence de l'API pour Hamcrest

Référence des types fournis par le package hamcrest.

Les classes IsAccessible et IsAuditedForAccessibility fournissent les fonctionnalités principales. Vous obtenez une instance de l'une d'elles grâce à sa méthode factory statique, isAxeClean() ou isAuditedForAccessibility(), et vous enchaînez ensuite les méthodes AxeDevtoolsMatcher pour configurer la vérification.

Les exemples de cette page supposent que webDriver est votre Selenium WebDriver, driver est un AxeDriver l'encapsulant, et qu'il y a ces imports statiques. Les classes de sélection proviennent de com.deque.html.axedevtools.matchers.selectors et AxeReportingOptions de com.deque.html.axedevtools.selenium.reporter.

import static org.hamcrest.MatcherAssert.assertThat;
import static com.deque.html.axedevtools.matchers.IsAccessible.isAxeClean;
import static com.deque.html.axedevtools.matchers.IsAuditedForAccessibility.isAuditedForAccessibility;

com.deque.html.axedevtools.matchers.AxeDevtoolsMatcher

La classe de base des matchers Axe DevTools. Elle étend le TypeSafeMatcher<AxeDriver> de Hamcrest, donc elle correspond à un AxeDriver. Vous n'en créez pas directement : utilisez IsAccessible ou IsAuditedForAccessibility, qui héritent de toutes les méthodes ci-dessous.

Chaque méthode de configuration renvoie le même matcher, de sorte que les appels peuvent être enchaînés. L'analyse elle-même s'exécute lorsque assertThat évalue le matcher. En coulisse, chaque matcher exécute une analyse AxeSelenium, donc les règles décrites là pour combiner les options s'appliquent ici aussi.

within(String...)

Limite l'analyse aux éléments correspondants aux sélecteurs CSS donnés et à leurs descendants. Chaque sélecteur ajoute une zone distincte à l'analyse, de sorte que within("#header", "#footer") teste les deux, de la même manière que si on appelait within une fois pour chacun. Cela diffère de AxeSelenium.include(Object...), où plusieurs arguments forment un seul chemin.

public AxeDevtoolsMatcher within(String... cssSelectors);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().within("#header", "#footer"));

within(Selector...)

Limite l'analyse aux zones décrites par les objets Selector. Utilisez-le avec IFrameSelector pour tester un élément à l'intérieur d'un iFrame. Chaque sélecteur ajoute une zone distincte à l'analyse.

public AxeDevtoolsMatcher within(Selector... selectors);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

// Test the form inside the #payment-frame iframe
assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));

within(Object...)

Limite l'analyse aux zones décrites par d'autres objets sélecteurs, les plus utiles étant FromFrames et FromShadowDom. Utilisez-le pour tester un élément à l'intérieur d'un arbre DOM shadow, que les objets Selector ne peuvent pas exprimer. Chaque argument ajoute une zone distincte à l'analyse.

public AxeDevtoolsMatcher within(Object... selectors);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

// Test the #search form inside the shadow root attached to .app-header
assertThat(driver, isAxeClean().within(new FromShadowDom(".app-header", "form#search")));

excluding(String...)

Supprime les éléments correspondant aux sélecteurs CSS donnés, et leurs descendants, de l'analyse. Chaque sélecteur supprime une zone distincte. Les exclusions s'appliquent en plus de tout appel within, ce qui vous permet de tester une région sauf une partie.

public AxeDevtoolsMatcher excluding(String... cssSelectors);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

// Test main, but skip the .cookie-banner and .ad-slot inside it
assertThat(driver, isAxeClean().within("main").excluding(".cookie-banner", ".ad-slot"));

excluding(Selector...)

Supprime les zones décrites par les objets Selector de l'analyse, telles qu'un élément à l'intérieur d'un iFrame. Chaque sélecteur supprime une zone distincte.

public AxeDevtoolsMatcher excluding(Selector... selectors);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

// Skip the third-party ad inside the #ad-frame iframe
assertThat(driver, isAxeClean().excluding(new IFrameSelector("#ad-frame", ".ad")));

excluding(Object...)

Supprime les zones décrites par d'autres objets sélecteurs, les plus utiles étant FromFrames et FromShadowDom, de l'analyse. Chaque argument supprime une zone distincte.

public AxeDevtoolsMatcher excluding(Object... selectors);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

// Skip the chat widget inside the shadow root attached to support-chat
assertThat(driver, isAxeClean().excluding(new FromShadowDom("support-chat", ".widget")));

accordingTo(String...)

N'exécute que les règles portant au moins l'une des balises données, telles que wcag2a ou best-practice.

accordingTo et checkingOnly définissent la même option, donc seul le dernier des deux appels prend effet. Un deuxième appel accordingTo remplace également les balises du premier, donc passez toutes les balises dans un seul appel.

public AxeDevtoolsMatcher accordingTo(String... tags);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().accordingTo("wcag2a", "wcag2aa"));

checkingOnly(String...)

N'exécute que les règles nommées et aucune autre.

checkingOnly et accordingTo définissent la même option, donc seul le dernier des deux appels prend effet. Un deuxième appel checkingOnly remplace également les règles du premier, donc passez tous les identifiants de règle dans un seul appel.

public AxeDevtoolsMatcher checkingOnly(String... rules);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().checkingOnly("label", "color-contrast"));

checking(String...)

Active les règles nommées en plus des règles déjà sélectionnées par le jeu de règles ou par accordingTo.

checking et skipping définissent la même option, donc seul le dernier des deux appels prend effet, et un deuxième appel checking remplace les règles du premier. Passez tous les identifiants de règle dans un seul appel, et ne combinez pas checking avec skipping dans la même vérification.

public AxeDevtoolsMatcher checking(String... rules);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

// WCAG 2.0 Level A rules, plus the tabindex best-practice rule
assertThat(driver, isAxeClean().accordingTo("wcag2a").checking("tabindex"));

skipping(String...)

Désactive les règles nommées, en laissant le reste du jeu de règles ou des tags sélectionnés en place.

skipping et checking définissent la même option, donc seul le dernier des deux appels prend effet, et un deuxième appel skipping remplace les règles du premier. Passez tous les identifiants de règle dans un seul appel, et ne combinez pas skipping avec checking dans la même vérification.

public AxeDevtoolsMatcher skipping(String... rules);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().skipping("color-contrast", "image-alt"));

ignoring(String, String)

Supprime les violations d'une règle des résultats lorsque cette règle échoue sur un élément donné, de sorte qu'elles ne provoquent pas l'échec de l'assertion. Le sélecteur doit correspondre exactement au target de l'élément dans les résultats, sous forme de "[#sidebar]".

Le filtrage fonctionne sur des règles entières : si un élément qui échoue à la règle correspond au sélecteur, l'entrée entière de la règle est supprimée, y compris les échecs sur d'autres éléments. Un appel par règle suffit ; deux appels pour la même règle correspondant tous deux lancent un IllegalStateException. Voir AxeSelenium.ignoring(String, String) pour plus de détails.

public AxeDevtoolsMatcher ignoring(String selector, String ruleId);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().ignoring("[#sidebar]", "color-contrast"));

forConfig(URL)

Sélectionne le suite d'audit (un fichier de configuration de règle JSON) à vérifier, par URL. Comme AxeSelenium.forConfig(URL), cela définit le suite d'audit global, donc cela s'applique aussi aux vérifications ultérieures.

public AxeDevtoolsMatcher forConfig(URL auditPath);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

URL auditSuite = getClass().getResource("/config/my-audit-suite.json");
assertThat(driver, isAxeClean().forConfig(auditSuite));

forConfig(String)

Sélectionne le suite d'audit à vérifier, par son chemin sur le système de fichiers. Comme forConfig(URL), cela définit le suite d'audit global.

public AxeDevtoolsMatcher forConfig(String auditPath) throws MalformedURLException;

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Génère

MalformedURLException si le chemin ne peut pas être converti en URL.

Exemple

@Test
public void matchesAuditSuite() throws MalformedURLException {
    assertThat(driver, isAxeClean().forConfig("/opt/axe/my-audit-suite.json"));
}

forRuleset(String)

Sélectionne le jeu de règles à vérifier, tel que wcag2.2 ou 508, avec les règles de bonnes pratiques désactivées. Passer null sélectionne le par défaut, wcag2.1. Comme AxeSelenium.forRuleset(String), cela définit le jeu de règles global, donc cela s'applique aussi aux vérifications ultérieures. Voir AxeConfiguration.forRuleset(String) pour les identifiants de jeu de règles.

Les matchers n'ont aucun moyen d'activer les règles de bonnes pratiques avec un jeu de règles. Pour ce faire, appelez AxeConfiguration.configure().forRuleset(rulesetId, true) avant la vérification, et ne pas appeler non plus le forRuleset du matcher, ce qui désactive à nouveau les règles de bonnes pratiques.

public AxeDevtoolsMatcher forRuleset(String rulesetId);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().forRuleset("wcag2.2"));

logResults(AxeReportingOptions)

Écrit un rapport de cette vérification : un fichier .log listant les violations et un fichier .json avec les résultats complets. Les noms de fichiers et l'emplacement proviennent de reportingOptions ; voir AxeReportingOptions. Avec isAxeClean(), aucun rapport n'est écrit sauf si vous appelez logResults.

Si reportingOptions n'a pas de numéro de ligne défini, Axe DevTools enregistre la ligne de votre test qui a appelé logResults.

public AxeDevtoolsMatcher logResults(AxeReportingOptions reportingOptions);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

AxeReportingOptions options = new AxeReportingOptions()
    .testSuiteName("checkout")
    .uiState("page-loaded");

assertThat(driver, isAxeClean().logResults(options));

setReportingOptions(AxeReportingOptions)

Remplace les options de rapport que isAuditedForAccessibility() utilise lorsque vous n'appelez pas logResults. Cela n'a aucun effet sur isAxeClean(), qui n'écrit un rapport que par logResults. Les options que vous passez remplacent entièrement les valeurs par défaut : toute valeur que vous ne définissez pas revient à AxeConfiguration (les rapports vont à axe-reports, sauf si vous définissez outputDirectory), et vous devez définir uiState.

public AxeDevtoolsMatcher setReportingOptions(AxeReportingOptions reportingOptions);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAuditedForAccessibility()
    .setReportingOptions(new AxeReportingOptions().testSuiteName("nightly").uiState("home")));

setTimeout(int)

Définit le temps maximum, en secondes, que axe-core peut analyser la page avant que la vérification échoue par dépassement de temps. La valeur par défaut est de 30 secondes.

public AxeDevtoolsMatcher setTimeout(int timeout);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().setTimeout(120));

enableAnalytics(boolean)

Active ou désactive le service d'utilisation pour cette vérification. Le service d'utilisation est activé par défaut. Lorsque la variable d'environnement AXE_TRACK_USAGE est définie, elle a priorité et cette méthode n'a aucun effet : true active le service et toute autre valeur le désactive.

public AxeDevtoolsMatcher enableAnalytics(boolean state);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().enableAnalytics(false));

trackingEnabled()

Indique si cette vérification envoie des données d'utilisation.

public boolean trackingEnabled();

Renvoie

true si le service d'utilisation est activé.

setAnalyticsUrl(String)

Définit l'URL à laquelle les données d'utilisation sont envoyées. La valeur par défaut est la variable d'environnement AXE_METRICS_URL, ou https://usage.deque.com lorsque celle-ci n'est pas définie. Lorsque AXE_METRICS_URL est définie, cette méthode n'a aucun effet.

public AxeDevtoolsMatcher setAnalyticsUrl(String url);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().setAnalyticsUrl("https://usage.example.com"));

setAnalyticsDisinctId(String)

Définit l'ID distinct envoyé avec les données d'utilisation. Le nom de la méthode est écrit Disinct dans l'API, donc saisissez-le exactement comme indiqué. L'ID est enregistré dans ~/.deque/distinct_id, ainsi les exécutions ultérieures sur la même machine continueront de l'utiliser. Lorsque l'ID provient de la variable d'environnement AXE_DISTINCT_ID, cette méthode n'a aucun effet.

public AxeDevtoolsMatcher setAnalyticsDisinctId(String id);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean().setAnalyticsDisinctId("build-agent-7"));

setAnalyticsComponentName(String)

Définit le nom du projet envoyé avec les données d'utilisation. Cela réinitialise également tous les appels précédents de setAnalyticsUrl et enableAnalytics sur ce comparateur à leurs valeurs par défaut, donc appelez-le avant ces méthodes. Un ID distinct défini avec setAnalyticsDisinctId est conservé.

public AxeDevtoolsMatcher setAnalyticsComponentName(String name);

Paramètres

Renvoie

Ce matcher, pour l'enchaînement de méthodes.

Exemple

assertThat(driver, isAxeClean()
    .setAnalyticsComponentName("storefront-tests")
    .setAnalyticsDisinctId("build-agent-7"));

com.deque.html.axedevtools.matchers.IsAccessible

Un comparateur qui échoue lorsque la page présente des violations d'accessibilité. Il étend AxeDevtoolsMatcher, donc chaque méthode ci-dessus peut lui être enchaînée pour définir la portée, les règles, la suite d'audit et le rendu de rapports.

Lorsque la vérification échoue, le message d'erreur liste chaque violation, les éléments affectés, et comment les corriger, dans le même format que le rapport .log. Si axe-core renvoie une erreur au lieu de résultats, la vérification produit une AxeRuntimeException au lieu d'un échec.

assertThat(driver, isAxeClean()
    .within("#header")
    .within("#footer")
    .excluding(".graphics")
    .accordingTo("wcag2a", "wcag2aa"));

isAxeClean()

Crée un comparateur IsAccessible. Cette méthode statique est le seul moyen d'en obtenir un. Sans configuration supplémentaire, il vérifie la page entière par rapport à l'ensemble de règles global, qui par défaut est wcag2.1, et ne génère aucun rapport.

public static IsAccessible isAxeClean();

Renvoie

Un nouveau comparateur IsAccessible.

Exemple

@Test
public void homePageIsAccessible() {
    webDriver.get("https://example.com");
    assertThat(driver, isAxeClean());
}

com.deque.html.axedevtools.matchers.IsAuditedForAccessibility

Un comparateur qui examine la page et rédige un rapport, mais n'échoue jamais à cause de violations. Une erreur axe-core génère toujours une AxeRuntimeException, comme avec isAxeClean(). Utilisez-le pour collecter des résultats pour le suivi sans interrompre la construction ; vous aurez besoin de suivre les régressions à partir des rapports, en dehors des tests réussis et échoués. Il étend AxeDevtoolsMatcher, donc chaque méthode ci-dessus peut lui être enchaînée.

À moins que vous n'appeliez logResults, le rapport est écrit dans target/axe-report/accessibility-check.log et target/axe-report/accessibility-check.json. Utilisez setReportingOptions pour modifier ces valeurs par défaut. Chaque vérification écrase le rapport précédent au même chemin, alors donnez à chaque vérification son propre nom de suite de tests ou état de l'interface utilisateur via setReportingOptions ou logResults, ou activez useUniqueFilename.

assertThat(driver, isAuditedForAccessibility()
    .within("#header")
    .within("#footer")
    .excluding(".graphics")
    .accordingTo("wcag2a", "wcag2aa"));

isAuditedForAccessibility()

Crée un comparateur IsAuditedForAccessibility. Cette méthode statique est le seul moyen d'en obtenir un.

public static IsAuditedForAccessibility isAuditedForAccessibility();

Renvoie

Un nouveau comparateur IsAuditedForAccessibility.

Exemple

@Test
public void auditCheckoutPage() {
    webDriver.get("https://example.com/checkout");
    assertThat(driver, isAuditedForAccessibility()
        .logResults(new AxeReportingOptions().testSuiteName("checkout").uiState("loaded")));
}

com.deque.html.axedevtools.matchers.selectors.Selector

L'interface implémentée par ElementSelector et IFrameSelector. Passez des sélecteurs à within(Selector...) ou excluding(Selector...).

toList()

Renvoie le sélecteur sous forme de liste de sélecteurs CSS : un par niveau iFrame, suivi du sélecteur pour l'élément. Les deux implémentations le fournissent. Les comparateurs l'appellent pour vous ; vous n'avez pas besoin de l'appeler dans les tests.

List<String> toList();

Renvoie

Les sélecteurs CSS, sous forme de List\<String>.

com.deque.html.axedevtools.matchers.selectors.ElementSelector

Un Selector pour un élément dans le document actuel. À lui seul, il est équivalent à passer la chaîne de sélecteur CSS à within ou excluding ; son principal usage est comme la partie la plus interne d'un IFrameSelector.

ElementSelector(String)

Crée un sélecteur pour les éléments correspondants à un sélecteur CSS.

public ElementSelector(String cssSelector);

Paramètres

Exemple

// The form inside #inner-frame, which is inside #outer-frame
Selector form = new IFrameSelector("#outer-frame",
    new IFrameSelector("#inner-frame", new ElementSelector("form")));

com.deque.html.axedevtools.matchers.selectors.IFrameSelector

Un Selector pour un élément dans un iFrame. Enchâssez un IFrameSelector dans un autre pour atteindre un élément dans des iFrames imbriqués.

IFrameSelector(String, String)

Crée un sélecteur pour un élément dans un iFrame.

public IFrameSelector(String frameSelector, String cssSelector);

Paramètres

Exemple

assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));

IFrameSelector(String, Selector)

Crée un sélecteur pour un élément dans un iFrame, où l'élément est décrit par un autre Selector. Passez un autre IFrameSelector pour aller un iFrame plus loin, ou un ElementSelector.

public IFrameSelector(String frameSelector, Selector selector);

Paramètres

Exemple

// The form inside #inner-frame, which is inside #outer-frame
assertThat(driver, isAxeClean().within(
    new IFrameSelector("#outer-frame", new IFrameSelector("#inner-frame", "form"))));