Riferimento API per Hamcrest

Riferimento per i tipi forniti dal pacchetto hamcrest.

Le classi IsAccessible e IsAuditedForAccessibility forniscono la funzionalità principale. Si ottiene un'istanza di entrambe tramite il metodo di fabbrica statico, isAxeClean() o isAuditedForAccessibility(), e poi si concatenano i metodi AxeDevtoolsMatcher per configurare il controllo.

Gli esempi in questa pagina presumono che webDriver sia il vostro Selenium WebDriver, che driver sia un AxeDriver che lo racchiude, e questi import statici. Le classi selettori provengono da com.deque.html.axedevtools.matchers.selectors e AxeReportingOptions da 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 base dei matcher di Axe DevTools. Estende il TypeSafeMatcher<AxeDriver> di Hamcrest, quindi corrisponde a un AxeDriver. Non ne create uno direttamente: usate IsAccessible o IsAuditedForAccessibility, che ereditano tutti i metodi sottostanti.

Ogni metodo di configurazione restituisce lo stesso matcher, quindi le chiamate possono essere concatenate. La scansione viene eseguita quando assertThat valuta il matcher. Dietro le quinte, ogni matcher esegue una scansione AxeSelenium, quindi le regole descritte per combinare le opzioni si applicano anche qui.

within(String...)

Limita la scansione agli elementi corrispondenti ai selettori CSS forniti e ai loro discendenti. Ogni selettore aggiunge una zona separata alla scansione, quindi within("#header", "#footer") testa entrambi, come chiamare within una volta per ciascuno. Questo differisce da AxeSelenium.include(Object...), dove diversi argomenti formano un unico percorso.

public AxeDevtoolsMatcher within(String... cssSelectors);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

within(Selector...)

Limita la scansione alle aree descritte dagli oggetti Selector. Usatelo con IFrameSelector per testare un elemento all'interno di un iFrame. Ogni selettore aggiunge un'area separata alla scansione.

public AxeDevtoolsMatcher within(Selector... selectors);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

within(Object...)

Limita la scansione alle aree descritte da altri oggetti selettori, più utilmente FromFrames e FromShadowDom. Usatelo per testare un elemento all'interno di un albero DOM shadow, che gli oggetti Selector non possono esprimere. Ogni argomento aggiunge un'area separata alla scansione.

public AxeDevtoolsMatcher within(Object... selectors);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

excluding(String...)

Rimuove gli elementi corrispondenti ai selettori CSS forniti e ai loro discendenti dalla scansione. Ogni selettore rimuove un'area separata. Le esclusioni si applicano in aggiunta a eventuali chiamate within, il che permette di testare una regione tranne una parte di essa.

public AxeDevtoolsMatcher excluding(String... cssSelectors);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

excluding(Selector...)

Rimuove le aree descritte dagli oggetti Selector dalla scansione, come un elemento all'interno di un iFrame. Ogni selettore rimuove un'area separata.

public AxeDevtoolsMatcher excluding(Selector... selectors);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

excluding(Object...)

Rimuove le aree descritte da altri oggetti selettori, più utilmente FromFrames e FromShadowDom, dalla scansione. Ogni argomento rimuove un'area separata.

public AxeDevtoolsMatcher excluding(Object... selectors);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

accordingTo(String...)

Esegue solo le regole che portano almeno uno dei tag forniti, come wcag2a o best-practice.

accordingTo e checkingOnly impostano la stessa opzione, quindi solo l'ultima delle due chiamate ha effetto. Una seconda chiamata a accordingTo sostituisce anche i tag dalla prima, quindi passate tutti i tag in una chiamata.

public AxeDevtoolsMatcher accordingTo(String... tags);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

checkingOnly(String...)

Esegue solo le regole nominate e nessun'altra.

checkingOnly e accordingTo impostano la stessa opzione, quindi solo l'ultima delle due chiamate ha effetto. Una seconda chiamata a checkingOnly sostituisce anche le regole dalla prima, quindi passate tutti gli ID delle regole in una chiamata.

public AxeDevtoolsMatcher checkingOnly(String... rules);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

checking(String...)

Attiva le regole nominate in aggiunta alle regole già selezionate dal set di regole o da accordingTo.

checking e skipping impostano la stessa opzione, quindi solo l'ultima delle due chiamate ha effetto, e una seconda chiamata a checking sostituisce le regole dalla prima. Passate tutti gli ID delle regole in una chiamata e non combinate checking con skipping nello stesso controllo.

public AxeDevtoolsMatcher checking(String... rules);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

skipping(String...)

Disattiva le regole nominate, lasciando inalterati il resto del set di regole selezionato o i tag.

