Saltar al contenido principal
Accesibilidad y Normativa
9 min de lectura

Pruebas automatizadas de accesibilidad en CI/CD: construcción de un pipeline sin regresiones con Axe-Core, Playwright y GitHub Actions

Guía técnica profunda para integrar pruebas de accesibilidad automatizadas en pipelines de CI/CD utilizando @axe-core/playwright, reglas personalizadas, matriz de contraste para modos claro/oscuro y quality gates en pull requests para WCAG 2.2 AA.

AY
Artur Yusupov
Ingeniero Web Fullstack y Desarrollador IA
Pruebas automatizadas de accesibilidad en CI/CD: construcción de un pipeline sin regresiones con Axe-Core, Playwright y GitHub Actions

1. El coste de auditar la accesibilidad al final del proyecto

En los equipos de software ágiles, la accesibilidad suele postergarse hasta el final del ciclo mediante auditorías manuales anuales.

Este enfoque presenta graves deficiencias:

  • Coste de remediación elevado: Corregir un modal inaccesible, una jerarquía de encabezados rota o la ausencia de foco en producción requiere hasta 10 veces más tiempo de desarrollo que hacerlo en un pull request.
  • Regresiones constantes: Más del 57% de los fallos de WCAG en entornos reales surgen de pequeñas modificaciones de CSS o actualizaciones de librerías que eliminan el contraste o los anillos de foco.

La respuesta de ingeniería moderna es DevSecOps para Accesibilidad: desplazar las comprobaciones a la izquierda en pipelines de integración continua con Axe-Core y Playwright.

Matriz de metodologías de prueba de accesibilidad: Manual vs Lighthouse vs Playwright + Axe-Core

Enfoque de auditoría
Auditoría manual con lector de pantalla
Cobertura de reglas WCAG 2.2
100% (Incluye contexto semántico humano)
Integración en CI/CD
Imposible en pipeline automatizado
Velocidad de ejecución
Días o semanas
Tasa de falsos positivos
Alta (Subjetividad del auditor)
Enfoque de auditoría
Lighthouse CI (Escaneo básico)
Cobertura de reglas WCAG 2.2
~25% - 30% de violaciones
Integración en CI/CD
Configuración simple en GitHub Actions
Velocidad de ejecución
15 - 30 segundos
Tasa de falsos positivos
Moderada (Avisos genéricos)
Enfoque de auditoría
Playwright + Axe-Core (Recomendado)
Cobertura de reglas WCAG 2.2
~55% - 60% (Estructurales y contraste)
Integración en CI/CD
Quality gate bloqueante en PR con SARIF
Velocidad de ejecución
< 3 segundos / página
Tasa de falsos positivos
0% (Reglas DOM deterministas)

2. Esquema arquitectónico del pipeline automatizado

El sistema opera en tres niveles de validación:

CODE
┌──────────────────┐      ┌─────────────────────────┐      ┌──────────────────────────┐
│ Bucle Local Dev  │ ───> │   Quality Gate en PR    │ ───> │  Despliegue a Producción │
│ Pre-commit Hook  │      │ GitHub Actions CI Scan  │      │  Monitorización Continua │
│ (Vitest / A11y)  │      │  Playwright + Axe-Core  │      │   SARIF / Lighthouse     │
└──────────────────┘      └─────────────────────────┘      └──────────────────────────┘
1
Pre-commit: Pruebas unitarias de componentes con axe-core en entornos locales.
2
Pull Request (CI): Ejecución end-to-end en navegadores headless mediante @axe-core/playwright sobre el DOM renderizado real.
3
Quality Gate: Bloqueo automático del merge si se detecta cualquier infracción crítica o severa.

3. Configuración de @axe-core/playwright

Instalación de las dependencias necesarias:

BASH
pnpm add -D @axe-core/playwright @playwright/test

Utilidad centralizada en TypeScript con reporte detallado:

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

export async function checkA11y(page: Page) {
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
    .exclude('#clarity-script')
    .analyze();

  if (results.violations.length > 0) {
    const errorReport = results.violations.map((v) => {
      const nodes = v.nodes.map((n) => `  - ${n.target.join(' ')}: ${n.failureSummary}`).join('\n');
      return `[A11y Violation] ${v.id}: ${v.description}\n${nodes}`;
    }).join('\n\n');

    expect(results.violations, errorReport).toEqual([]);
  }
}

4. Pruebas de estados dinámicos y matriz de temas

  • Modales accesibles: Validación de la captura de foco interior y cierre inmediato con la tecla Escape.
  • Matriz de contraste claro/oscuro: Verificación automatizada de que los ratios de 4.5:1 en texto y 3:1 en bordes se cumplen tanto en tema oscuro como en tema claro.

5. Configuración de GitHub Actions

El flujo de trabajo en .github/workflows/a11y-ci.yml compila la aplicación y ejecuta las pruebas de accesibilidad antes de permitir el merge a la rama principal.


6. Beneficios en producción

  • Detección automática del 40% al 50% de las violaciones de accesibilidad antes de revisión de código.
  • Ejecución completa en menos de 3.5 segundos por pull request.
  • Trazabilidad y cumplimiento legal garantizado frente a la Ley Europea de Accesibilidad 2026.
Implementación real en producción

Dónde funciona esta arquitectura en proyectos reales

Estas soluciones no son teoría abstracta: están desplegadas y verificadas en los siguientes productos reales:

Auditoría de Arquitectura

¿Planeas una migración técnica o nuevo proyecto?

Consulta los requerimientos de tu proyecto con el asistente de IA o solicita una evaluación técnica directa.

Contactar directamente