Escribir pruebas con Selenium

Esta configuración de Axe DevTools no está inherentemente vinculada a ninguna biblioteca de afirmaciones. Esto permite realizar pruebas de accesibilidad simples, así como la total personalización de las pruebas y el uso con afirmaciones personalizadas.

Requisitos previos

Para poder usar Axe DevTools Java Selenium y obtener resultados con él, debe haber creado previamente un archivo de prueba con Axe DevTools y tener su elección de Selenium WebDriver importado e inicializado. Si no ha completado este paso, primero lea esta guía sobre cómo hacerlo.

Ejecutar un escaneo

Con esta configuración, ejecutar un escaneo básico de accesibilidad requiere solo tres líneas de código. En su archivo de prueba, reemplace <URL> con la dirección web deseada de la página que desea probar. Los resultados del escaneo se guardan en la variable results

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

Utilizar los resultados del escaneo

Una vez que haya ejecutado el escaneo, puede que quiera hacer algo con los resultados. La opción más sencilla es imprimir los resultados en la consola.

System.out.print(results);

También puede usar los resultados para verificar violaciones de accesibilidad. La forma más sencilla de hacerlo es con una instrucción como esta:

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

Para obtener más información sobre cómo utilizar el objeto de resultados para escribir pruebas personalizadas, consulte la página sobre usando los resultados.

Archivo de prueba de muestra

Este archivo de prueba funciona con los mismos componentes básicos cubiertos en importar e inicializar, así como la guía de escritura de pruebas en esta página.

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!");
    }
}

En este ejemplo, se utilizan Chrome y ChromeDriver. Esto puede sustituirse por cualquier otro controlador de navegador de Selenium y navegador. Si este archivo de prueba encuentra algún problema de accesibilidad, imprime el número de violaciones encontradas y sale con el código de estado 1 (error). Para usar este archivo de prueba en su propio entorno, deberá agregar una URL a la línea

webdriver.get("<URL>");

Referencia adicional

Además del uso básico descrito anteriormente, Axe DevTools Java Selenium ofrece varios métodos encadenados para modificar la forma en que se realiza el escaneo. Estos métodos pueden modificar el alcance y el conjunto de reglas del escaneo a cualquier configuración deseada. Por defecto, se escanea toda la página y se verifican las violaciones de accesibilidad según las pautas WCAG 2.1 nivel AA, con las reglas de mejores prácticas y experimentales desactivadas. Las configuraciones de estos métodos encadenados permanecen en el objeto AxeSelenium, y include y exclude se suman a las áreas anteriores cada vez que los llamas, por lo que reutilizar un objeto para un segundo escaneo configurado de manera diferente conserva la configuración del primer escaneo. Crea un nuevo AxeSelenium para cada escaneo configurado de manera diferente.

Alcance

Por defecto, se escanea toda la página. Sin embargo, Axe DevTools permite la capacidad de escanear porciones específicas de una página con sus métodos de encadenamiento de ámbito. Estos métodos de ámbito cambian efectivamente la "superficie" de la página a escanear hacia el área deseada. Además, hay disponible un método para ignorar violaciones. Este método no reduce el área del escaneo; ignora las violaciones de una regla cuando esta falla en un elemento específico, mientras que el resto de la página se sigue verificando como de costumbre. Todos estos métodos funcionan según las áreas del selector CSS. El área de cada selector CSS en una página dada se puede determinar usando el widget "inspeccionar elemento" de las herramientas de desarrollo de tu navegador.

Métodos de alcance

Como se explicó anteriormente, estos métodos cambian efectivamente la área de superficie de la página que se escaneará. Hay dos métodos en esta categoría, un método "inclusivo" y un método "exclusivo". Pueden encadenarse mutuamente entre sí para crear múltiples enclaves y exclaves de área de escaneo.

Definición del alcance - Inclusión

