Procedimientos de prueba

Un análisis decide lo que las reglas pueden decidir. El resto de una evaluación le toca a una persona: las preguntas que un análisis deja abiertas (cantTell) y las partes de un criterio que ninguna regla prueba. Desde @surea11y/core 1.15.0, core dice también cómo hacer esa parte: un procedimiento de prueba para cada faceta de cada criterio de WCAG que evalúan sus reglas, y de las buenas prácticas, con los pasos, las herramientas que necesita y qué cumple y qué falla, en inglés, francés, alemán, español y japonés. Es el mismo texto del que sale el «Cómo comprobarlo» de un hallazgo, así que las comprobaciones manuales de un equipo y sus análisis dicen lo mismo.

Úsalos sin ningún análisis, para una auditoría manual; junto a un análisis, para lo que deja a una persona; o para explicar un criterio cuyas reglas no encontraron nada pero no lo cubren entero. Como los pasos de un hallazgo, los procedimientos son una guía, no parte de la identidad de un hallazgo: su redacción puede mejorar en cualquier versión.

Verlos

Estas dos páginas son la propia salida de core para WCAG 2.2 nivel A y AA, regeneradas con cada versión que sigue este sitio, y se abren desde el disco sin cargar nada de otro sitio:

• La referencia: cómo evaluar cada criterio, faceta por faceta, bajo los principios y pautas de WCAG.
• La hoja de trabajo: cada comprobación una vez, con un resultado (Sin comprobar, Superado, No superado, No aplicable) y notas que registrar, guardados en tu navegador y descargables como JSON o CSV.

Ambas páginas se someten a las propias reglas de core, en jsdom y en Chromium, en modo claro y oscuro, con el perfil WCAG 2.2 AA: un enlace para saltar, un nivel de encabezado cada vez, regiones con nombre, listas y fieldsets reales, foco visible, nada solo por el color, un tema de colores forzados respetado, el ancho de un móvil y un diseño imprimible.

Qué es un procedimiento

Un criterio tiene facetas, los objetivos de prueba que comprueba una persona para evaluarlo. Una faceta que decide una regla es full, una de la que las reglas deciden una parte es partial, y una que solo puede juzgar una persona es manual. Una faceta tiene un procedimiento general: los pasos que sigue una persona en una página entera, en un navegador con sus herramientas de desarrollo, un teclado y, cuando importa, un lector de pantalla; luego lo que ve si cumple y si falla, nombrando el criterio que incumple; y las herramientas que necesita además de un navegador:

• Una faceta de tecnología es una prueba que hace una regla sobre un tipo de elemento (un <img> tiene un atributo alt). No tiene procedimiento propio: coveredBy nombra la faceta más amplia cuyo procedimiento la evalúa, para que una lista de comprobación enumere lo que hace una persona, una sola vez.
• Una variante es la pregunta más concreta que hace una regla sobre un elemento: los pasos que muestra su hallazgo sin decidir como howToCheck. Un hallazgo muestra siempre su variante, nunca el texto general, y los dos nunca se contradicen. Cada código de motivo que una regla de core puede informar como cantTell está bajo exactamente una faceta.
• Lo que ningún criterio exige se mantiene aparte, bajo best-practice, para que los procedimientos de un criterio nunca presenten un consejo como un fallo.

Qué criterios tienen procedimientos

Cada criterio que evalúa una regla de core, por completo, en parte o como cantTell, tiene un procedimiento para cada faceta, incluidas las que ninguna regla comprueba, ya que una persona las necesita para terminar lo que empezó el análisis: 36 de los 87 criterios de WCAG 2.2 en los niveles A, AA y AAA y el 4.1.1 (eliminado en la 2.2), con 170 facetas, 56 procedimientos propios y 114 facetas de tecnología cubiertas por uno de ellos. Un criterio así es complete. Los otros 51 criterios, que no evalúa ninguna regla (el 1.2.3 Audiodescripción o medio alternativo, por ejemplo), figuran con sus facetas y sin procedimiento: cómo evaluarlos a mano queda fuera de core. Las buenas prácticas tienen uno para cada una de sus 13 facetas: regiones de referencia, contenido en regiones de referencia, encabezados, marcado de tablas, roles ARIA, orden del foco, teclas de acceso, enlaces para saltar, nombres y etiquetas, zoom, nombres repetidos, ventanas nuevas y descargas, y movimiento reducido.

Leerlos

En Node vienen de @surea11y/core, que lee los diccionarios del disco. El código que se ejecuta en un navegador importa lo mismo de @surea11y/core/procedures, con el sufijo From (proceduresFrom, listProceduresFrom, procedureChecklistFrom, renderProceduresFrom, procedureLanguagesFrom), y pasa los diccionarios que importa como @surea11y/core/procedures/<locale>: no necesita sistema de archivos ni toca ninguna de las reglas.

const { proceduresFor } = require('@surea11y/core');
 
proceduresFor('1.4.12', { locale: 'fr' });
// { standard: 'wcag', id: '1.4.12', title: 'Espacement du texte', level: 'AA', complete: true,
//   rules: ['avoid-inline-spacing', 'text-spacing-content-loss'], facets: [ … ] }

