Referencia de API para Hamcrest

Referencia para los tipos proporcionados por el paquete hamcrest.

Las clases IsAccessible y IsAuditedForAccessibility proporcionan la funcionalidad principal. Obtienes una instancia de cualquiera de ellas a través de su método de fábrica estático, isAxeClean() o isAuditedForAccessibility(), y luego encadenas los métodos AxeDevtoolsMatcher sobre ella para configurar la comprobación.

Los ejemplos en esta página asumen que webDriver es tu WebDriver de Selenium, driver es un AxeDriver que lo envuelve, y estas importaciones estáticas. Las clases de selectores provienen de com.deque.html.axedevtools.matchers.selectors, y 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 clase base de los comparadores de Axe DevTools. Extiende TypeSafeMatcher<AxeDriver> de Hamcrest, por lo que se compara contra un AxeDriver. No creas uno directamente: usa IsAccessible o IsAuditedForAccessibility, que heredan todos los métodos a continuación.

Cada método de configuración devuelve el mismo comparador, por lo que las llamadas se pueden encadenar. El escaneo en sí se ejecuta cuando assertThat evalúa el comparador. Detrás de escena, cada comparador ejecuta un escaneo AxeSelenium, por lo que las reglas descritas allí para combinar opciones se aplican aquí también.

within(String...)

Limita el escaneo a los elementos que coinciden con los selectores CSS dados y sus descendientes. Cada selector agrega un área separada al escaneo, por lo que within("#header", "#footer") prueba ambos, igual que llamar within una vez por cada uno. Esto difiere de AxeSelenium.include(Object...), donde varios argumentos forman un solo camino.

public AxeDevtoolsMatcher within(String... cssSelectors);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

within(Selector...)

Limita el escaneo a las áreas descritas por objetos Selector. Úselo con IFrameSelector para probar un elemento dentro de un iFrame. Cada selector agrega un área separada al escaneo.

public AxeDevtoolsMatcher within(Selector... selectors);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

within(Object...)

Limita el escaneo a áreas descritas por otros objetos de selector, más útilmente FromFrames y FromShadowDom. Úselo para probar un elemento dentro de un árbol de DOM encapsulado, que los objetos Selector no pueden expresar. Cada argumento agrega un área separada al escaneo.

public AxeDevtoolsMatcher within(Object... selectors);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

excluding(String...)

Elimina los elementos que coinciden con los selectores CSS dados y sus descendientes del escaneo. Cada selector elimina un área separada. Las exclusiones se aplican además de cualquier llamada a within, lo que te permite probar una región excepto por una parte de ella.

public AxeDevtoolsMatcher excluding(String... cssSelectors);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

excluding(Selector...)

Elimina las áreas descritas por objetos Selector del escaneo, como un elemento dentro de un iFrame. Cada selector elimina un área separada.

public AxeDevtoolsMatcher excluding(Selector... selectors);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

excluding(Object...)

Elimina áreas descritas por otros objetos de selector, más útilmente FromFrames y FromShadowDom, del escaneo. Cada argumento elimina un área separada.

public AxeDevtoolsMatcher excluding(Object... selectors);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

accordingTo(String...)

Ejecuta solo las reglas que tienen al menos una de las etiquetas dadas, como wcag2a o best-practice.

accordingTo y checkingOnly establecen la misma opción, por lo que solo la última de las dos llamadas tiene efecto. Una segunda llamada a accordingTo también reemplaza las etiquetas de la primera, por lo que debes pasar todas las etiquetas en una sola llamada.

public AxeDevtoolsMatcher accordingTo(String... tags);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

checkingOnly(String...)

Ejecuta solo las reglas nombradas y ninguna otra.

checkingOnly y accordingTo establecen la misma opción, por lo que solo la última de las dos llamadas tiene efecto. Una segunda llamada a checkingOnly también reemplaza las reglas de la primera, por lo que debes pasar todos los IDs de regla en una sola llamada.

public AxeDevtoolsMatcher checkingOnly(String... rules);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

checking(String...)

Activa las reglas nombradas además de las seleccionadas por el conjunto de reglas o por accordingTo.

checking y skipping establecen la misma opción, por lo que solo la última de las dos llamadas tiene efecto, y una segunda llamada a checking reemplaza las reglas de la primera. Pasa todos los IDs de regla en una sola llamada, y no combines checking con skipping en el mismo chequeo.

public AxeDevtoolsMatcher checking(String... rules);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

skipping(String...)

Desactiva las reglas nombradas, dejando el resto del conjunto de reglas o etiquetas seleccionadas en su lugar.