El método de encadenamiento de ámbito include altera el escaneo para ejecutarse únicamente dentro del área de la página especificada por el(los) selector(es) CSS que se le pasan. Hay varias maneras de usar el método include: ámbito único, ámbito múltiple, ámbito compuesto y ámbito de IFrame.

Este método se puede utilizar con un solo selector de la siguiente manera:

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

Este escaneo solo se ejecutará dentro del alcance del selector 1

Puede configurar un escaneo con múltiples alcances:

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

Esta llamada escaneará dentro del ámbito del selector 1 y del selector 2. Pueden estar separados por comas o declarados en una llamada include aparte.

El alcance compuesto se puede lograr con la siguiente sintaxis:

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

Este alcance compuesto da como resultado que solo se escaneen los elementos con el selector 2 dentro del selector 1. Esto se configura al no separar con comas los selectores.

Para definir el alcance dentro de un IFrame, se puede pasar un List<String>. El alcance a ser escaneado dentro del IFrame se pasa como un parámetro adicional.

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

Este escaneo se ejecuta en elementos dentro del selector 1, que está dentro del marco 1.

Definir el alcance dentro de múltiples IFrames funciona de la misma manera que la selección múltiple estándar. Simplemente llame a include nuevamente.

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

Este escaneo se ejecuta solo dentro del selector 1 dentro del marco 1, y el selector 2 dentro del marco 2.

También es posible definir el alcance dentro de IFrames anidados:

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

Este escaneo se ejecuta dentro del alcance del selector 1 dentro del marco 2, que a su vez está dentro del marco 1

Definición del alcance - Exclusión

Además del método de encadenamiento include, esta API tiene un método exclude. Este método altera el escaneo de modo que solo se escanearán los elementos fuera del ámbito especificado. Su configuración y uso son idénticos al método include, por lo que consulta la sección anterior para más detalles y ejemplos de cómo se puede usar. Un detalle importante a recordar es que los métodos include y exclude pueden encadenarse entre sí para crear ámbitos complejos de manera mucho más sencilla que usando solo include o exclude.

Este ejemplo muestra una de las maneras de combinar los métodos include y exclude:

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

Este escaneo se ejecuta solo en la parte de la página que está dentro del selector 1 y que no está también dentro del selector 2.

Definición del alcance - Ignorar violaciones

El último método de encadenamiento relacionado con el ámbito es el método de ignorar resultados. Este método no altera el alcance general del escaneo; ignora las violaciones de una regla cuando esta falla en un elemento específico. Funciona pasando el target del elemento que deseas ignorar, tal como aparece en los resultados, junto con la regla que viola. El objetivo se escribe de la manera en que Java imprime una lista, con el selector dentro de corchetes, como "[.sidebar]". Una llamada ignoring por regla es suficiente, porque una coincidencia elimina toda la entrada de la regla. No lo llames dos veces para la misma regla: si ambos objetivos coinciden con elementos fallidos, el escaneo arroja un IllegalStateException.

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

Este escaneo ignorará la violación de contraste de color en la barra lateral y la violación de texto alternativo de la imagen en el contenido de marca. Si el objetivo coincide con un elemento que falla la regla, se elimina toda la entrada de la regla de las violaciones, incluidas las fallas en otros elementos. Consulta AxeSelenium.ignoring(String, String) en la referencia de la API.

Reglas

Hay tres maneras de modificar tu configuración de reglas para cada escaneo. Estos diferentes métodos permiten diferentes grados de granularidad al seleccionar las reglas a probar. El método de conjunto de reglas menos granular selecciona un conjunto de reglas, o un grupo más grande de reglas basadas en estándares comunes de accesibilidad. El método de estándares de reglas ligeramente más granular, también conocido como etiquetas, selecciona reglas basadas en las áreas en las que encajan dentro de un estándar de accesibilidad más amplio. Finalmente, hay tres opciones para la configuración con una regla a la vez. Todos juntos, estos métodos encadenados te permiten ajustar tu escaneo para ejecutar precisamente las reglas que deseas.