import { proceduresFrom } from '@surea11y/core/procedures';
import en from '@surea11y/core/procedures/en';
import fr from '@surea11y/core/procedures/fr';
 
proceduresFrom({ en, fr }, '1.4.12', { locale: 'fr' });

Cada faceta lleva su label, automation, las rules que la reclaman, sus tools, su procedure ({ steps, passWhen, failWhen }, o null para una faceta de tecnología, con coveredBy) y sus variants, cada una exactamente el howToCheck del hallazgo de esa regla para ese código. Un texto en otro idioma distinto del leído (el título propio de una versión anterior de WCAG, como el «Parsing» de la 2.1 para el 4.1.1, o un texto que le falta a un locale) dice en cuál está, para que una herramienta pueda marcarlo con lang, como pide el 3.1.2 de WCAG. El PROCEDURES.md de core, en GitHub, tiene la estructura completa.

Enumerarlos

const { listProcedures } = require('@surea11y/core');
 
listProcedures();                                         // WCAG 2.2, every level
listProcedures({ version: '2.1', levels: ['A', 'AA'] });  // WCAG 2.1 A and AA
listProcedures({ standard: 'best-practice' });
listProcedures({ levels: ['A', 'AA'], automation: ['manual', 'partial'] }); // what a scan leaves

Los criterios de WCAG son los que tiene la versión, en sus niveles: la 2.0 y la 2.1 enumeran el 4.1.1 como criterio de nivel A titulado «Procesamiento», la 2.2 no. Con varios filtros, una faceta debe cumplir cada uno; el complete de un requisito sigue siendo el suyo.

Una lista de comprobación

procedureChecklist acepta las mismas opciones y da lo que hace una persona para evaluar el estándar, una vez cada cosa: un elemento por procedimiento general, con las facetas de tecnología que también evalúa en covers, y las reglas que hay detrás en rules.

const { procedureChecklist } = require('@surea11y/core');
 
procedureChecklist({ levels: ['A', 'AA'] }).items[0];
// {
//   key: '1.1.1/text-alternative-mechanism',
//   label: 'Non-text content that conveys something has a text alternative',
//   automation: 'partial',
//   wcag: '1.1.1',
//   requirements: ['1.1.1'],
//   covers: ['img-alt-attr-present', 'role-img-text-alternative-present', …],
//   rules: ['img-alt-present', …],
//   tools: [{ id: 'devtools', label: "The browser's developer tools" }],
//   procedure: { steps: ['…'], passWhen: '…', failWhen: '… which fails WCAG 1.1.1.' }
// }

Páginas y hojas de trabajo

renderProcedures convierte lo que dan listProcedures, procedureChecklist o proceduresFor en un documento que una persona lee o completa: una página HTML autocontenida, que se abre desde el disco sin servidor, red, fuentes ni scripts de otro sitio, o Markdown. La misma entrada y las mismas opciones dan siempre la misma página.

const { listProcedures, procedureChecklist, renderProcedures } = require('@surea11y/core');
const fs = require('node:fs');
 
// A reference: how to assess every WCAG 2.2 A and AA criterion.
fs.writeFileSync('wcag-22-aa.html', renderProcedures(listProcedures({ levels: ['A', 'AA'] })));
 
// A worksheet: each check once, with a result and notes to record.
fs.writeFileSync('wcag-22-aa-checklist.html', renderProcedures(procedureChecklist({ levels: ['A', 'AA'] })));
 
// The same in Markdown, for a repository or a wiki.
fs.writeFileSync('wcag-22-aa.md', renderProcedures(listProcedures({ levels: ['A', 'AA'] }), { format: 'markdown' }));

La página de una lista es una referencia del estándar: su título y alcance, qué significan sus resultados (las buenas prácticas no cuentan para ninguna conformidad, el nivel AAA es orientativo), «Antes de empezar», un índice, y cada requisito con sus facetas: qué comprueba cada una, cuánto de ella deciden las reglas, las herramientas, los pasos, qué cumple y qué falla, y las reglas que la prueban.

La página de una lista de comprobación es una hoja de trabajo. Bajo cada elemento una persona registra un resultado y notas; la página cuenta los resultados en un mensaje de estado que anuncia un lector de pantalla, los guarda en el navegador (localStorage, con el estándar, la versión y el título como clave), y los descarga como JSON, con el resultado de cada requisito agregado a partir de sus elementos, o como CSV, que una hoja de cálculo abre con sus tildes. Un requisito falla cuando falla uno de sus elementos, es open cuando uno aún no se ha comprobado, es notApplicable cuando no se aplica ninguno, y se cumple en los demás casos.

{
  "title": "WCAG 2.2: manual checklist",
  "standard": "wcag",
  "version": "2.2",
  "items": [
    {
      "key": "1.1.1/text-alternative-mechanism",
      "requirements": ["1.1.1"],
      "outcome": "fail",
      "notes": "The logo has no alt."
    }
  ],
  "requirements": [{ "id": "1.1.1", "outcome": "fail" }]
}

