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.

Necesidad	Opción recomendada	Motivo
Analizar una aplicación web real	Playwright	Maneja 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ático	CLI	Sin integración que escribir: un único comando contra un archivo, una URL o un paso de CI.
Ya usas Cypress, Selenium, Puppeteer o WebdriverIO	La integración correspondiente	Encaja directamente en el entorno de pruebas que ya tienes.
Tests unitarios o de componentes	test-matchers	Integración directa con Jest/Vitest contra jsdom.
Integración propia o acceso directo al motor	`@surea11y/core`	Má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
  pass: 6   fail: 2   cantTell: 3   notApplicable: 114
  occurrences by tier: fail: 2   cantTell: 4
FAIL (2 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: 0px, font weight: normal). Expected contrast
      ratio of 7:1 (normal text).
  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: 0px, font weight: normal). Expected contrast
      ratio of 4.5:1 (normal text).
cantTell — needs human review (3 rule(s)): contrast-computable, link-name-quality,
manual-review

Un fail del que el motor está seguro (contraste), una lista de cantTell para que revise una persona (¿es "Click here" un buen nombre de enlace?, ¿ese mismo texto de bajo contraste pasa otra comprobación distinta?, ¿hay algo aquí que necesite una revisión manual?) y, entre los 114 resultados notApplicable, target-size-minimum: no puede ejecutarse sin un layout CSS real, y un análisis de HTML estático no lo tiene. 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.
HTML estático desde una terminal o un pipeline de CI: 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.