Referência de API para Hamcrest
Referência de API para os tipos de correspondentes Hamcrest do Axe DevTools para Java Web
Referência para os tipos fornecidos pelo pacote hamcrest.
As classes IsAccessible e IsAuditedForAccessibility fornecem a funcionalidade principal. Você obtém uma instância de qualquer uma delas a partir de seu método de fábrica estático, isAxeClean() ou isAuditedForAccessibility(), e então encadeia os métodos AxeDevtoolsMatcher para configurar a verificação.
Os exemplos nesta página assumem que webDriver é seu WebDriver do Selenium, driver é um AxeDriver envolvendo-o, e essas importações estáticas. As classes de seletores vêm de com.deque.html.axedevtools.matchers.selectors, e 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
A classe base dos matchers do Axe DevTools. Ela estende o TypeSafeMatcher<AxeDriver> do Hamcrest, portanto, combina com um AxeDriver. Você não cria um diretamente: use IsAccessible ou IsAuditedForAccessibility, que herdam todos os métodos abaixo.
Cada método de configuração retorna o mesmo matcher, permitindo que as chamadas sejam encadeadas. A varredura em si é executada quando assertThat avalia o matcher. Por trás dos bastidores, cada matcher executa uma varredura AxeSelenium, portanto, as regras descritas lá para combinar opções também se aplicam aqui.
within(String...)
Limita a varredura aos elementos que correspondem aos seletores CSS fornecidos, e seus descendentes. Cada seletor adiciona uma área separada à varredura, assim within("#header", "#footer") testa ambos, da mesma forma que chamar within uma vez para cada. Isso difere de AxeSelenium.include(Object...), onde vários argumentos formam um único caminho.
public AxeDevtoolsMatcher within(String... cssSelectors);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
cssSelectors |
String... |
Um ou mais seletores CSS, cada um no documento de nível superior. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().within("#header", "#footer"));within(Selector...)
Limita a varredura às áreas descritas por objetos Selector. Use-o com IFrameSelector para testar um elemento dentro de um iFrame. Cada seletor adiciona uma área separada à varredura.
public AxeDevtoolsMatcher within(Selector... selectors);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
selectors |
Selector... |
Um ou mais objetos ElementSelector ou IFrameSelector. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
// Test the form inside the #payment-frame iframe
assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));within(Object...)
Limita a varredura às áreas descritas por outros objetos de seletores, sendo os mais utilizados FromFrames e FromShadowDom. Use-o para testar um elemento dentro de uma árvore de shadow DOM, que objetos Selector não conseguem expressar. Cada argumento adiciona uma área separada à varredura.
public AxeDevtoolsMatcher within(Object... selectors);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
selectors |
Object... |
Um ou mais seletores, cada um dos quais é uma string de seletor CSS, uma lista de strings, um seletor FromFrames ou um seletor FromShadowDom. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
// Test the #search form inside the shadow root attached to .app-header
assertThat(driver, isAxeClean().within(new FromShadowDom(".app-header", "form#search")));excluding(String...)
Remove os elementos que correspondem aos seletores CSS fornecidos, e seus descendentes, da varredura. Cada seletor remove uma área separada. As exclusões se aplicam além de quaisquer chamadas within, o que permite testar uma região, exceto por parte dela.
public AxeDevtoolsMatcher excluding(String... cssSelectors);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
cssSelectors |
String... |
Um ou mais seletores CSS, cada um no documento de nível superior. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
// Test main, but skip the .cookie-banner and .ad-slot inside it
assertThat(driver, isAxeClean().within("main").excluding(".cookie-banner", ".ad-slot"));excluding(Selector...)
Remove as áreas descritas por objetos Selector da varredura, como um elemento dentro de um iFrame. Cada seletor remove uma área separada.
public AxeDevtoolsMatcher excluding(Selector... selectors);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
selectors |
Selector... |
Um ou mais objetos ElementSelector ou IFrameSelector. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
// Skip the third-party ad inside the #ad-frame iframe
assertThat(driver, isAxeClean().excluding(new IFrameSelector("#ad-frame", ".ad")));excluding(Object...)
Remove áreas descritas por outros objetos de seletores, sendo os mais utilizados FromFrames e FromShadowDom, da varredura. Cada argumento remove uma área separada.
public AxeDevtoolsMatcher excluding(Object... selectors);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
selectors |
Object... |
Um ou mais seletores, cada um dos quais é uma string de seletor CSS, uma lista de strings, um seletor FromFrames ou um seletor FromShadowDom. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
// Skip the chat widget inside the shadow root attached to support-chat
assertThat(driver, isAxeClean().excluding(new FromShadowDom("support-chat", ".widget")));accordingTo(String...)
Executa apenas as regras que possuem pelo menos uma das tags fornecidas, como wcag2a ou best-practice.
accordingTo e checkingOnly definem a mesma opção, portanto, apenas a última das duas chamadas tem efeito. Uma segunda chamada accordingTo também substitui as tags da primeira, por isso passe todas as tags em uma única chamada.
public AxeDevtoolsMatcher accordingTo(String... tags);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
tags |
String... |
Um ou mais tags do axe-core. Veja Descrições de regras para as tags em cada regra. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().accordingTo("wcag2a", "wcag2aa"));checkingOnly(String...)
Executa apenas as regras nomeadas e nenhuma outra.
checkingOnly e accordingTo definem a mesma opção, portanto, apenas a última das duas chamadas tem efeito. Uma segunda chamada checkingOnly também substitui as regras da primeira, por isso passe todos os IDs de regras em uma única chamada.
public AxeDevtoolsMatcher checkingOnly(String... rules);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
rules |
String... |
Um ou mais IDs de regras do axe-core. Veja Descrições de regras. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().checkingOnly("label", "color-contrast"));checking(String...)
Ativa as regras nomeadas além das regras já selecionadas pelo conjunto de regras ou por accordingTo.
checking e skipping definem a mesma opção, portanto, apenas a última das duas chamadas tem efeito, e uma segunda chamada checking substitui as regras da primeira. Passe todos os IDs de regras em uma única chamada, e não combine checking com skipping na mesma verificação.
public AxeDevtoolsMatcher checking(String... rules);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
rules |
String... |
Um ou mais IDs de regras do axe-core. Veja Descrições de regras. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
// WCAG 2.0 Level A rules, plus the tabindex best-practice rule
assertThat(driver, isAxeClean().accordingTo("wcag2a").checking("tabindex"));skipping(String...)
Desativa as regras nomeadas, mantendo o restante do conjunto de regras ou tags selecionados.
skipping e checking definem a mesma opção, portanto, apenas a última das duas chamadas tem efeito, e uma segunda chamada skipping substitui as regras da primeira. Passe todos os IDs de regras em uma única chamada, e não combine skipping com checking na mesma verificação.
public AxeDevtoolsMatcher skipping(String... rules);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
rules |
String... |
Um ou mais IDs de regras do axe-core. Veja Descrições de regras. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().skipping("color-contrast", "image-alt"));ignoring(String, String)
Remove as violações de uma regra dos resultados quando essa regra falha em um determinado elemento, para que não falhem na asserção. O seletor deve corresponder exatamente ao target do elemento nos resultados, no formato "[#sidebar]".
A filtragem funciona em regras inteiras: se qualquer elemento que falha na regra corresponder ao seletor, a entrada inteira da regra é removida, incluindo falhas em outros elementos. Uma chamada por regra é suficiente; duas chamadas para a mesma regra que ambas correspondam lançam um IllegalStateException. Veja AxeSelenium.ignoring(String, String) para detalhes.
public AxeDevtoolsMatcher ignoring(String selector, String ruleId);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
selector |
String |
O target do elemento, como aparece nos resultados. |
ruleId |
String |
O ID da regra cuja violação ignorar. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().ignoring("[#sidebar]", "color-contrast"));forConfig(URL)
Seleciona o conjunto de auditoria (um arquivo de configuração de regras em JSON) para verificar por URL. Como AxeSelenium.forConfig(URL), isso define o conjunto de auditoria global, portanto, também se aplica a verificações posteriores.
public AxeDevtoolsMatcher forConfig(URL auditPath);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
auditPath |
URL |
A URL do arquivo do conjunto de auditoria. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
URL auditSuite = getClass().getResource("/config/my-audit-suite.json");
assertThat(driver, isAxeClean().forConfig(auditSuite));forConfig(String)
Seleciona o conjunto de auditoria para verificar, pelo seu caminho no sistema de arquivos. Como forConfig(URL), isso define o conjunto de auditoria global.
public AxeDevtoolsMatcher forConfig(String auditPath) throws MalformedURLException;Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
auditPath |
String |
O caminho do arquivo do conjunto de auditoria no sistema de arquivos. |
Retorna
Este matcher, para encadeamento de métodos.
Lança
MalformedURLException se o caminho não puder ser convertido para uma URL.
Exemplo
@Test
public void matchesAuditSuite() throws MalformedURLException {
assertThat(driver, isAxeClean().forConfig("/opt/axe/my-audit-suite.json"));
}forRuleset(String)
Seleciona o conjunto de regras para verificar, como wcag2.2 ou 508, com as regras de melhores práticas desativadas. Passar null seleciona o padrão, wcag2.1. Como AxeSelenium.forRuleset(String), isso define o conjunto de regras global, portanto, também se aplica a verificações posteriores. Veja AxeConfiguration.forRuleset(String) para os IDs do conjunto de regras.
Os matchers não têm como ativar as regras de melhores práticas junto com um conjunto de regras. Para fazer isso, chame AxeConfiguration.configure().forRuleset(rulesetId, true) antes da verificação, e não chame também o forRuleset do matcher, que desativa as regras de melhores práticas novamente.
public AxeDevtoolsMatcher forRuleset(String rulesetId);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
rulesetId |
String |
O ID do conjunto de regras. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().forRuleset("wcag2.2"));logResults(AxeReportingOptions)
Escreve um relatório desta verificação: um arquivo .log listando as violações e um arquivo .json com os resultados completos. Os nomes dos arquivos e a localização vêm de reportingOptions; veja AxeReportingOptions. Com isAxeClean(), nenhum relatório é escrito a menos que você chame logResults.
Se reportingOptions não tiver nenhum número de linha definido, o Axe DevTools grava a linha do seu teste que chamou logResults.
public AxeDevtoolsMatcher logResults(AxeReportingOptions reportingOptions);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
reportingOptions |
AxeReportingOptions |
Onde gravar o relatório e como descrever o teste nele. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
AxeReportingOptions options = new AxeReportingOptions()
.testSuiteName("checkout")
.uiState("page-loaded");
assertThat(driver, isAxeClean().logResults(options));setReportingOptions(AxeReportingOptions)
Substitui as opções de relatório que isAuditedForAccessibility() usa quando você não chama logResults. Não tem efeito em isAxeClean(), que só grava um relatório por meio de logResults. As opções que você passa substituem completamente os padrões: qualquer valor que você não definir recai em AxeConfiguration (os relatórios vão para axe-reports a menos que você defina outputDirectory), e você deve definir uiState.
public AxeDevtoolsMatcher setReportingOptions(AxeReportingOptions reportingOptions);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
reportingOptions |
AxeReportingOptions |
As opções de relatório a serem usadas. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAuditedForAccessibility()
.setReportingOptions(new AxeReportingOptions().testSuiteName("nightly").uiState("home")));setTimeout(int)
Define quanto tempo, em segundos, o axe-core pode analisar a página antes que a verificação falhe por timeout. O padrão é 30 segundos.
public AxeDevtoolsMatcher setTimeout(int timeout);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
timeout |
int |
O tempo limite, em segundos. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().setTimeout(120));enableAnalytics(boolean)
Ativa ou desativa o serviço de uso para esta verificação. O serviço de uso está ativado por padrão. Quando a variável de ambiente AXE_TRACK_USAGE é definida, ela tem precedência e este método não tem efeito: true ativa o serviço e qualquer outro valor o desativa.
public AxeDevtoolsMatcher enableAnalytics(boolean state);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
state |
boolean |
true para enviar dados de uso, false para parar de enviá-los. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().enableAnalytics(false));trackingEnabled()
Informa se esta verificação envia dados de uso.
public boolean trackingEnabled();Retorna
true se o serviço de uso estiver ativado.
setAnalyticsUrl(String)
Define a URL para a qual os dados de uso são enviados. O padrão é a variável de ambiente AXE_METRICS_URL, ou https://usage.deque.com quando não está definida. Quando AXE_METRICS_URL é definida, este método não tem efeito.
public AxeDevtoolsMatcher setAnalyticsUrl(String url);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
url |
String |
A URL do serviço de uso. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().setAnalyticsUrl("https://usage.example.com"));setAnalyticsDisinctId(String)
Define o ID distinto enviado com os dados de uso. O nome do método é escrito como Disinct na API, então digite-o exatamente como mostrado. O ID é salvo em ~/.deque/distinct_id, assim execuções posteriores na mesma máquina continuam a usá-lo. Quando o ID vem da variável de ambiente AXE_DISTINCT_ID, este método não tem efeito.
public AxeDevtoolsMatcher setAnalyticsDisinctId(String id);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
id |
String |
O ID distinto. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean().setAnalyticsDisinctId("build-agent-7"));setAnalyticsComponentName(String)
Define o nome do projeto enviado com os dados de uso. Isso também redefine quaisquer chamadas anteriores de setAnalyticsUrl e enableAnalytics neste analisador para seus padrões, então chame-o antes desses métodos. Um ID distinto definido com setAnalyticsDisinctId é mantido.
public AxeDevtoolsMatcher setAnalyticsComponentName(String name);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
name |
String |
O nome do projeto. |
Retorna
Este matcher, para encadeamento de métodos.
Exemplo
assertThat(driver, isAxeClean()
.setAnalyticsComponentName("storefront-tests")
.setAnalyticsDisinctId("build-agent-7"));com.deque.html.axedevtools.matchers.IsAccessible
Um analisador que falha na asserção quando a página tem violações de acessibilidade. Ele estende AxeDevtoolsMatcher, portanto, todos os métodos acima podem ser encadeados para definir o escopo, regras, suíte de auditoria e relatórios.
Quando a asserção falha, a mensagem de falha lista cada violação, os elementos afetados e como corrigi-los, no mesmo formato do relatório .log. Se axe-core retornar um erro em vez de resultados, a verificação lança um AxeRuntimeException em vez de falhar a asserção.
assertThat(driver, isAxeClean()
.within("#header")
.within("#footer")
.excluding(".graphics")
.accordingTo("wcag2a", "wcag2aa"));isAxeClean()
Cria um analisador IsAccessible. Este método estático é a única maneira de obter um. Sem mais configurações, ele verifica a página inteira com o conjunto de regras global, que por padrão é wcag2.1, e não escreve nenhum relatório.
public static IsAccessible isAxeClean();Retorna
Um novo analisador IsAccessible.
Exemplo
@Test
public void homePageIsAccessible() {
webDriver.get("https://example.com");
assertThat(driver, isAxeClean());
}com.deque.html.axedevtools.matchers.IsAuditedForAccessibility
Um analisador que escaneia a página e escreve um relatório, mas nunca falha na asserção por causa de violações. Um erro do axe-core ainda lança um AxeRuntimeException, como com isAxeClean(). Use-o para coletar resultados para monitoramento sem interromper a construção; será necessário rastrear regressões a partir dos relatórios, fora das aprovações e falhas dos testes. Ele estende AxeDevtoolsMatcher, portanto, todos os métodos acima podem ser encadeados nele.
A menos que você chame logResults, o relatório é escrito para target/axe-report/accessibility-check.log e target/axe-report/accessibility-check.json. Use setReportingOptions para mudar esses padrões. Cada verificação substitui o relatório anterior no mesmo caminho, portanto, dê a cada verificação seu próprio nome de suíte de teste ou estado de UI por meio de setReportingOptions ou logResults, ou ative useUniqueFilename.
assertThat(driver, isAuditedForAccessibility()
.within("#header")
.within("#footer")
.excluding(".graphics")
.accordingTo("wcag2a", "wcag2aa"));isAuditedForAccessibility()
Cria um analisador IsAuditedForAccessibility. Este método estático é a única maneira de obter um.
public static IsAuditedForAccessibility isAuditedForAccessibility();Retorna
Um novo analisador IsAuditedForAccessibility.
Exemplo
@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
A interface implementada por ElementSelector e IFrameSelector. Passe seletores para within(Selector...) ou excluding(Selector...).
toList()
Retorna o seletor como uma lista de seletores CSS: um por nível de iFrame, seguido do seletor para o elemento. Ambas as implementações o fornecem. Os analisadores o chamam para você; você não precisa chamá-lo nos testes.
List<String> toList();Retorna
Os seletores CSS, como um List\<String>.
com.deque.html.axedevtools.matchers.selectors.ElementSelector
Um Selector para um elemento no documento atual. Por si só, é equivalente a passar a string do seletor CSS para within ou excluding; seu principal uso é como parte mais interna de um IFrameSelector.
ElementSelector(String)
Cria um seletor para os elementos correspondentes a um seletor CSS.
public ElementSelector(String cssSelector);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
cssSelector |
String |
Um seletor CSS. |
Exemplo
// 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
Um Selector para um elemento dentro de um iFrame. Aninhe um IFrameSelector dentro de outro para alcançar um elemento dentro de iFrames aninhados.
IFrameSelector(String, String)
Cria um seletor para um elemento dentro de um iFrame.
public IFrameSelector(String frameSelector, String cssSelector);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
frameSelector |
String |
Um seletor CSS para o elemento iFrame na página. |
cssSelector |
String |
Um seletor CSS para o elemento a ser testado dentro do iFrame. |
Exemplo
assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));IFrameSelector(String, Selector)
Cria um seletor para um elemento dentro de um iFrame, onde o elemento é descrito por outro Selector. Passe outro IFrameSelector para ir um iFrame mais profundo ou um ElementSelector.
public IFrameSelector(String frameSelector, Selector selector);Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
frameSelector |
String |
Um seletor CSS para o elemento iFrame na página. |
selector |
Selector |
Um IFrameSelector para um iFrame aninhado ou um ElementSelector para o elemento a ser testado. |
Exemplo
// The form inside #inner-frame, which is inside #outer-frame
assertThat(driver, isAxeClean().within(
new IFrameSelector("#outer-frame", new IFrameSelector("#inner-frame", "form"))));