Pruebas automáticas en el flujo de desarrollo: axe-core, eslint-plugin-jsx-a11y, Lighthouse y tests e2e

Corregir un problema de accesibilidad en producción cuesta mucho más que evitarlo en el editor. Las herramientas automáticas no encuentran todos los problemas, pero encuentran los más repetitivos de forma inmediata, consistente y gratuita, y sobre todo impiden que vuelvan. Esta lección explica qué herramienta encaja en cada punto del flujo de desarrollo, cómo configurarlas y, con la misma importancia, qué no pueden hacer.

Qué detectan y qué no

Se estima que las herramientas automáticas detectan aproximadamente entre el 30 % y el 40 % de los problemas de accesibilidad; el porcentaje real depende del tipo de sitio. Detectan muy bien lo que es sintáctico y determinista: imágenes sin alt, campos sin etiqueta, contraste insuficiente de texto sobre fondo plano, atributos ARIA inválidos, id duplicados, falta de lang, enlaces sin nombre, encabezados que saltan niveles, elementos enfocables ocultos. No pueden detectar si el alt es correcto, si el orden del foco tiene sentido, si el estado ARIA se actualiza, si el nombre de un botón describe su acción, si un modal devuelve el foco, si un carrusel se puede pausar o si un texto es comprensible. Por eso las pruebas automáticas se complementan siempre con el protocolo de teclado del curso anterior y con revisión con lector de pantalla.

axe-core: el motor común

axe-core, de Deque, es la biblioteca de reglas de accesibilidad de código abierto que está detrás de la extensión axe DevTools, de Lighthouse, de Accessibility Insights de Microsoft y de muchas integraciones. Su filosofía es no dar falsos positivos: cuando marca algo como error, casi siempre lo es; a cambio, marca como «necesita revisión» lo que no puede decidir (contraste sobre imágenes, por ejemplo). Se integra en varios puntos:

• Navegador: extensión axe DevTools para analizar la página actual durante el desarrollo.
• Pruebas unitarias de componentes: jest-axe o vitest-axe ejecutan las reglas sobre el HTML renderizado por un componente.
• Pruebas de extremo a extremo: @axe-core/playwright y cypress-axe analizan páginas reales en el navegador, en cada estado (modal abierto, formulario con errores).
• Desarrollo en React: @axe-core/react muestra los problemas en la consola mientras programas, pero solo admite hasta React 17; en versiones posteriores, usa la extensión o las pruebas de componentes.

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('cita previa sin errores de accesibilidad', async ({ page }) => {
  await page.goto('/tramites/cita-previa');
  const inicial = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
    .analyze();
  expect(inicial.violations).toEqual([]);

  await page.getByRole('button', { name: 'Elegir centro' }).click();
  const conDialogo = await new AxeBuilder({ page }).analyze();
  expect(conDialogo.violations).toEqual([]);
});

Las pruebas de extremo a extremo también sirven para automatizar parte del protocolo de teclado: Playwright permite pulsar Tab y comprobar qué elemento tiene el foco, pulsar Escape y verificar que el diálogo se cierra y el foco vuelve al botón, o pulsar flechas en unas pestañas y comprobar aria-selected. Y los locators por rol (getByRole('button', { name: 'Guardar' })) convierten cada test en una verificación implícita de que los controles tienen rol y nombre accesibles: si no los tienen, el test no encuentra el elemento.

Linting: atrapar errores al escribir

eslint-plugin-jsx-a11y analiza el JSX de React en el editor y en la integración continua, antes de que exista una página que probar. Detecta imágenes sin alt, onClick en elementos no interactivos sin rol ni teclado, aria-* inválidos, label sin control asociado, autoFocus, accessKey, enlaces sin href, roles no soportados y más. Se activa con la configuración plugin:jsx-a11y/recommended y conviene usar el modo strict en proyectos nuevos. Para Vue existe eslint-plugin-vuejs-accessibility, y para Angular, las reglas de accesibilidad de angular-eslint (plantillas) cubren casos parecidos. Para HTML estático, html-validate incluye reglas de accesibilidad y el validador del W3C detecta errores de marcado que repercuten en las tecnologías de apoyo.

Lighthouse y las auditorías de página

Lighthouse (integrado en Chrome y ejecutable en CI con lighthouse-ci) usa un subconjunto de reglas de axe y devuelve una puntuación de 0 a 100. Esa puntuación es útil para seguir la tendencia y para que la dirección la entienda, pero es engañosa como medida de conformidad: una página con 100 puede ser inaccesible (orden de foco, estados ARIA, modales) y una con 85 puede tener solo problemas menores. Úsala como indicador, nunca como certificado. Pa11y y pa11y-ci hacen lo mismo con el motor HTML CodeSniffer o axe y son cómodos para rastrear decenas de URL de un sitio en cada despliegue.

Dónde colocar cada herramienta

Definición de hecho

Para que todo esto tenga efecto, la accesibilidad debe formar parte de los criterios de aceptación de cada historia y de la definición de hecho del equipo. Una versión mínima:

1. El linter de accesibilidad no muestra errores.
2. Las pruebas de componente con axe pasan en todos los estados.
3. Las pruebas e2e con axe pasan en las páginas y flujos tocados.
4. Quien revisa el código ha recorrido la funcionalidad con teclado siguiendo el protocolo.
5. Los componentes nuevos se han probado con un lector de pantalla y documentan su teclado.

Con esta cadena, los problemas que las máquinas detectan no vuelven, y el tiempo de las personas se concentra en lo que requiere criterio humano.

Resumen

• Las herramientas automáticas detectan en torno a un tercio de los problemas, los sintácticos y deterministas; el resto exige teclado, lector de pantalla y criterio humano.
• axe-core es el motor común: extensión, jest-axe/vitest-axe en componentes, @axe-core/playwright o cypress-axe en e2e.
• eslint-plugin-jsx-a11y (y equivalentes para Vue y Angular) atrapa los errores al escribir.
• La puntuación de Lighthouse es un indicador de tendencia, no un certificado de conformidad.
• Fija umbrales que no puedan crecer, analiza cada estado de la interfaz y haz de la accesibilidad parte de la definición de hecho.