Las palabras propias de una página están en todos los idiomas que incluye core, y también los procedimientos, las etiquetas de las facetas y los principios, pautas y criterios de WCAG, con los nombres que les da la traducción publicada de WCAG en cada idioma. Lo que está en otro idioma que el de la página se marca con él, para que un lector de pantalla lea cada parte en su idioma. fragment: true da solo el contenido, en un <div class="surea11y-procedures"> con sus encabezados desde h1, para un sitio de documentación que aporta sus propios estilos.

Desde la CLI

@surea11y/cli 1.5.0 escribe las mismas páginas sin código: surea11y procedures sin análisis, y --manual-checks junto a un análisis, para las comprobaciones que deja a una persona.

# How to assess every WCAG 2.2 A and AA criterion, or a worksheet for a manual audit
$ surea11y procedures --wcag-level AA -o wcag-22-aa.html
$ surea11y procedures --wcag-level AA --checklist --title "Audit: example.com" -o audit.html
# The checks a scan leaves to a person, as a worksheet next to its report
$ surea11y scan https://example.com/ --wcag 2.2 --html report.html --manual-checks manual-checks.html

En el informe HTML

El informe HTML tiene una sección «Lo que queda para una persona»: cada requisito del estándar analizado con una comprobación que ninguna regla decide por completo, su resultado en el análisis al lado y, contraídas debajo, esas comprobaciones con sus pasos. Un requisito cuyas reglas se superan todas solo se cumple cuando también se superan sus comprobaciones, y el informe lo dice. renderHtmlReport(result, { manualChecks: false }) deja fuera la sección.

Usos

Una auditoría manual, sin análisis. Quien audita completa la hoja de trabajo del estándar con el que se hace la auditoría, registra cada resultado y nota, y descarga el JSON para el informe:

const checklist = procedureChecklist({ version: '2.2', levels: ['A', 'AA'] });
fs.writeFileSync('audit-worksheet.html', renderProcedures(checklist, { title: 'Accessibility audit: example.com' }));

Un adjunto de una ejecución de pruebas. Una prueba de Playwright que analiza una página puede adjuntar las comprobaciones que sus reglas no deciden, para que queden junto al análisis en el informe de pruebas:

test('home page', async ({ page }, testInfo) => {
  // ... scan the page ...
  const left = procedureChecklist({ levels: ['A', 'AA'], automation: ['manual', 'partial'] });
  await testInfo.attach('manual-checks.html', {
    body: renderProcedures(left, { record: false }),
    contentType: 'text/html'
  });
});

Una sesión con una persona usuaria de lector de pantalla. Solo lo que necesita un lector de pantalla, para una sesión con una persona que lo usa a diario:

const sr = listProcedures({ levels: ['A', 'AA'], tools: 'screen-reader' });
fs.writeFileSync('screen-reader-session.html', renderProcedures(sr, { title: 'Screen reader session' }));

Documentación. Un archivo Markdown por estándar en un sitio de documentación o un repositorio, regenerado cuando se actualiza core, para que un equipo lea los mismos procedimientos que usan sus herramientas. Un criterio, donde hace falta: una herramienta que muestra un hallazgo puede mostrar cómo evaluar todo su criterio, con renderProcedures(proceduresFor('1.4.12', { locale: 'de' }), { fragment: true }).

El estándar de un pack

El estándar de un pack puede decir cómo evalúa una persona sus propios requisitos, y cada función anterior lo lee si recibe los packs: con su propia numeración y grupos, en su propio idioma cuando declara uno. Un requisito que reformula un criterio de WCAG toma los procedimientos de ese criterio, leídos como el requisito («which fails EN 301 549 9.1.4.3»). Desde core 1.16.0, una faceta también enumera las reglas de core que el mapeo del estándar envía a lo que evalúa (mappedRules, también en el mappedRules de un elemento de la lista de comprobación), así que un requisito o una prueba que solo comprueban reglas de core no parece sin comprobar.

const en301549 = require('@surea11y/pack-en301549');
 
proceduresFor('9.1.4.3', { packs: [en301549], standard: 'en301549', version: 'V4.1.1', locale: 'fr' });
relatedRequirements('1.4.3', { packs: [en301549] });
// [{ standard: 'EN 301 549', id: '9.1.4.3', version: 'V4.1.1', relation: 'restates', … }]
 
const options = { packs: [en301549], standard: 'en301549', version: 'V4.1.1', locale: 'fr' };
fs.writeFileSync('en-301-549.html', renderProcedures(procedureChecklist(options), { packs: [en301549] }));

El pack de EN 301 549 1.2.0 da procedimientos para cada cláusula del capítulo 9 cuyo criterio evalúa una regla de core, en cinco idiomas, y el pack de WAI-ARIA da una lista de comprobación para cada uno de sus requisitos, con los roles, estados y valores válidos enumerados por completo. Un pack que no da procedimientos no cambia nada: los de WCAG son los mismos con él que sin él.