skipping e checking impostano la stessa opzione, quindi solo l'ultima delle due chiamate ha effetto, e una seconda chiamata a skipping sostituisce le regole dalla prima. Passate tutti gli ID delle regole in una chiamata e non combinate skipping con checking nello stesso controllo.

public AxeDevtoolsMatcher skipping(String... rules);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

ignoring(String, String)

Rimuove le violazioni di una regola dai risultati quando quella regola fallisce su un dato elemento, in modo che non falliscano l'assertion. Il selettore deve corrispondere esattamente alla target dell'elemento nei risultati, nella forma "[#sidebar]".

Il filtraggio funziona su intere regole: se un elemento che fallisce la regola corrisponde al selettore, l'intera voce della regola viene rimossa, inclusi i fallimenti su altri elementi. Una chiamata per regola è sufficiente; due chiamate per la stessa regola che corrispondono entrambe generano un IllegalStateException. Vedi AxeSelenium.ignoring(String, String) per i dettagli.

public AxeDevtoolsMatcher ignoring(String selector, String ruleId);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

forConfig(URL)

Seleziona la suite di audit (un file di configurazione delle regole JSON) con cui controllare, tramite URL. Come AxeSelenium.forConfig(URL), imposta la suite di audit globale, quindi si applica anche ai controlli successivi.

public AxeDevtoolsMatcher forConfig(URL auditPath);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

forConfig(String)

Seleziona la suite di audit con cui controllare, tramite il suo percorso sul file system. Come forConfig(URL), imposta la suite di audit globale.

public AxeDevtoolsMatcher forConfig(String auditPath) throws MalformedURLException;

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Genera

MalformedURLException se il percorso non può essere convertito in un URL.

Esempio

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

forRuleset(String)

Seleziona il set di regole con cui controllare, come wcag2.2 o 508, con le regole di best practice disattivate. Passando null si seleziona il predefinito, wcag2.1. Come AxeSelenium.forRuleset(String), imposta globalmente il set di regole, quindi si applica anche ai controlli successivi. Vedi AxeConfiguration.forRuleset(String) per gli ID dei set di regole.

I matcher non hanno modo di attivare le regole di best practice insieme a un set di regole. Per farlo, chiamate AxeConfiguration.configure().forRuleset(rulesetId, true) prima del controllo, e non chiamate anche forRuleset del matcher, che disattiva le regole di best practice.

public AxeDevtoolsMatcher forRuleset(String rulesetId);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

logResults(AxeReportingOptions)

Scrive un report di questo controllo: un file .log che elenca le violazioni e un file .json con i risultati completi. I nomi e la posizione dei file vengono da reportingOptions; vedi AxeReportingOptions. Con isAxeClean(), nessun report viene scritto a meno che non si chiami logResults.

Se reportingOptions non ha impostato il numero di linea, Axe DevTools registra la linea del vostro test che ha chiamato logResults.

public AxeDevtoolsMatcher logResults(AxeReportingOptions reportingOptions);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

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

setReportingOptions(AxeReportingOptions)

Sostituisce le opzioni di reporting che isAuditedForAccessibility() usa quando non si chiama logResults. Non ha effetto su isAxeClean(), che scrive un report solo tramite logResults. Le opzioni che passate sostituiscono completamente i valori predefiniti: qualsiasi valore che non impostate ricorre a AxeConfiguration (i report vanno a axe-reports a meno che non impostiate outputDirectory), e dovete impostare uiState.

public AxeDevtoolsMatcher setReportingOptions(AxeReportingOptions reportingOptions);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

setTimeout(int)

Imposta quanto tempo, in secondi, axe-core può analizzare la pagina prima che il controllo fallisca per timeout. Il valore predefinito è di 30 secondi.

public AxeDevtoolsMatcher setTimeout(int timeout);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

enableAnalytics(boolean)

Attiva o disattiva servizio di utilizzo per questo controllo. Il servizio di utilizzo è attivo per impostazione predefinita. Quando la variabile d'ambiente AXE_TRACK_USAGE è impostata, ha la precedenza e questo metodo non ha effetto: true accende il servizio e qualsiasi altro valore lo spegne.

public AxeDevtoolsMatcher enableAnalytics(boolean state);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

trackingEnabled()

Indica se questo controllo invia i dati di utilizzo.

public boolean trackingEnabled();

Restituisce

true se il servizio di utilizzo è attivo.

setAnalyticsUrl(String)

Imposta l'URL a cui vengono inviati i dati di utilizzo. L'impostazione predefinita è la variabile d'ambiente AXE_METRICS_URL, o https://usage.deque.com quando questa non è impostata. Quando AXE_METRICS_URL è impostata, questo metodo non ha effetto.

public AxeDevtoolsMatcher setAnalyticsUrl(String url);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

setAnalyticsDisinctId(String)

