@surea11y/core

Las pruebas de accesibilidad que te dicen lo que no pueden decirte.

Pruebas de accesibilidad deterministas para Playwright, Cypress, Puppeteer, Selenium, WebdriverIO, Jest/Vitest y pipelines de CI.

@surea11y/core es un motor de pruebas de accesibilidad que ejecutas en tu propia suite de pruebas, canalización de CI o desde la línea de comandos.

Lo que lo distingue es lo que hace con los casos que las pruebas automatizadas no pueden resolver. Implementa el Accessibility Conformance Testing (ACT) Rules Format abierto del W3C, validado con el corpus público de casos de prueba de ACT, en lugar de evaluarse únicamente con sus propias pruebas. Informa hallazgos, ausencia de hallazgos y, de forma poco habitual, incertidumbre explícita, de modo que los resultados son auditables en lugar de tranquilizadores.

Sure significa certeza sobre lo que se sabe, y honestidad sobre lo que no. Te dice lo que no te puede decir.

132 reglas de accesibilidad · 58 validadas contra el corpus ACT · 798 casos de referencia · resultados deterministas · incertidumbre explícita

Ver qué cambió en la última versión

No es un único producto

surea11y es una familia de paquetes que comparten un mismo motor, no una única herramienta con un único comando de instalación. Instala el que coincida con cómo ya pruebas. Cada uno incorpora @surea11y/core por ti:

Consulta Primeros pasos para ver la instalación y el uso de cada integración (binding).

En qué se diferencian sus resultados

Cada regla toma una decisión determinista, a partir de un vocabulario fijo de cuatro resultados, no la forma violations/passes/incomplete/inapplicable que usan otras herramientas populares de pruebas de accesibilidad:

• ✕fail (fail): una violación demostrable a partir del DOM. Reservado para casos objetivos y normativos.
• ✓pass (pass): se cumple la condición específica de esta regla. No es una afirmación de que la página sea accesible.
• ?can't tell (cantTell): una persona tiene que decidir esto, y el resultado indica qué era ambiguo.
• –n/a (notApplicable): la precondición de la regla no está presente.

cantTell expresa uno de los principios centrales del proyecto. Un motor que descarta en silencio lo que no puede determinar produce un informe más corto y una falsa sensación de cobertura. Consulta Resultados e informes para conocer la estructura completa del resultado, y Conformidad para ver cómo los resultados individuales se combinan en un veredicto de WCAG, incluida la forma en que se resuelve y aplica una versión de WCAG objetivo (2.0/2.1/2.2).

Verificado contra el corpus de ACT

El motor incluye 132 reglas. Cincuenta y ocho de ellas tienen una contraparte en W3C ACT Rules y se ejecutan contra los propios casos de prueba publicados por ACT: 798 ejemplos en esas 58 reglas. El motor no falla en ninguno de los ejemplos que ACT marca como aprobados o no aplicables, por lo que no informa falsos positivos frente a ese corpus. Treinta y un ejemplos que ACT marca como fallidos quedan sin señalar (en su mayoría son juicios de valor, como si un encabezado describe el contenido que tiene debajo). Consulta ACT_RULE_MAPPING.md para ver cada uno, con el razonamiento.

El informe de implementación EARL registra el resultado de cada uno de esos casos, incluidos los resultados aprobados y no aplicables, de modo que una regla que permaneció en silencio porque nada le era aplicable se distingue de una que directamente no está implementada. Consulta Informe EARL para conocer el formato.

Principios clave

• Ejecución determinista. La misma entrada siempre produce la misma salida.
• Conservador por diseño. fail se reserva para violaciones objetivas y normativas, minimizando las falsas alarmas.
• Trazabilidad frente a los estándares. Las reglas se asignan al Criterio de Éxito de WCAG aplicable siempre que corresponde.
• Salida estable y legible por máquina. Los identificadores de regla permanecen estables sin importar el idioma.
• Independiente del framework. Se ejecuta dentro de jsdom o de cualquier framework de automatización de navegador.
• Extensible. Agrega reglas personalizadas, registra políticas y filtra análisis por ID de regla, etiquetas o versión de WCAG.
• Informes localizados. Los mensajes legibles por humanos se pueden traducir sin afectar los datos legibles por máquina: hoy incluye en, fr, de y es.

Filosofía

Automatiza lo que se puede determinar objetivamente. Nunca finjas automatizar lo que no se puede.

Algunos requisitos de WCAG se pueden comprobar con total confianza. Otros necesitan juicio humano, conocimiento del contexto o una evaluación de usabilidad. Una puntuación única o un veredicto binario borra esa diferencia; surea11y la informa. Por eso existen cantTell y notApplicable como resultados, y eso da forma a cada regla del motor.

Lo que surea11y no detecta

Ser explícito sobre los límites de la automatización es parte de la misma filosofía. Por ejemplo, surea11y no:

• confirma que un texto alternativo sea significativo, solo que esté presente (un atributo alt con el valor "image123.png" aprueba la comprobación objetiva);
• juzga si una elección de contraste de color es estéticamente apropiada, solo si cumple la relación de contraste aplicable;
• determina si un mensaje de error realmente explica el problema, ya que eso depende de una lógica de validación que un análisis estático no puede ver;
• detecta una trampa de foco de teclado o contenido recortado al 400% de zoom, ya que ambos requieren simular una interacción real del usuario a lo largo del tiempo, no solo leer el DOM en un instante.

Estos son los casos en los que el motor informa cantTell, y donde el juicio de una persona revisora sigue siendo necesario. Consulta Limitaciones conocidas para ver la lista completa.