skipping y checking establecen la misma opción, por lo que solo la última de las dos llamadas tiene efecto, y una segunda llamada a skipping reemplaza las reglas de la primera. Pasa todos los IDs de regla en una sola llamada, y no combines skipping con checking en el mismo chequeo.

public AxeDevtoolsMatcher skipping(String... rules);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

ignoring(String, String)

Elimina las violaciones de una regla de los resultados cuando esa regla falla en un elemento dado, para que no fallen la aserción. El selector debe coincidir exactamente con el target del elemento en los resultados, en la forma "[#sidebar]".

El filtrado funciona en reglas completas: si cualquier elemento que falla la regla coincide con el selector, la entrada completa de la regla se elimina, incluidas las fallas en otros elementos. Una llamada por regla es suficiente; dos llamadas para la misma regla que ambas coinciden lanzan un IllegalStateException. Consulta AxeSelenium.ignoring(String, String) para más detalles.

public AxeDevtoolsMatcher ignoring(String selector, String ruleId);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

forConfig(URL)

Selecciona el conjunto de auditoría (un archivo de configuración de reglas JSON) para verificar, por URL. Como AxeSelenium.forConfig(URL), esto establece el conjunto de auditoría global, por lo que también se aplica a chequeos posteriores.

public AxeDevtoolsMatcher forConfig(URL auditPath);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

forConfig(String)

Selecciona el conjunto de auditoría para verificar, por su ruta en el sistema de archivos. Como forConfig(URL), establece el conjunto de auditoría global.

public AxeDevtoolsMatcher forConfig(String auditPath) throws MalformedURLException;

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Lanza

MalformedURLException si no se puede convertir la ruta a una URL.

Ejemplo

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

forRuleset(String)

Selecciona el conjunto de reglas para verificar, como wcag2.2 o 508, con las reglas de mejores prácticas desactivadas. Pasar null selecciona el predeterminado, wcag2.1. Como AxeSelenium.forRuleset(String), esto establece el conjunto de reglas global, por lo que también se aplica a pruebas posteriores. Consulta AxeConfiguration.forRuleset(String) para los IDs del conjunto de reglas.

Los comparadores no tienen forma de activar las reglas de mejores prácticas junto con un conjunto de reglas. Para hacerlo, llama a AxeConfiguration.configure().forRuleset(rulesetId, true) antes de la prueba, y no llames también al forRuleset del comparador, que desactiva las reglas de mejores prácticas.

public AxeDevtoolsMatcher forRuleset(String rulesetId);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

logResults(AxeReportingOptions)

Escribe un informe de esta verificación: un archivo .log que lista las violaciones y un archivo .json con los resultados completos. Los nombres de archivo y la ubicación provienen de reportingOptions; consulta AxeReportingOptions. Con isAxeClean(), no se escribe un informe a menos que llames a logResults.

Si reportingOptions no tiene un número de línea establecido, Axe DevTools registra la línea de tu prueba que llamó a logResults.

public AxeDevtoolsMatcher logResults(AxeReportingOptions reportingOptions);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

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

setReportingOptions(AxeReportingOptions)

Reemplaza las opciones de informe que isAuditedForAccessibility() usa cuando no llamas a logResults. No tiene efecto en isAxeClean(), que solo escribe un informe a través de logResults. Las opciones que pasas reemplazan completamente los valores predeterminados: cualquier valor que no establezcas recae en AxeConfiguration (los informes van a axe-reports a menos que establezcas outputDirectory), y debes establecer uiState.

public AxeDevtoolsMatcher setReportingOptions(AxeReportingOptions reportingOptions);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

setTimeout(int)

Establece cuánto tiempo, en segundos, puede analizar el núcleo axe la página antes de que la prueba falle por tiempo de espera. El valor predeterminado es de 30 segundos.

public AxeDevtoolsMatcher setTimeout(int timeout);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

enableAnalytics(boolean)

Activa o desactiva el servicio de uso para esta verificación. El servicio de uso está activado por defecto. Cuando se establece la variable de entorno AXE_TRACK_USAGE, ésta tiene prioridad y este método no tiene efecto: true activa el servicio y cualquier otro valor lo desactiva.

public AxeDevtoolsMatcher enableAnalytics(boolean state);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

trackingEnabled()

Informa si esta verificación envía datos de uso.

public boolean trackingEnabled();

Devuelve

true si el servicio de uso está activado.

setAnalyticsUrl(String)

Configura la URL a la que se envían los datos de uso. El valor predeterminado es la variable de entorno AXE_METRICS_URL, o https://usage.deque.com cuando no se establece. Cuando se configura AXE_METRICS_URL, este método no tiene efecto.

public AxeDevtoolsMatcher setAnalyticsUrl(String url);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

