QA y automatización: axe-core, Playwright, pa11y-ci y definición de hecho

La automatización no hace accesible un producto, pero evita que deje de serlo. Un conjunto de pruebas automáticas bien colocado en el flujo de integración continua detecta las regresiones más comunes en segundos, libera a QA para las comprobaciones que exigen criterio humano y da a la organización una red de seguridad medible. En esta lección verás qué herramientas usar, dónde colocarlas, cómo configurarlas y, sobre todo, qué no pueden hacer.

Qué cubre la automatización y qué no

Las herramientas automáticas basadas en reglas (axe-core es el motor más extendido; también lo usan Lighthouse y muchas extensiones) detectan de forma fiable problemas como: imágenes sin atributo alt, campos sin etiqueta, contrastes insuficientes en texto plano, atributos ARIA inválidos o mal combinados, ausencia de idioma de la página, encabezados vacíos, enlaces sin texto, identificadores duplicados. Según distintos estudios, cubren aproximadamente entre un 30 % y un 40 % de los problemas que aparecen en una auditoría manual (algunos fabricantes, midiendo por volumen de incidencias y no por criterios, dan cifras más altas); y en muchos casos solo señalan la posibilidad de un problema que debe confirmar una persona.

No pueden evaluar si un texto alternativo es adecuado, si el orden del foco tiene sentido, si un mensaje de error ayuda a corregir, si un componente personalizado se usa con teclado como se espera, si los subtítulos son correctos o si un proceso completo puede terminarse con lector de pantalla. Esas comprobaciones quedan para las pruebas manuales, que deben estar igual de definidas en el proceso.

Dónde colocar las pruebas: la pirámide

axe-core con Playwright

Playwright es un marco de pruebas de extremo a extremo que controla navegadores reales. El paquete oficial @axe-core/playwright permite analizar la página en cualquier punto de un flujo, incluidos los estados que solo aparecen tras interactuar (un diálogo abierto, un error de validación mostrado).

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

test('el formulario de cita previa no tiene violaciones', async ({ page }) => {
  await page.goto('/cita-previa');
  await page.getByRole('button', { name: 'Continuar' }).click(); // provoca errores de validación

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

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

Algunas decisiones importantes de configuración:

• Etiquetas (tags): limita a los niveles que exiges (A y AA de 2.0, 2.1 y 2.2) para que el pipeline no falle por reglas de buenas prácticas que no son criterios de conformidad, o inclúyelas como avisos, no como errores.
• Exclusiones: excluye componentes de terceros que no puedes corregir, pero regístralos como riesgo conocido y revísalos en las pruebas manuales; no los olvides.
• Estados: analiza después de interactuar. La mayoría de los problemas de ARIA aparecen en menús abiertos, diálogos y mensajes de error, no en la carga inicial.
• Informe: guarda el JSON de resultados como artefacto del pipeline para poder analizar tendencias.

Con Cypress, el paquete cypress-axe ofrece el mismo enfoque con cy.injectAxe() y cy.checkA11y().

pa11y-ci para muchas URL

pa11y-ci recorre una lista de URL (o un sitemap) y falla si encuentra errores, lo que lo hace ideal para un rastreo nocturno del entorno de pruebas o de producción. Un fichero .pa11yci típico:

{
  "defaults": {
    "standard": "WCAG2AA",
    "runners": ["axe", "htmlcs"],
    "timeout": 30000,
    "hideElements": "#cookie-banner",
    "chromeLaunchConfig": { "args": ["--no-sandbox"] }
  },
  "urls": [
    "https://pruebas.ejemplo.es/",
    "https://pruebas.ejemplo.es/tramites",
    { "url": "https://pruebas.ejemplo.es/mi-cuenta", "actions": [
      "set field #usuario to demo",
      "set field #clave to demo",
      "click element #entrar",
      "wait for url to be https://pruebas.ejemplo.es/mi-cuenta/inicio"
    ]}
  ]
}

Usar dos motores (axe y HTML_CodeSniffer) amplía la cobertura, aunque también los falsos positivos; revisa los resultados antes de hacerlos bloqueantes. Un umbral razonable al empezar es «no más errores que en la ejecución anterior» y, una vez estabilizado, «cero errores».

Definición de hecho y criterios de aceptación en QA

La automatización solo funciona si forma parte del contrato del equipo. Dos documentos lo fijan:

• Definición de hecho: el pipeline de accesibilidad pasa en verde; el componente o pantalla se ha probado con teclado; se ha probado con un lector de pantalla si la historia incluye interacción; cualquier exclusión está justificada en la propia prueba y registrada como deuda.
• Criterios de aceptación manuales: QA dispone de una lista por tipo de historia (formulario, tabla de datos, diálogo, navegación, contenido multimedia) con las comprobaciones manuales que la automatización no cubre. Por ejemplo, para un formulario: etiquetas correctas al escuchar cada campo, errores anunciados y enfocados, envío con Enter, orden de foco lógico, comprensible al 400 % de zoom.

Lista de comprobación para implantar la automatización

1. Linter de accesibilidad activo en los repositorios de interfaz.
2. axe-core en las pruebas de componentes del design system, sobre todos los estados.
3. axe-core en Playwright o Cypress en los flujos críticos, analizando tras las interacciones.
4. pa11y-ci o equivalente sobre el entorno de pruebas con ejecución nocturna y umbral definido.
5. Resultados guardados como artefactos para medir tendencia.
6. Definición de hecho con comprobaciones automáticas y manuales.
7. Lista de comprobaciones manuales por tipo de historia a disposición de QA.
8. Registro de exclusiones y reglas deshabilitadas con justificación.

Resumen

• La automatización detecta de forma fiable una parte de los problemas (alrededor del 30-40 %) y es insustituible contra regresiones, pero no verifica la experiencia real.
• Coloca pruebas en todos los niveles: linter, componente, flujos e2e con axe-core en Playwright o Cypress, rastreo con pa11y-ci y pruebas manuales definidas.
• Analiza tras interactuar, limita las etiquetas a los niveles exigidos, registra exclusiones y guarda resultados para medir tendencia.
• La definición de hecho y las listas manuales por tipo de historia convierten la accesibilidad en parte del contrato del equipo.