Informe HTML

Un informe HTML autocontenido que puedes abrir en un navegador después de un análisis: sin servidor, sin recursos externos, sin peticiones de red. Pensado para quienes hacen pruebas de control de calidad (QA) o revisión manual y quieren una vista navegable de los resultados de un análisis en lugar de JSON sin procesar o un resumen de terminal. Abre un informe de ejemplo: una pequeña página de pago analizada con los hooks de listeners y de regiones vivas, con un hallazgo en cada grupo y lo que el análisis deja a una persona.

$ surea11y scan ./dist/index.html --html report.html

Abre report.html directamente desde el disco. Funciona junto a cualquier otro modo de salida: --html no sustituye a --json/al resumen predeterminado, es un artefacto adicional escrito en la ruta indicada.

Qué muestra

Cabecera: un titular en lenguaje llano ("N de M comprobaciones aplicables pasaron") más una barra apilada y una leyenda (icono + etiqueta + recuento; el estado nunca depende solo del color) desglosada por resultado (fail/cantTell/pass/notApplicable). Cuando ninguna regla falló y alguna se aplicó, una nota bajo el titular dice que eso no afirma que la página sea conforme, y nombra lo que una persona aún comprueba: los hallazgos que necesitan revisión, el uso con teclado, cómo lee la página un lector de pantalla y el propio contenido.
Vale la pena revisar: una tarjeta por regla con ocurrencias fail/cantTell (no una por ocurrencia: una regla con muchas ocurrencias idénticas es una sola cosa que merece atención, no muchas), cada una mostrando gravedad, chip(s) de SC de WCAG, en un análisis de varios perfiles lo que hace de ella cada perfil («wai-aria-1.2: No superada» junto a «wcag22-aa: Requiere revisión», sus verdicts), una ocurrencia representativa y el recuento total de ocurrencias. Las reglas que fallan van primero. Les siguen los hallazgos que necesitan revisión, en tres grupos: aquellos cuyos indicios apuntan a un fallo («Probable fallo: confírmelo»), aquellos cuyos indicios apuntan a que cumple («Probablemente cumple: confírmelo») y los que solo una persona puede juzgar («Lo debe revisar una persona»), tal como los clasifica reviewGroupOf(check, occurrence) de @surea11y/core, para que una herramienta que ordena una cola de revisión la ordene igual. Cada tarjeta de los dos primeros dice por qué tiende hacia ese lado (el lean de la ocurrencia). Cada una de estas tarjetas tiene una sección «Cómo comprobarlo», contraída por defecto, con los pasos para responder la pregunta y qué cumple y qué falla (el howToCheck de la ocurrencia). Una regla cuyos hallazgos tienden hacia lados distintos tiene una tarjeta en cada grupo. Dentro de cada grupo, primero la más grave (de crítica a menor) y, con la misma gravedad, la que tiene más ocurrencias. Limitado a las 24 reglas de mayor prioridad, con una nota de desbordamiento a partir de ahí. Una regla que no terminó (lanzó una excepción) también recibe una tarjeta, que lo indica junto con su error, ya que la página no se comprobó con ella. Una regla con un enlace de ayuda http(s) (meta.helpUrl, incluido el de una regla personalizada) recibe en su tarjeta un enlace "How to fix <rule>"; una regla sin él enlaza el documento Understanding del criterio de WCAG que comprueba ("Understanding 1.1.1 Non-text Content").
Frames: solo para un resultado entre frames (runa11yCoreAcrossFrames, o el .frames(true) de una integración). Las tarjetas anteriores son las de la propia página; esta sección tiene un encabezado por frame, nombrado por su ruta (los selectores de los elementos frame que llevan hasta él), con el título y la URL del frame y sus tarjetas, o "Not scanned" y el motivo para un frame que no respondió. El resto del informe describe la propia página.
Lo más cerca del límite: se muestra cuando el análisis tiene márgenes (margin en un resultado de comprobación). Una fila por cada regla cuyo elemento aprobado más cercano quedó cerca de su umbral (dentro de la banda de la regla, como el 10 % de una razón de contraste), como indica la nota sobre la tabla: su valor aprobado más cercano, el límite, el margen que queda y el elemento. Los píxeles se redondean a enteros, con «menos de 1 px» por debajo de uno; las razones muestran dos decimales. Una regla que pasó con poco margen es una que un pequeño cambio puede convertir en un fallo.
Resumen por WCAG: agrupado por nivel de conformidad (A / AA / AAA), obtenido directamente de los resultados agregados compuestos rulesResults[] propios del motor (ver Conformidad): una fila por Criterio de Éxito (con los requisitos de cada otro estándar del standards del resultado a los que se asocian sus reglas, como la cláusula de EN 301 549 que lo reformula, cuando la hay y el análisis pidió cláusulas de EN 301 549), su resultado, un desglose de aprobado/fallido/necesita revisión/n.a. (con una línea «Comprobado en parte» cuando las reglas del criterio solo comprueban parte de lo que pide, así que una persona comprueba el resto, como «Comprobado en parte: sus comprobaciones cubren solo una parte de este criterio, y el resto lo comprueba una persona», o cuando el análisis seleccionó solo algunas de sus reglas, como «Comprobado en parte: 1 de 2 comprobaciones no se seleccionó para este análisis», ver Un criterio comprobado en parte) y qué reglas atómicas contribuyeron, incluida una regla personalizada asociada al criterio. Son datos reales del motor, no una agrupación inventada: el mismo resultado agregado que obtendrías del rulesResults del JSON sin procesar.
Resultado agregado propio de un estándar: solo cuando el análisis ejecutó las reglas de un estándar que tiene sus propios resultados agregados (su perfil, o engineOptions.optInRules), una tabla por estándar, y por versión de él cuando un análisis de varios perfiles juzgó la página con dos (EN 301 549 V3.2.1 con V4.1.1, cada una nombrada por su versión), con una fila por resultado agregado, con la redacción del estándar, los requisitos de las reglas que decidieron el resultado, el desglose y las reglas que contribuyeron. Esto cubre el estándar de un pack y la lista de comprobación de un pack, cuyos elementos son sus resultados agregados. Cada uno de esos estándares figura en el standards del resultado, así que un resultado guardado se muestra igual dondequiera que se genere; cuando esa lista falta o está dañada, el informe lo indica encima del resumen por WCAG.
Lo que queda para una persona (core 1.15.0 y posteriores): lo que el análisis no puede decidir en los requisitos que evalúan sus reglas. Cada requisito del estándar analizado con una comprobación que ninguna regla decide por completo, cada uno con su resultado en el análisis al lado («Análisis: No superada», «Análisis: Superada» o «Ninguna regla lo comprueba») y, debajo, contraídas por defecto, esas comprobaciones: qué evalúa cada una, cuánto de ella deciden las reglas, las herramientas que necesita, los pasos, y qué cumple y qué falla (los procedimientos de prueba de core). Una frase encima dice cuántas comprobaciones y requisitos hay, y que un requisito cuyas reglas se superan todas solo se cumple cuando también se superan sus comprobaciones. El estándar es WCAG, en la versión a la que apuntó el análisis y los niveles de los que informó; cuando el análisis ejecutó el perfil de un pack y el pack, pasado en options.packs, da procedimientos, es el estándar de ese pack, con su propia numeración. Un análisis de varios perfiles tiene una parte por cada estándar y versión. Una nota debajo dice cómo hacer con ellas una hoja de trabajo, para registrar un resultado de cada una (renderProcedures, o el --manual-checks de la CLI). Se genera en Node; el informe del navegador (surea11y.report.js) no la tiene.
Datos técnicos completos (contraído por defecto): una tarjeta resumen (mosaicos por resultado) y una tabla con función de búsqueda, filtrable (por resultado) y paginada de cada ocurrencia individual de todo el análisis; un hallazgo que necesita revisión y tiene tendencia la muestra bajo su resumen («Probable fallo: …»), y la búsqueda la encuentra. Cuando no muestra ninguna ocurrencia, contiene una fila que lo dice: el análisis no registró ninguna, o los filtros las ocultan todas.