Para obtener información sobre las reglas de axe-core, visite la página de resumen de conjuntos de reglas.

Selección de conjuntos de reglas

Este método selecciona reglas por su asociación más agregada: un conjunto de reglas. Un conjunto de reglas es una colección de todas las reglas que pertenecen a un estándar de accesibilidad de toda la industria. Conjuntos de reglas para WCAG 2.0, 2.1 y 2.2; ADA Sección 508; Trusted Tester v5; EN 301 549; y RGAA. Además, las reglas de mejores prácticas pueden activarse con una bandera booleana.

Los conjuntos de reglas a menudo están compuestos por múltiples etiquetas, que son reglas agrupadas por distinciones más específicas. Por ejemplo, el conjunto de reglas wcag2 contiene todas las reglas etiquetadas wcag2a reglas de nivel A de WCAG 2.0, wcag2aa para reglas de nivel AA de WCAG 2.0, y wcag2aaa para reglas de nivel AAA de WCAG 2.0.

Utilice esta opción cuando desee seleccionar un conjunto de reglas sin modificar.

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

Esta verificación se ejecutará solo con las reglas de WCAG 2.1.

Para habilitar las reglas de mejores prácticas, use la segunda forma de forRuleset.

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

Selección de estándar

El método de cadena de estándares de accesibilidad, o etiqueta, permite una mayor granularidad dentro de los conjuntos de reglas de axe-core. Para las reglas basadas en WCAG, este método le permite seleccionar solo las reglas etiquetadas como nivel-A o nivel-AA. Esta lista desglosa los nombres de etiquetas disponibles y sus estándares correspondientes.

Esta opción es particularmente útil cuando solo se prueba una porción específica de un conjunto de reglas, por ejemplo, solo las reglas de nivel A bajo WCAG 2.0.

Aunque no están definidas explícitamente como parte de ningún estándar de accesibilidad, ofrecemos una serie de reglas que llamamos "mejores prácticas". Aunque no son estrictamente necesarias, probar con estas reglas ayudará a que su sitio web sea lo más equitativo posible en su uso.

Se puede seleccionar un solo estándar de la siguiente manera:

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

Esta verificación se ejecutará solo con reglas etiquetadas bajo WCAG 2.0 nivel A

Además, se pueden especificar múltiples etiquetas para seleccionar múltiples estándares de accesibilidad:

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

Estas verificaciones ejecutarán tanto las reglas etiquetadas bajo WCAG 2.0 nivel A como ADA Sección 508.

Selección de reglas

Finalmente, puede alterar su conjunto de reglas por una sola regla. Para obtener información sobre los nombres de todas las reglas de axe-core y qué prueba cada regla, consulte la documentación de descripciones de reglas de axe-core.

Estos métodos funcionan bien cuando su grupo final deseado de reglas solo difiere de un conjunto de reglas o estándar/etiqueta existente en unas pocas reglas individuales. Para construir un conjunto de reglas completamente personalizado, consulte nuestras opciones de reglas personalizadas.

Comprobación de reglas adicionales

El método de cadena de comprobación le permite agregar reglas adicionales para probar además de su conjunto de reglas estándar.

Este método se puede usar para verificar una sola regla adicional:

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

donde el escaneo se ejecuta con el conjunto de reglas predeterminado además de la regla "label".

Para verificar varias reglas adicionales, pásalas todas en una llamada. Llamar a checking una segunda vez reemplaza las reglas de la primera llamada en lugar de agregarlas.

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

donde el escaneo se ejecuta con el conjunto de reglas predeterminado además de las reglas "label" y "tabindex".

También se puede usar para agregar una o varias reglas a una etiqueta especificada:

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

donde el escaneo se ejecuta probando contra las reglas de nivel A de WCAG 2.0, con la adición de la regla "tabindex".

Omisión de reglas