setAnalyticsDisinctId(String)

Configura el ID distintivo que se envía con los datos de uso. El nombre del método se escribe Disinct en la API, así que escríbelo exactamente como se muestra. El ID se guarda en ~/.deque/distinct_id, por lo que las ejecuciones posteriores en la misma máquina lo seguirán usando. Cuando el ID proviene de la variable de entorno AXE_DISTINCT_ID, este método no tiene efecto.

public AxeDevtoolsMatcher setAnalyticsDisinctId(String id);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

setAnalyticsComponentName(String)

Configura el nombre del proyecto enviado con los datos de uso. Esto también restablece cualquier llamada previa de setAnalyticsUrl y enableAnalytics en este comparador a sus valores predeterminados, por lo que deberás llamarlo antes que a esos métodos. Un ID distintivo configurado con setAnalyticsDisinctId se mantiene.

public AxeDevtoolsMatcher setAnalyticsComponentName(String name);

Parámetros

Devuelve

Este comparador, para encadenamiento de métodos.

Ejemplo

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

com.deque.html.axedevtools.matchers.IsAccessible

Un comparador que falla la aserción cuando la página tiene violaciones de accesibilidad. Extiende AxeDevtoolsMatcher, por lo que cada método anterior se puede encadenar a él para configurar el alcance, las reglas, el conjunto de auditoría y la generación de reportes.

Cuando falla la aserción, el mensaje de error enumera cada violación, los elementos afectados y cómo solucionarlos, en el mismo formato que el informe .log. Si axe-core devuelve un error en lugar de resultados, la verificación lanza un AxeRuntimeException en lugar de fallar la aserción.

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

isAxeClean()

Crea un comparador IsAccessible. Este método estático es la única manera de obtener uno. Sin más configuración, verifica toda la página contra el conjunto de reglas global, que por defecto es wcag2.1, y no genera ningún informe.

public static IsAccessible isAxeClean();

Devuelve

Un nuevo comparador IsAccessible.

Ejemplo

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

com.deque.html.axedevtools.matchers.IsAuditedForAccessibility

Un comparador que escanea la página y genera un informe, pero nunca falla la aserción debido a violaciones. Un error de axe-core aún lanza un AxeRuntimeException, como con isAxeClean(). Úsalo para recopilar resultados para monitoreo sin interrumpir la construcción; necesitarás seguir los regresos de los informes, fuera de los pases y fallos de pruebas. Extiende AxeDevtoolsMatcher, por lo que cada método anterior se puede encadenar a él.

A menos que llames a logResults, el informe se escribe en target/axe-report/accessibility-check.log y target/axe-report/accessibility-check.json. Usa setReportingOptions para cambiar esos valores predeterminados. Cada verificación sobrescribe el informe anterior en la misma ruta, por lo que debes darle a cada verificación su propio nombre de conjunto de pruebas o estado de UI a través de setReportingOptions o logResults, o activar useUniqueFilename.

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

isAuditedForAccessibility()

Crea un comparador IsAuditedForAccessibility. Este método estático es la única manera de obtener uno.

public static IsAuditedForAccessibility isAuditedForAccessibility();

Devuelve

Un nuevo comparador IsAuditedForAccessibility.

Ejemplo

@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

La interfaz implementada por ElementSelector y IFrameSelector. Pasa selectores a within(Selector...) o excluding(Selector...).

toList()

Devuelve el selector como una lista de selectores CSS: uno por nivel de iFrame, seguido del selector para el elemento. Ambas implementaciones lo proporcionan. Los comparadores lo llaman por ti; no necesitas llamarlo en las pruebas.

List<String> toList();

Devuelve

Los selectores CSS, como un List\<String>.

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

Un Selector para un elemento en el documento actual. Por sí solo es equivalente a pasar la cadena del selector CSS a within o excluding; su uso principal es como la parte más interna de un IFrameSelector.

ElementSelector(String)

Crea un selector para los elementos coincidentes según un selector CSS.

public ElementSelector(String cssSelector);

Parámetros

Ejemplo

// 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 para un elemento dentro de un iFrame. Anida un IFrameSelector dentro de otro para alcanzar un elemento dentro de iFrames anidados.

IFrameSelector(String, String)

Crea un selector para un elemento dentro de un iFrame.

public IFrameSelector(String frameSelector, String cssSelector);

Parámetros

Ejemplo

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

IFrameSelector(String, Selector)

Crea un selector para un elemento dentro de un iFrame, donde el elemento está descrito por otro Selector. Pasa otro IFrameSelector para ir un iFrame más profundo, o un ElementSelector.

public IFrameSelector(String frameSelector, Selector selector);

Parámetros

Ejemplo

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