Un elemento dentro de un árbol shadow se localiza por los selectores de sus hosts shadow y luego el suyo propio, unidos con >>> : html > body > main > x-card >>> button. Las tarjetas, la tabla de márgenes y la tabla de ocurrencias lo muestran así, igual que SARIF y JUnit.

El informe sigue el esquema de color del lector, y su propio texto cumple WCAG 1.4.3 en ambos: cada color de estado tiene al menos 4,5:1 sobre su chip y su mosaico, y las propias reglas de contraste del motor pasan en el informe renderizado en modo claro y oscuro.

El informe se reorganiza a 320 px CSS (WCAG 1.4.10): la página nunca se desplaza en horizontal. Una tabla más ancha que la ventana se desplaza dentro de su propia caja, una región con el nombre del encabezado de la tabla que recibe el foco del teclado, así que se puede desplazar con las flechas.

La barra de metadatos bajo la cabecera lleva el recuento de reglas, el recuento de ocurrencias, la etiqueta del motor, la versión del esquema, la versión de WCAG a la que apuntó el análisis, el engineOptions.profile que usó (si hubo uno; cada perfil de un análisis de varios, unidos con +, y los que no se ejecutaron) y, junto a él, la ley bajo la que se evalúa el perfil cuando el perfil de un pack nombra una (core 1.16.0, experimental), las etiquetas de reglas opcionales que añadió engineOptions.optInRules (si añadió alguna), las condiciones en que se renderizó la página y el idioma al que se resolvió el análisis. Las condiciones son el viewport (con la relación de píxeles del dispositivo cuando no es 1) y el esquema de color, y las fuentes web cuando aún se estaban cargando; un análisis sin diseño, en jsdom, lo indica en su lugar. Un hallazgo que depende del diseño puede aparecer y desaparecer con el ancho del viewport, así que el chip indica qué ancho describe el informe. El mecanismo de reserva de idioma es por cadena de texto e invisible en el propio texto, así que un informe solicitado en un idioma que el motor no soporta se lee como uno en inglés normal; el chip nombra el idioma solicitado junto al resuelto cuando ambos difieren. Ver Locales.

