Primeros pasos

Instalación

No existe un único comando de instalación. surea11y combina un motor central con varias integraciones publicadas por separado, por lo que el paquete que debes instalar depende de cómo ejecutes actualmente tus pruebas o scripts. Elige la opción que corresponda a tu entorno:

¿No sabes por dónde empezar?

Usa Playwright para analizar una aplicación web real o la CLI para revisar HTML estático desde una terminal o un pipeline de CI.

NecesidadOpción recomendadaMotivo
Analizar una aplicación web realPlaywrightManeja un navegador real y es una integración que las suites de pruebas modernas ya usan, así que los resultados reflejan el layout y el renderizado reales.
Analizar HTML estáticoCLISin integración que escribir: un único comando contra archivos, URLs, un sitemap o un paso de CI; con --browser, también analiza páginas que renderiza su JavaScript.
Ya usas Cypress, Selenium, Puppeteer o WebdriverIOLa integración correspondienteEncaja directamente en el entorno de pruebas que ya tienes.
Tests unitarios o de componentestest-matchersIntegración directa con Jest/Vitest contra jsdom.
Integración propia o acceso directo al motor@surea11y/coreMáximo control sobre la ejecución y los resultados.

Un ejemplo de cinco minutos

La CLI es la forma más rápida de ver un resultado real: sin configurar un navegador, sin framework de pruebas. Analiza una página mínima:

<html lang="en">
<body>
<main>
<h1>Welcome</h1>
<p style="color: #999999; background-color: #ffffff;">This text has low contrast.</p>
<a href="/details">Click here</a>
</main>
</body>
</html>
$ npm install -g @surea11y/cli
$ surea11y scan ./index.html
surea11y scan: file:///path/to/index.html
engine: @surea11y/core 1.16.1
pass: 14 fail: 3 cantTell: 2 notApplicable: 126
occurrences by tier: fail: 3 cantTell: 2
needs review: likely fail: 0 likely pass: 0 needs a person: 2
FAIL (3 rule(s)):
contrast-enhanced (serious, 1 fail occurrence(s))
- html > body > main > p
Element has insufficient color contrast (AAA) of 2.85:1 (foreground:
#999999, background: #ffffff, font size: 16px, font weight: normal).
Expected contrast ratio of 7:1 (normal text).
hint: Change the text color, the background color, or both, so the
contrast ratio reaches at least 7:1.
contrast-minimum (serious, 1 fail occurrence(s))
- html > body > main > p
Element has insufficient color contrast of 2.85:1 (foreground:
#999999, background: #ffffff, font size: 16px, font weight: normal).
Expected contrast ratio of 4.5:1 (normal text).
hint: Change the text color, the background color, or both, so the
contrast ratio reaches at least 4.5:1.
page-title-present (serious, 1 fail occurrence(s))
- html > head
This page has no <title> element.
hint: Add a <title> that says what the page is about or what it is for.
cantTell — needs human review (2 rule(s)): link-name-quality,
manual-review
criteria (WCAG 2.2):
fail 1.4.3 Contrast: minimum; 1.4.6 Contrast: enhanced; 2.4.2 Page
titled
cantTell 1.1.1 Non-text content: text alternatives; 1.2.1 Audio-only
and video-only (prerecorded): transcript; 1.2.2 Captions
(Prerecorded); 1.3.1 Info and Relationships; 1.3.4
Orientation; 1.3.5 Identify Input Purpose; 1.4.1 Use of
Color; 1.4.2 Audio Control; 1.4.4 Resize Text; 1.4.5 Images
of Text; 1.4.12 Text Spacing; 2.1.1 Keyboard; 2.1.3 Keyboard
(No Exception); 2.2.1 Timing Adjustable; 2.2.2 Pause, Stop,
Hide; 2.2.4 Interruptions; 2.4.1 Bypass Blocks; 2.4.3 Focus
order; 2.4.4 Link Purpose (In Context); 2.4.6 Headings and
Labels; 2.4.7 Focus visible; 2.4.9 Link Purpose (Link Only);
2.5.8 Target size: minimum; 3.1.1 Language of page; 3.1.2
Language of Parts; 3.2.5 Change on Request; 3.3.1 Error
Identification; 3.3.2 Labels or Instructions; 3.3.8
Accessible Authentication (Minimum); 4.1.2 Name, role, value:
accessible name; 4.1.2 Name, role, value: ARIA validity;
4.1.3 Status Messages
notApplicable: 2
A criterion that passes here means the checks that ran found nothing in
it, not that the page conforms.

Dos problemas de los que el motor está seguro, así que dan fail: el texto de bajo contraste, que falla tanto en la relación AA como en la AAA, y el <title> que falta. Después, una lista de cantTell para que revise una persona (¿es "Click here" un buen nombre de enlace?, ¿hay algo aquí que necesite una revisión manual?); la línea needs review indica que ninguna de las dos preguntas tiene tendencia hacia un lado, así que ambas necesitan a una persona. Entre los 126 resultados notApplicable está target-size-minimum: no puede ejecutarse sin un layout CSS real, y un análisis de HTML estático no lo tiene (--browser se lo da).

El último bloque presenta el mismo resultado por criterio de WCAG 2.2: 1.4.3, 1.4.6 y 2.4.2 dan fail; todos los demás criterios que comprueba el análisis son cantTell y quedan para una persona; y los 2 sin nada que juzgar solo se cuentan. Ninguno figura como pass: desde @surea11y/core 1.14, un criterio solo pasa cuando sus reglas comprueban todo lo que pide, y todavía no lo hace ninguno, así que, cuando todas pasan, el resto sigue en manos de una persona. Consulta Resultados e informes para ver qué significa cada campo de un resultado completo.

  • Tests end-to-end, manejando un navegador real o headless: Cypress, Playwright, Puppeteer, Selenium o WebdriverIO.
  • Tests unitarios y de componentes, contra jsdom: test-matchers, para Jest o Vitest.
  • Páginas desde una terminal o un pipeline de CI, como HTML estático o en un navegador: la CLI.
  • Sin framework de pruebas ni paso de compilación: standalone: instala @surea11y/core directamente o incorpora el bundle de navegador.

Uso

Ya sea con jsdom, un navegador real, cualquier integración (binding) o la CLI, un análisis devuelve un resultado con la misma estructura nativa: checksResults (una entrada por regla, incluyendo cada pass/notApplicable, no una lista de "solo violaciones") y rulesResults (resultados agregados por SC de WCAG). Esta no es la estructura violations/passes/incomplete/inapplicable que usan otras herramientas populares de pruebas de accesibilidad. Los métodos de cada integración siguen convenciones habituales del ecosistema para facilitar la migración, pero el esquema de resultado más rico se mantiene tal cual. Ver Resultados e informes para el esquema completo.