Informe EARL

@surea11y/core/earl convierte los resultados de un análisis en EARL 1.0 en JSON-LD: el vocabulario que publica el W3C para declarar "esta herramienta probó esto y obtuvo este resultado", y el formato que el grupo comunitario ACT Rules acepta como informe de implementación.

const { renderEarlReport } = require('@surea11y/core/earl');
 
const report = renderEarlReport(result, {
  assertor: { name: 'surea11y', version: '1.7.0' },
  mode: 'earl:automatic'
});
 
fs.writeFileSync('earl.jsonld', JSON.stringify(report, null, 2));

Para qué sirve

Dos audiencias, y ambas quieren el mismo documento por razones distintas.

Un informe de implementación le dice al grupo comunitario ACT Rules cómo se comporta este motor frente a sus casos de prueba, que es lo que permite que un motor aparezca listado junto a las demás implementaciones. Estar listado no es un aval y el W3C no verifica los datos: la formulación correcta es "listado como implementación ACT", nunca "certificado por el W3C". El informe propio de este motor se publica en https://surea11y.github.io/act-report/act-report.jsonld y se regenera con scripts/act-report.js.

Un consumidor obtiene un formato de intercambio. EARL es lo que lee una herramienta de accesibilidad cuando tiene que combinar resultados de más de una fuente (un análisis automatizado y una auditoría manual, por ejemplo, o varios motores), porque cada aserción indica quién la hizo y cómo. Eso tiene valor aunque nunca se envíe a ningún sitio.

En qué se diferencia de los demás informes

El informe SARIF y el informe HTML llevan solo las violaciones: informan de las ocurrencias fail y cantTell y descartan todo lo demás. EARL es lo contrario. Cada regla que se ejecutó se convierte en una aserción, incluidas pass e inapplicable, porque un informe de implementación es una afirmación sobre lo que decidió el motor en todos los casos. Una regla que no dijo nada porque no encontró nada aplicable es evidencia, no ruido: es lo que permite distinguir "este motor comprobó y no encontró nada que comprobar" de "este motor no implementa esa regla en absoluto".

Forma

El grafo se agrupa por sujeto en lugar de ser una lista plana de aserciones:

{
  "@context": "https://www.w3.org/WAI/content-assets/wcag-act-rules/earl-context.json",
  "@graph": [
    {
      "@type": "TestSubject",
      "source": "https://example.test/",
      "assertions": [
        {
          "@type": "Assertion",
          "test": { "title": "img-alt-present", "isPartOf": ["WCAG2:non-text-content"] },
          "result": { "outcome": "earl:failed" },
          "assertedBy": {
            "@type": "Assertor",
            "name": "surea11y",
            "release": { "@type": "Version", "revision": "1.7.0" }
          },
          "mode": "earl:automatic"
        }
      ]
    }
  ]
}

• source es la URL analizada, o bien about:blank cuando un resultado no lleva ninguna.
• test.title es el ID de regla propio del motor. En términos ACT, una regla es el procedimiento que ejecutó la implementación, que es exactamente lo que nombra un ID de regla.
• test.isPartOf enumera los Criterios de Éxito a los que se asocia esa regla, como WCAG2:<criterion-id>. Se omite por completo para una regla que no reclama ningún criterio: aria-allowed-role es la única regla automática del motor en esa situación, y afirmar una lista vacía se leería como "no encontramos a qué se asocia" en lugar de "deliberadamente no se asocia a ninguno".
• assertedBy y mode aparecen solo cuando se proporcionan.

Los ids de criterio se derivan del propio título del criterio (Non-text Content → non-text-content). normativeMappings también lleva referencias a documentos Understanding y estándares que no son WCAG, que comparten standard: "WCAG" y un requirement con el criterio real; un Criterio de Éxito es la entrada que declara un nivel de conformidad y no reclama ningún otro tipo de documento, y solo esas entradas se leen.

Resultados

earl:untested no tiene contraparte: una regla que no se ejecutó no produce ningún resultado sobre el cual hacer una aserción, así que no aporta ninguna aserción en lugar de aportar una de "no probada".

cantTell no le resta crédito de conformidad. Las propias reglas de consistencia de ACT permiten que una implementación automatizada indique "no se puede determinar" en algunos ejemplos (aunque no en todos) y aun así cuente como consistente. Lo que una implementación parcialmente consistente no puede hacer es producir un falso positivo: fallar un ejemplo que la regla dice que debería pasar o que es inaplicable. Esa es la condición que vale la pena vigilar, y es una propiedad de las reglas, no de este informe. Según la última ejecución completa, el motor produce cero falsos positivos entre los 798 ejemplos ACT que cubren sus 58 reglas asociadas. Ver ACT_RULE_MAPPING.md, y volver a ejecutar scripts/act-testcase-check.js para la cifra actual en lugar de confiar en esta indefinidamente.

Varios resultados, un solo informe

renderEarlReport acepta un array con la misma facilidad que un solo resultado, porque un informe que cubre muchas páginas es el caso normal:

renderEarlReport([homeResult, checkoutResult, searchResult], { assertor });

Los resultados que comparten una URL se fusionan en un solo sujeto: quien llama y analiza la misma página con distintas engineOptions sigue describiendo un único recurso, y el contexto no tiene forma de expresar dos sujetos con la misma fuente. Cuando dos resultados hacen una aserción sobre la misma regla para la misma URL, gana el último.

La salida es determinista: los sujetos se ordenan por fuente, las aserciones por ID de regla, y las mismas entradas producen una salida idéntica byte a byte sin importar el orden. Eso es lo que hace útil una comparación entre dos versiones del motor.

Opciones

Ver también

• Esquema de salida: el resultado que este informe lee
• ACT_RULE_MAPPING.md: a qué reglas ACT corresponden las reglas del motor
• API_STABILITY.md: qué está cubierto por el versionado semántico