Toda la página está escrita en el idioma al que se resolvió el análisis: encabezados, columnas de tabla, nombres de resultados y gravedades, el titular, el paginador y el formato de fecha. <html lang> nombra ese idioma. Los códigos de resultado de los filtros de ocurrencias (fail, cantTell, …) se mantienen tal cual, porque son los valores que un lector busca en el resultado JSON.

Un caso conserva las etiquetas en inglés: un análisis en un idioma que el motor no incluye, ejecutado con un diccionario engineOptions.messages propio. Ese diccionario no forma parte del resultado, así que el informe no puede leer etiquetas de él; sus hallazgos se marcan entonces con su propio idioma (lang="nl", por ejemplo), para que un lector de pantalla los lea con la voz adecuada.

Un resultado compacto (engineOptions.output.detail: 'findings', ver Esquema de salida) se lee como el resultado completo que representa, así que se informa igual.

Uso como biblioteca

const { renderHtmlReport } = require('@surea11y/core/report');
const { runDomRulesInPage } = require('@surea11y/core');
 
const result = runDomRulesInPage(url, null, {}, null);
const html = renderHtmlReport(result, { title: 'My scan report' });
 
require('fs').writeFileSync('report.html', html);

renderHtmlReport(result, options) devuelve una cadena y nunca toca el sistema de archivos por sí misma (el flag --html de la CLI es el que escribe). La página se fecha con el timestamp del resultado (se establece con engineOptions.timestamp), mostrado en UTC, así que el mismo resultado siempre genera la misma página; un resultado sin él se fecha con el momento en que se genera. options.title es opcional (por defecto, el título propio del idioma del informe: "Informe de análisis de surea11y" en español). options.packs es la lista de packs que ejecutó el análisis (engineOptions.packs), cuando ejecutó alguno: en Node el informe añade los pasos de «Cómo comprobarlo» a los hallazgos sin decidir que llegan sin ellos, siempre los de una regla de core y los de la regla base de una variante, y los pasos propios de una regla de un pack (su meta.review, en inglés, o como los traduzcan los diccionarios de su pack) solo cuando recibe los packs (ver Packs). En el navegador (surea11y.report.js) muestra los pasos que el resultado ya lleva. Con los packs, «Lo que queda para una persona» sigue también el estándar de un pack cuando el análisis ejecutó su perfil. options.manualChecks: false deja fuera esa sección.

Alcance

Esto es un informe de un solo análisis: una instantánea puntual, no un panel que siga resultados a lo largo de muchos análisis en el tiempo. Seguir resultados a lo largo de muchas ejecuciones es un asunto aparte, más amplio, y no forma parte de esta herramienta: conserva el JSON de cada análisis y compáralo tú mismo, o bien envía SARIF a un panel que ya se encargue del historial (ver Informe SARIF más abajo).