Al igual que el método de verificación, el método de omisión cambia las reglas predeterminadas a usar por la(s) regla(s) especificada(s). Sin embargo, en vez de agregarlas al conjunto de reglas, el método de omisión elimina la(s) regla(s) especificada(s) de aquellas usadas para probar la página. Su configuración y uso son idénticos al método de verificación, por lo que consulta la sección anterior para más detalles y ejemplos sobre cómo usarlo.

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

Este ejemplo muestra un escaneo probando contra las reglas de nivel A de WCAG 2.0, con la eliminación de la regla "label".

Los métodos de verificación y omisión configuran la misma opción, por lo que solo la última de las dos llamadas en un encadenamiento surte efecto. No los combines en el mismo escaneo.

Solo Verificación

El método de solo verificación verifica solo la(s) regla(s) especificada(s). Cualquier regla no especificada explícitamente no se incluirá en el escaneo.

Este método encadenado se puede usar para especificar una sola regla:

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

donde el escaneo se ejecuta solo con la regla "tabindex".

Para especificar más de una regla, pásalas todas en una llamada. Una segunda llamada checkingOnly reemplaza las reglas de la primera. checkingOnly y accordingTo también configuran la misma opción, por lo que solo la última de las dos surte efecto.

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

donde el escaneo se ejecuta solo con las reglas "label" y "tabindex".

Deshabilitación de iframe

En páginas volátiles, los iframes pueden causar problemas. Axe necesita ser inyectado en cada frame y configurado de la misma manera en cada frame. Si se añaden o eliminan iframes mientras AxeSelenium::run está probando tu página, es posible que se lancen excepciones o que se produzca un comportamiento inesperado. Como medida de seguridad, AxeSelenium expone un método para deshabilitar toda interacción con iframes, AxeSelenium::disableIframeTesting. Cuando está habilitado, axe-core no se inyectará en los iframes de la página, ni se ejecutará en dichos iframes. Solo se verificará la página de nivel superior.

Se puede usar de esta manera:

axeselenium.disableIframeTesting().run(axedriver);

Servicio de uso

Obtén información sobre las tendencias de uso de Axe DevTools dentro de tu organización

El servicio de uso se puede configurar a través de variables de entorno o métodos en tiempo de ejecución. Cuando se utilizan ambos, se usan los valores de los métodos. Nota: no todos los campos de datos del servicio de uso pueden establecerse a través de métodos.

De forma predeterminada, el servicio de uso está habilitado y los resultados se envían a https://usage.deque.com. Establezca la variable de entorno AXE_TRACK_USAGE en false para deshabilitarlo. Si sus eventos de uso no llegan a Deque, establezca explícitamente la variable de entorno AXE_METRICS_URL.

Variables de entorno

Estas variables de entorno te permiten configurar el servicio de uso y cambiar las propiedades de los eventos reportados.

Habilitar seguimiento

Este método permite a los usuarios optar por enviar o no datos al servicio de uso. El envío está habilitado por defecto.

.enableTracking(boolean state)

Establecer URL de seguimiento

Este método permite a los usuarios cambiar a dónde se envían los datos de métricas de uso. Por defecto, es https://usage.deque.com

.setTrackingUrl(String url)

Establecer ID distinto

Este método permite a los usuarios cambiar el id distinto que se almacena/usa

.setDistinctId(String distinctId)

Próximos pasos

Una vez que estés escribiendo pruebas con Axe DevTools, lee más sobre usando resultados para escribir pruebas personalizadas más detalladas, o lee sobre usando el generador de reportes para generar reportes de los escaneos de accesibilidad.

Resolución de problemas

Si experimentas problemas al configurar tus pruebas de accesibilidad, contacta directamente a tu representante de Deque, contáctanos a través de nuestra mesa de soporte, o envíanos un correo electrónico. Estamos encantados de ayudar a que tus esfuerzos de pruebas de accesibilidad despeguen.