axe-core y Axe

Cómo funciona

axe-core inspecciona el DOM visible y aplica reglas de accesibilidad. El resultado distingue infracciones, comprobaciones superadas y casos incompletos que requieren revisión. Las pruebas deben cubrir los estados reales: formularios con errores, menús abiertos y diálogos.

Ejemplo: revisar una pantalla

Con axe-core cargado en el navegador de pruebas:

const results = await axe.run(document);
for (const violation of results.violations) {
  console.log(violation.id, violation.help);
}

Puedes incorporar este análisis a las pruebas de navegador y revisar los elementos afectados con herramientas de Deque.

Integración con Playwright

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

test('el formulario de solicitud no tiene infracciones WCAG A/AA', async ({
  page,
}) => {
  await page.goto('/solicitud');
  await page.getByRole('button', { name: 'Enviar' }).click(); // provocar errores de validación

  const resultados = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
    .exclude('#widget-chat-terceros')
    .analyze();

  expect(resultados.violations).toEqual([]);
});

Existen integraciones equivalentes para Cypress (cypress-axe), Selenium, Jest con jsdom (jest-axe) y Storybook (addon a11y), que permiten revisar cada componente aislado (component testing).

Estructura del resultado

Campo	Significado
violations	Infracciones detectadas, con impacto (minor a critical) y nodos afectados
passes	Reglas comprobadas y superadas
incomplete	Requieren revisión humana (por ejemplo, contraste sobre una imagen)
inapplicable	Reglas sin elementos a los que aplicar

Cada infracción incluye un enlace a la explicación de la regla y el selector del elemento, útil para el reporte en CI.

Qué detecta y qué no

Detecta bien	Requiere pruebas manuales
Imágenes sin texto alternativo	Si el texto alternativo es significativo
Campos de formulario sin etiqueta	Orden lógico del foco y trampas de teclado
Contraste insuficiente en texto plano	Comprensión de mensajes de error
Roles y atributos ARIA inválidos	Experiencia real con lector de pantalla
IDs duplicados, jerarquía de encabezados	Contenido dinámico anunciado correctamente

Las pruebas automáticas detectan una parte de los problemas de accesibilidad; el resto exige revisión con teclado y lectores de pantalla (NVDA, VoiceOver, TalkBack).

Adopción gradual

En una aplicación existente con muchas infracciones, empieza registrando la línea base y haz fallar el pipeline solo con infracciones nuevas o de impacto critical y serious. Reduce la deuda por pantallas prioritarias (registro, solicitud de crédito, pagos) y amplía el alcance cada trimestre.

Criterios de implementación

Acuerda qué reglas y niveles WCAG evalúa el equipo. Combina los resultados con pruebas de teclado, foco y lector de pantalla. Una ejecución sin infracciones automáticas no equivale a una auditoría completa.