Imposta l'ID distinto inviato con i dati di utilizzo. Il nome del metodo è scritto Disinct nell'API, quindi digitarlo esattamente come mostrato. L'ID viene salvato su ~/.deque/distinct_id, quindi le esecuzioni successive sulla stessa macchina continueranno a utilizzarlo. Quando l'ID proviene dalla variabile d'ambiente AXE_DISTINCT_ID, questo metodo non ha effetto.

public AxeDevtoolsMatcher setAnalyticsDisinctId(String id);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

setAnalyticsComponentName(String)

Imposta il nome del progetto inviato con i dati di utilizzo. Ciò reimposta anche tutte le precedenti chiamate setAnalyticsUrl e enableAnalytics su questo matcher ai valori predefiniti, quindi chiamalo prima di quei metodi. Un ID distinto impostato con setAnalyticsDisinctId viene mantenuto.

public AxeDevtoolsMatcher setAnalyticsComponentName(String name);

Parametri

Restituisce

Questo matcher per concatenamento dei metodi.

Esempio

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

com.deque.html.axedevtools.matchers.IsAccessible

Un matcher che fallisce l'asserzione quando la pagina ha violazioni di accessibilità. Estende AxeDevtoolsMatcher, quindi ogni metodo sopra può essere concatenato su di esso per impostare l'ambito, le regole, la suite di audit e la reportistica.

Quando l'asserzione fallisce, il messaggio di errore elenca ogni violazione, gli elementi interessati e come risolverli, nello stesso formato del rapporto .log. Se axe-core restituisce un errore invece di risultati, il controllo lancia un AxeRuntimeException anziché fallire l'asserzione.

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

isAxeClean()

Crea un matcher IsAccessible. Questo metodo statico è l'unico modo per ottenerne uno. Senza ulteriori configurazioni, controlla l'intera pagina rispetto al set di regole globale, che predefinisce wcag2.1, e non scrive alcun rapporto.

public static IsAccessible isAxeClean();

Restituisce

Un nuovo matcher IsAccessible.

Esempio

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

com.deque.html.axedevtools.matchers.IsAuditedForAccessibility

Un matcher che scansiona la pagina e scrive un rapporto, ma non fallisce mai l'asserzione a causa di violazioni. Un errore di axe-core lancia comunque un AxeRuntimeException, come con isAxeClean(). Utilizzalo per raccogliere risultati per il monitoraggio senza interrompere la build; dovrai monitorare le regressioni dai rapporti, all'esterno dei passaggi e dei fallimenti dei test. Estende AxeDevtoolsMatcher, quindi ogni metodo sopra può essere concatenato su di esso.

A meno che tu non chiami logResults, il rapporto è scritto su target/axe-report/accessibility-check.log e target/axe-report/accessibility-check.json. Usa setReportingOptions per cambiare quei valori predefiniti. Ogni controllo sovrascrive il rapporto precedente allo stesso percorso, quindi dai a ogni controllo il proprio nome di suite di test o stato dell'interfaccia utente tramite setReportingOptions o logResults, o attiva useUniqueFilename.

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

isAuditedForAccessibility()

Crea un matcher IsAuditedForAccessibility. Questo metodo statico è l'unico modo per ottenerne uno.

public static IsAuditedForAccessibility isAuditedForAccessibility();

Restituisce

Un nuovo matcher IsAuditedForAccessibility.

Esempio

@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'interfaccia implementata da ElementSelector e IFrameSelector. Passa i selettori a within(Selector...) o excluding(Selector...).

toList()

Restituisce il selettore come un elenco di selettori CSS: uno per livello di iFrame, seguito dal selettore per l'elemento. Entrambe le implementazioni lo forniscono. I matchers lo chiamano per te; non hai bisogno di chiamarlo nei test.

List<String> toList();

Restituisce

I selettori CSS, come un List\<String>.

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

Un Selector per un elemento nel documento corrente. Da solo è equivalente a passare la stringa del selettore CSS a within o excluding; il suo uso principale è come parte più interna di un IFrameSelector.

ElementSelector(String)

Crea un selettore per gli elementi corrispondenti a un selettore CSS.

public ElementSelector(String cssSelector);

Parametri

Esempio

// 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 per un elemento all'interno di un iFrame. Nidifica un IFrameSelector all'interno di un altro per raggiungere un elemento all'interno di iFrames annidati.

IFrameSelector(String, String)

Crea un selettore per un elemento all'interno di un iFrame.

public IFrameSelector(String frameSelector, String cssSelector);

Parametri

Esempio

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

IFrameSelector(String, Selector)

Crea un selettore per un elemento all'interno di un iFrame, dove l'elemento è descritto da un altro Selector. Passa un altro IFrameSelector per andare un iFrame più in profondità, o un ElementSelector.

public IFrameSelector(String frameSelector, Selector selector);

Parametri

Esempio

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