Esquema de salida

Esta es la estructura exacta del objeto que devuelven runDomRulesInPage(...) / runa11yCoreInPage(...) (consulta INTEGRATION.md para saber cuál llamar). Todos los ejemplos de esta página son salida real del motor actual (schemaVersion: "1.0.0"), no están escritos a mano. runa11yCoreAcrossFrames devuelve una estructura distinta y recursiva que envuelve esta. Ver Resultado entre frames más abajo.

Resultado de nivel superior

{
  engine: {
    tag: string,
    version: string,       // the @surea11y/core release that produced the result
    schemaVersion: string,
    locale: { requested: string, resolved: string, reason: string },
    wcagVersion: "2.0" | "2.1" | "2.2",
    wcagLevel?: "A" | "AA" | "AAA",
    profile?: string,      // "wcag20-a" … "wcag22-aaa" (wcag<version>-<level>), the deprecated "en301549-v4.1.1", "en301549-v3.2.1" and "section508", or a pack's own
    profiles?: string[],   // a scan of several profiles only: the profiles that ran
    profilesNotRun?: { profile: string, reason: string }[],  // a scan of several profiles only
    mappings?: string[],   // e.g. ["en301549"] or ["en301549:V3.2.1"]
    profileExcludes?: { rules: string[], criteria: string[] },
    law?: { id: string, name: string, jurisdiction: string, lang: string },  // experimental
    optInRules?: string[],
    outputDetail?: "findings",
    packs?: string[],      // name@version
    environment: {
      layout: boolean,
      viewport?: { width: number, height: number },  // CSS px
      devicePixelRatio?: number,
      colorScheme?: "light" | "dark",
      forcedColors?: "active" | "none",
      forcedColorsCss?: true,          // under forced colors, when the page's own CSS reacts to them
      fonts?: "loaded" | "loading",
      images?: "loaded" | "loading",
      animationsSettled?: number,
      contentVisibilitySkipped?: number, // elements whose content-visibility: auto content was skipped
      internalsHook?: "early" | "late",  // only where the page runs the internals hook
      listenerHook?: "early" | "late",   // only where the page runs the listener hook
      liveRegionHook?: "early" | "late"  // only where the page runs the live-region hook
    }
  },
  url: string | null,
  title: string | null,
  timestamp: string | null,
  perfStats: object | null,
  contextSelector: string | string[] | null,
  contextMatch: { elementCount: number, unmatchedSelectors: string[] } | null,
  checksResults: CheckResult[],
  rulesResults: CompositeResult[],
  standards?: Array<{ key: string, standard: string, titleLang?: string, note?: string }>,
  overriddenBuiltinIds: string[],
  skippedCustomRules: Array<{ id: string | null, reason: string, excluded?: true }>,
  skippedPacks?: Array<{ name: string | null, reason: string }>,
  profiles?: { [profile: string]: { wcagVersion, wcagLevel?, standards, rulesResults } }  // a scan of several profiles only
}

Varios perfiles

Con engineOptions.profile como una lista de dos o más (['wcag22-aa', 'wai-aria-1.2'], ver Opciones del motor), cada perfil juzga la página como lo haría un análisis solo de él, y el resultado se lee como un análisis de un solo perfil con las reglas de todos. Un único nombre, o una lista de uno, da exactamente el resultado de siempre, sin ninguno de los campos siguientes. Core 1.15.0 y posteriores.

• checksResults: cada regla una vez. verdicts es el resultado de cada perfil para ella ({ 'wcag22-aa': 'cantTell', 'wai-aria-1.2': 'fail' }), por perfil, para los perfiles que la ejecutaron; outcome es el peor de ellos: fail, luego cantTell, luego pass, luego notApplicable. Un generador de informes que lee outcome cuenta el análisis como ese único perfil. checkOutcome es el resultado propio de la regla, antes de que ningún estándar juzgue sus hallazgos por código de motivo: lo que indican sus criterios de WCAG, ya que el fallo de un estándar en un hallazgo por el que WCAG solo pregunta no es un fallo de WCAG.
• Cada ocurrencia figura una vez, con verdicts: lo que hace de ella cada perfil. Es su nivel, salvo que los resultados agregados de un estándar juzguen la regla por los códigos de motivo de sus hallazgos: entonces es lo que estos hacen de ella (un cantTell de WCAG del que un estándar está seguro es fail allí), o notApplicable donde el estándar no lo cuenta. Un hallazgo que falla en un perfil y es una pregunta para otro dice ambas cosas. occurrenceOutcome es el peor de ellos cuando difiere del de la comprobación.
• rulesResults: los resultados agregados de todos los perfiles, cada uno una vez, con profiles, los perfiles que lo dan. Uno que dos perfiles dan con resultados distintos (dos versiones de WCAG, por ejemplo) es el peor de ellos.
• profiles: por cada perfil que se ejecutó, { wcagVersion, wcagLevel, standards, rulesResults } (wcagLevel solo para un perfil que apunta a un nivel de WCAG), siendo rulesResults el resultado de cada uno de sus resultados agregados por id: lo que habría informado un análisis solo de ese perfil. Un perfil que nombra una ley también tiene law, como engine.law (experimental).
• severity: la más alta que le da a la regla cualquier perfil que la hace fallar o pregunta por ella, sea cual sea el orden en que se enumeran los perfiles.

Resultado entre frames (runa11yCoreAcrossFrames)

runa11yCoreAcrossFrames (consulta INTEGRATION.md) devuelve una estructura distinta y recursiva en lugar de un resultado de nivel superior simple:

{
  topFrame: <the normal top-level result shape above>,
  frames: Array<
    | { url: string | null, selector: string | null, title: string | null,
        topFrame: <top-level result>, frames: [...same shape, recursively] }
    | { url: string | null, selector: string | null, title: string | null, error: string }
  >
}

• topFrame es exactamente la estructura del resultado de nivel superior, para el frame en el que se llamó a la función.
• frames tiene una entrada por cada <iframe>/<frame> hijo directo dentro del ámbito analizado (incluidos los shadow roots abiertos, y el propio ámbito cuando es un frame), salvo un frame que la página no muestra y un frame que excludeSelectors excluye, que quedan fuera con todo su documento. Cada entrada nombra su elemento frame: selector es un selector CSS del <iframe>/<frame> en el documento del padre, y title es el atributo title del elemento, o null, para que se puedan distinguir frames que cargan el mismo documento. url es el documento que muestra el frame o, para un frame que aún no ha navegado, su src. Un hijo alcanzable (uno que llamó a a11yCoreEnableFrameResponder()) aporta su propio { url, topFrame, frames } completo: incluyendo sus propios frames anidados, de forma recursiva, ya que un nieto anidado más profundo solo es alcanzable a través de su padre inmediato. Un hijo inalcanzable (el caso común para la mayoría de los embebidos de terceros, sin responder cooperante o que agotó el tiempo de espera) aporta { url, error } en su lugar, y no aborta el resto del análisis.
• Esto es un árbol, no una lista plana: una diferencia deliberada respecto a @surea11y/playwright's .frames(true), que sí puede aplanar porque page.frames() de Playwright ya entrega todos los frames sin importar la profundidad de anidamiento; un relé por postMessage no tiene esa visión global, así que el anidamiento se expresa de forma estructural en su lugar.
• Los generadores de informes aceptan el árbol tal cual. renderHtmlReport, renderSarifReport, renderJunitReport, buildBaselineEntries, matchBaseline y renderEarlReport informan de todos sus frames: cada frame que respondió, con sus propios hallazgos, ubicados en su propio documento, y cada frame que no respondió, como no analizado, para que un hueco en la cobertura no se lea como un aprobado. Un frame se nombra por su ruta, los selector de los elementos frame que llevan hasta él desde la página, del más externo al más interno (#checkout → iframe:nth-of-type(2)). Lanzan un TypeError ante cualquier cosa que no sea ni un resultado de análisis ni un resultado entre frames (un array, null o undefined de un análisis que falló), en lugar de presentarlo como un análisis que no encontró nada.
• También aceptan el análisis de frames de una integración. El .frames(true) de las integraciones de navegador devuelve { topFrame, frames } con cada frame como un resultado simple (o { url, error }) en lugar de una entrada anidada; los generadores de informes, getMargins y flattenCrossFrameResult leen cada uno de esos frames como analizado, nombrado por la ruta ['iframe'], ya que no lleva selector.
• flattenCrossFrameResult(result), de @surea11y/core, enumera los frames tal como los leen los generadores de informes: [{ frame: { path, title, url }, result }], o error en lugar de result para un frame que no respondió, primero la página y cada frame antes de los frames que contiene. El path de la página es []. Un resultado de análisis simple es una sola entrada.

Un resultado de comprobación (checksResults[i])

{
  ruleId: string,
  outcome: "pass" | "fail" | "cantTell" | "notApplicable",
  outcomeNormalized: "pass" | "fail" | "cantTell" | "inapplicable",
  severity: "minor" | "moderate" | "serious" | "critical",
  ruleSeverity?: "minor" | "moderate" | "serious" | "critical", // the rule's own, when a profile gave it another
  verdicts?: { [profile: string]: string },  // a scan of several profiles only: each profile's outcome
  checkOutcome?: string,   // a scan of several profiles only: the rule's own outcome, which its WCAG criteria read
  policyOutcome?: "pass" | "fail" | "cantTell" | "notApplicable", // what the rule found, when the policy made it cantTell
  confidence: "high" | "medium" | "low",
  type: "automatic" | "manual",
  occurrences: Occurrence[],
  title: string,
  description: string,
  i18n: { titleKey: string, descriptionKey: string, variantOfTitleKey?: string } | null,
  meta: {
    ruleId: string,
    ruleInterfaceVersion: string,
    ruleVersion: string,
    normative: boolean,
    atomic: boolean,
    deprecated: boolean,
    deprecation: object | null,
    category: "perceivable" | "operable" | "understandable" | "robust" | null,
    helpUrl: string,       // where to read how to fix it; "" when there is none
    tags: string[],        // the rule's tags, its own and the engine's
    normativeMappings: Array<{ standard: string, version: string, requirement: string, title: string,
      conformanceLevel?: string, wcagSc?: string[], url?: string, understandingUrl?: string }>,
    standard: string | null,
    applicability: string,
    expectation: string,
    references: string[],
    requirements: object | null,
    mappings: object | null
  },
  engineOptions: object,   // the resolved engineOptions this rule actually ran under
  schemaVersion: string,
  rollupIds: string[],     // the rulesResults entries that group this rule in this run; [] if none
  variantOf?: string,      // a pack's variant only: the id of the rule it runs at other settings; i18n.variantOfTitleKey is that rule's titleKey
  data?: object,           // page-level data a rule reports whatever its outcome; see below
  margin?: {               // the closest a measurement came to its threshold while meeting it; see below
    measure: string,       // "contrast-ratio" | "overflow-px" | "target-size-px" | ... (open set)
    unit: "px" | "ratio",  // open set
    limit: "min" | "max",
    threshold: number,
    value: number,
    headroom: number,      // >= 0
    measuredCount: number,
    selector?: string,
    shadowHostSelectors?: string[],  // as on an occurrence
    structuralPath?: number[],
    context?: object       // rule-specific; not a stable contract
  },
  wcagVersionScope?: {     // present only when the target WCAG version changed this outcome
    target: "2.0" | "2.1" | "2.2",
    removedSc: string[],
    coercedFrom: "fail",
    by?: "errata"         // 2.0 or 2.1: their errata count the criterion as always satisfied
  },
  ancestorWalkLimit?: {    // present only when a failed element is nested deeper than the engine walks up from it
    limit: number,         // 10000: the ancestors read, the element included
    occurrences: number,   // the fail-tier occurrences made cantTell-tier
    coercedFrom?: "fail"   // no fail-tier occurrence was left, so the outcome went from fail to cantTell
  },
  error?: string           // present when the rule did not complete, or the engine noted a change — see below
}

Notas:

• outcome frente a outcomeNormalized: idénticos, salvo que notApplicable se convierte en "inapplicable" en outcomeNormalized. Se ofrecen ambos para que puedas ajustarte a tu propio vocabulario o al vocabulario interno del motor.
• Con la política predeterminada a11y, las reglas type: "manual" devuelven cantTell en lugar de fail. Si la lógica propia de una regla manual hubiera dicho fail, el motor la fuerza a cantTell y añade una nota explicativa a error: esto se aplica de forma centralizada (policy.coerceManualFailToCantTell, activado por defecto bajo el contrato de política a11y; consulta POLICY.md), no es algo que cada regla tenga que recordar por su cuenta. Con esta política, fail está reservado únicamente para hallazgos deterministas de type: "automatic".
• meta.normativeMappings es cómo un resultado de comprobación se vincula de vuelta a un criterio de éxito de WCAG. Una lista vacía significa que la regla no tiene un mapeo formal en este resultado. Eso no indica si la regla es automática o manual: para eso, lee type (aria-allowed-role, por ejemplo, es automática y no tiene mapeo a WCAG). Consulta Conformidad para ver cómo se agregan. La lista no es solo de WCAG. Cuando el análisis pide otro estándar (engineOptions.mappings, o el perfil de un estándar), cada criterio de WCAG va seguido del requisito correspondiente de ese estándar, como la cláusula de EN 301 549 que lo reformula ({ standard: "EN 301 549", version: "V3.2.1" | "V4.1.1", requirement: "9.1.1.1", title, wcagSc: ["1.1.1"] }, una entrada por cada versión que incluye el criterio); y una regla también puede citar los documentos Understanding de WCAG (type: "Understanding"). Filtra por standard (y por la ausencia de type) antes de leer requirement como un criterio de éxito. La entrada de WCAG de un compuesto va siempre primero. Ver EN 301 549.
• rollupIds enumera los compuestos de rulesResults que agrupan esta regla en esta ejecución, incluidos los que se informan porque la selección nombró la regla por sí sola. Una lista vacía significa que los hallazgos de la regla no aparecen en ningún resultado agregado, así que quien lea solo rulesResults nunca los ve; heading-order, por ejemplo, no pertenece a ningún resultado agregado de WCAG.
• wcagVersionScope: presente solo cuando la versión de WCAG objetivo de la ejecución convirtió el fail de esta regla en un cantTell: hoy eso significa una regla mapeada al SC 4.1.1 Parsing (duplicate-id): bajo 2.2, que eliminó ese criterio, y bajo 2.0 y 2.1, cuyas erratas de 2023 lo consideran siempre satisfecho para HTML y XML (by: "errata"). Un perfil cuyo estándar conserva el texto de 4.1.1 (en301549-v3.2.1, o el perfil de un pack con keepsParsing) no se convierte. removedSc enumera los criterios afectados, target es la versión de la ejecución, y coercedFrom es el outcome que la propia regla devolvió. Las occurrences son las propias de la regla, sin cambios: no se descartó nada, solo cambió el veredicto de conformidad. Ausente en cualquier otro resultado, y nunca se indica a través de error: no salió nada mal. Consulta Filtrado por versión de WCAG.
• ancestorWalkLimit (core 1.16.0 y posteriores): el motor lee todos los ancestros de un elemento, a través de shadow roots y slots, para saber si algo a su alrededor lo oculta, hasta 10.000 de ellos: mucho más hondo de lo que renderiza ningún navegador. Un fallo en un elemento anidado a más profundidad no es seguro, ya que un elemento que el motor no leyó puede ocultarlo, así que su ocurrencia pasa al nivel cantTell, conservando su código de motivo, con uncertainty.code: "not-computable" y pasos propios del motor que preguntan si el elemento está expuesto. El veredicto de la regla sobre cada uno de los demás elementos se mantiene, así que el resultado sigue siendo fail mientras quede una ocurrencia de nivel fail, y pasa a cantTell en caso contrario (coercedFrom: "fail"). Como wcagVersionScope, no se indica a través de error: la regla terminó.
• data: presente solo en una regla que informa algo sobre la página entera, sea cual sea su resultado. Ninguna regla de core lo hace hoy. Como data.details en una ocurrencia, no es un contrato estable.
• margin: presente solo en una regla que declara uno en el catálogo (getChecksCatalog()[i].margin, { measure, unit, limit, band? }), cuando al menos un elemento alcanzó el umbral de la regla y, si la declaración tiene un band, quedó dentro de él. band.relative es una fracción del umbral: contrast-minimum, contrast-enhanced y link-in-text-block, con 0.1, solo indican un margen para una razón a menos del 10 % de la que necesitaba (de 4,5 a 4,95 frente a 4,5:1, de 3 a 3,3 frente a 3:1). band.absolute es una cantidad en unit: target-size-minimum, con 6, solo indica un objetivo de hasta 30 px, y text-spacing-content-loss, con 8, una línea solo desde 6 px dentro del borde de su caja. Un texto a 21:1 o un botón de 48 px no está cerca de nada, y ningún margen lo dice. Indica el elemento que más se acercó al umbral cumpliéndolo, de modo que un pass a 4,52:1 frente a 4,5:1, o a 0,4 px de cortar el texto, se distingue de uno holgado. Va junto al resultado y no es un hallazgo: nunca añade, quita ni cambia una ocurrencia, y las líneas base, SARIF, JUnit y EARL lo ignoran. También se indica en resultados fail y cantTell cuando algunos elementos pasaron. limit es min cuando el valor debe alcanzar el umbral (contraste, tamaño) y max cuando debe quedar por debajo (desbordamiento); headroom es cuánto margen queda, en unit, es decir, value - threshold para min y threshold - value para max, nunca negativo. threshold es el umbral con el que se juzgó ese elemento, que puede variar entre elementos (3:1 para texto grande). Los píxeles se dan con un decimal: los píxeles CSS y umbrales como la mitad de una fuente de 15px son fraccionarios, y una interfaz los redondea para las personas. Una razón no se redondea, ya que WCAG no redondea el contraste. En caso de empate gana el primer elemento en el orden del documento, así que una página da siempre el mismo margen. measure y unit son conjuntos abiertos que pueden crecer en una versión menor; context es específico de cada regla y, como data.details, no es un contrato estable. getMargins(result) devuelve todos los márgenes de un resultado como [{ ruleId, ...margin }], ordenados por ruleId; de un resultado entre frames, los de todos los frames, los de un frame hijo con frame, la ruta hasta él.
• error: presente cuando la regla no terminó, o cuando el motor cambió o ignoró parte de lo que devolvió la regla. Una regla que lanzó una excepción (o devolvió algo que no es un resultado) siempre aparece como outcome: "cantTell" con occurrences: [] y error establecido al mensaje de la excepción, así que cantTell sin ocurrencias y con un error es la forma de reconocer una regla que no terminó; el motor nunca deja que una regla rota haga fallar todo el análisis. En los demás casos, error contiene las notas del motor, unidas con | después de cualquier error que la propia regla devolvió: la coerción de fail manual descrita arriba, un outcome o un severity fuera de su conjunto, un type distinto del de su meta, ocurrencias que no son objetos (se dejan fuera), un policyOutcome o un ruleSeverity que devolvió la regla (no se toman: el motor establece ambos), y un uncertainty.code fuera del conjunto cerrado. Esos resultados conservan sus ocurrencias: la regla terminó. (Antes de la 1.16.0, también se anotaba aquí un fail antes de cuyos elementos se detenía el recorrido de ancestros de 200 pasos; consulta ancestorWalkLimit más arriba.)
• policyOutcome: presente cuando el allowedOutcomes de la política no permite el resultado que encontró la regla. El resultado es entonces cantTell, con el resultado propio de la regla aquí y sin error, para que los generadores de informes no lo lean como una regla que no terminó.
• engineOptions en cada resultado es el objeto de opciones resuelto (después de aplicar los valores predeterminados de locale/contrast), no literalmente lo que pasaste: útil para confirmar qué vio realmente una regla dada, especialmente el locale resuelto y contrast.mode/contrast.rootCanvasFallback. contrast.rootCanvasFallback es blanco cuando quien llama no dio ninguno, y contrast.rootCanvasFallbackSet indica cuál: true para un color que dio quien llama, false para el predeterminado. Omite messages, los diccionarios con los que tradujo la ejecución (un archivo de locale aparte en el paquete para navegador, o tus propias cadenas): son datos, no un ajuste, y una copia en cada resultado hacía que un análisis ocupara decenas de megabytes. engine.locale indica qué diccionario se usó. Otras tres opciones se reflejan tal como las vieron las reglas, para que el resultado siga siendo datos simples que JSON.stringify y structuredClone (postMessage) puedan transportar: probes como la copia limitada que leen las reglas, customRules como [{ id }], una entrada por cada regla personalizada con id, sin sus funciones, y styleSheetTexts como [{ href }], una entrada por cada hoja dada, sin su texto, ya que el CSS de una página repetido en cada resultado se multiplicaba por el número de reglas.

Una ocurrencia (occurrences[i])

Un fail siempre tiene al menos una: un fail de una regla personalizada que no nombra ningún elemento recibe una en el elemento del documento (selector: "html", código de motivo FAIL_WITHOUT_OCCURRENCE). Normalmente presente solo cuando outcome es fail o cantTell: un resultado pass tiene occurrences: [], ya que este motor no enumera los elementos que pasó, solo los que señaló. Las reglas de contraste son la excepción: su pass lleva una ocurrencia que describe el análisis (cuánto texto era elegible y calculable), con un selector vacío, para que un pass sin texto se distinga de uno sobre una página llena de texto.

Un notApplicable de core no nombra ninguna occurrence. Cuando las reglas de contraste son notApplicable porque ningún texto tenía un fondo calculable, dicen cuánto texto examinaron en el propio data.details del resultado (eligibleTextCount, computableTextCount), y contrast-computable informa como cantTell de cada texto que no pudo medir: la diferencia entre «se comprobó, nada que señalar» y «no se pudo comprobar» es algo que este motor indica en lugar de ocultar. Una regla de un pack o personalizada que no tuvo nada que juzgar todavía puede adjuntar una única occurrence explicando por qué; una occurrence así describe el análisis, no un elemento, así que su selector está vacío. No interpretes occurrences.length como un recuento de violaciones sin comprobar antes outcome.

{
  selector: string,
  html: string,
  structuralPath: number[] | null,
  shadowHostSelectors?: string[],
  summary: string,
  hint: string,
  i18n: { summaryKey: string, hintKey: string, params: object } | null,
  occurrenceOutcome?: "fail" | "cantTell",   // present when the rule graded its findings into tiers
  verdicts?: { [profile: string]: string },  // a scan of several profiles only
  uncertainty?: {          // present only on a cantTell-tier occurrence
    code: "not-computable" | "runtime-dependent" | "spec-only"
        | "equivalence-unknown" | "judgement-required" | "out-of-scope",
    needed?: string,       // what would settle the question
    evidence?: object      // what the rule did establish, rule-specific
  },
  lean?: {                 // present only on a cantTell-tier occurrence, and only with evidence
    toward: "pass" | "fail",
    why: string,           // localized: what in the page points that way
    signals: { signal: string, value: string | number | boolean | null }[],
    caution?: string,      // localized: what could make it wrong
    measured?: { agreed: number, cases: number, corpus?: string, coreVersion?: string },
    i18n?: { whyKey?: string, cautionKey?: string, params?: object }
  },
  howToCheck?: {           // present only on a cantTell-tier occurrence, when the rule says
    steps: string[],       // localized: what a person does, in order
    passWhen: string,      // localized: what they see if it passes
    failWhen: string       // localized: what they see if it fails
  },
  data?: {               // absent on manual-review's page-level finding
    visibilityFilter?: { eligible?: boolean, targetSet: string, accEligible: boolean | null, reasons: string[] },
    details?: object   // rule-specific, non-normative — see below
  }
}

Códigos de incertidumbre

Un cantTell dice que el motor no decidió. uncertainty dice por qué, a partir de un vocabulario cerrado, para que un consumidor pueda ramificar según el motivo en lugar de analizar una cadena de resumen. Está presente solo en una occurrence de nivel cantTell: una de nivel fail estaría afirmando que la regla decidió y no decidió a la vez, así que el motor la omite. Una incertidumbre cuyo code no es uno de los códigos de abajo también se deja fuera, y el error de la regla nombra el código.

needed indica, en una frase, qué resolvería la cuestión: lo que un revisor tiene que ir a comprobar. evidence lleva lo que la regla sí llegó a establecer, para que el revisor parta del trabajo del motor en lugar de repetirlo; su estructura es específica de cada regla y, como data.details, no es un contrato estable. En cuanto a code: pueden añadirse códigos nuevos en una versión menor, pero uno existente no cambia de significado, así que ramifica según los códigos que conoces y trata uno no reconocido como «necesita revisión» en lugar de como un error.

Toda regla automática que puede devolver cantTell lleva esto, y una prueba mantiene esa línea para que no pueda llegar una nueva sin ello. El código out-of-scope lo adjunta el motor, no una regla, en las mismas occurrences que producen un wcagVersionScope a nivel de resultado. Las reglas manuales no lo llevan: judgement-required ya es lo que significa type: "manual", así que repetirlo por occurrence no diría nada que el resultado no diga ya.

Tendencias

Un cantTell puede apuntar igualmente hacia un lado. lean indica hacia cuál, cuando la página da indicios de ello: toward es la respuesta que esos indicios hacen probable, why dice cuáles son, y signals enumera los hechos que leyó la regla, cada uno con un nombre en kebab-case y un valor simple, para que una herramienta pueda mostrarlos o ponderarlos. caution dice qué podría hacer que la tendencia se equivoque, cuando no queda claro por uncertainty.needed. El resultado sigue siendo cantTell: una tendencia es un consejo, no un veredicto, y nada de lo que lee resultados o niveles cambia por ella. LEANS.md es la guía para quienes leen informes y construyen herramientas: qué hallazgos tienen tendencia y por qué, cómo se mide una tendencia y hasta qué punto fiarse de ella.

lean solo está presente donde la regla tiene indicios. Su ausencia también es información: solo una persona puede juzgar este caso. Solo está presente en una ocurrencia de nivel cantTell, igual que uncertainty; el motor la descarta en una ocurrencia decidida, y descarta una mal formada (un toward distinto de pass o fail, o sin why) sin tocar el hallazgo. measured aparece cuando una tendencia se ha contado frente a al menos cinco casos de respuesta conocida: cuántas veces acertó (agreed) de cuántas (cases), de qué corpus salieron (corpus, con la fecha en que se leyó) y qué versión de core los contó (coreVersion). Los recuentos son por regla, código de motivo y dirección, a partir de los casos de prueba de las W3C ACT Rules, y el motor los lleva consigo, así que un resultado de cualquier punto de entrada los tiene. Una tendencia nunca contada, o contada en menos casos, no lo tiene; no hay ningún número de confianza. Ninguna lo tiene todavía: el primer recuento, en jsdom, vio 9 tendencias, ninguna en cinco casos.

why y caution están en el idioma del análisis; i18n guarda sus claves y parámetros, como hace el i18n de una ocurrencia con summary y hint. El propio motor da tendencia a un hallazgo: una regla mapeada únicamente a un criterio que la versión de WCAG objetivo eliminó, o que las erratas de 2023 consideran satisfecho, tiende a pass junto a su incertidumbre out-of-scope.

reviewGroupOf(check, occurrence), de @surea11y/core, indica a qué grupo de una revisión va una ocurrencia: 'fail', 'leanFail', 'leanPass' u 'open' (solo una persona puede juzgarla), los grupos del informe HTML. leaningFailures(result, { wcagOnly }) enumera los hallazgos que tienden a fallo, los que cuenta una puerta con leanFailAs (JUnit, SARIF).

Llegan tendencias nuevas en versiones menores, regla a regla, y una tendencia puede retirarse si la medición muestra que se equivoca demasiado a menudo: trata una tendencia como un consejo que puede estar o no, nunca como parte de la identidad de un hallazgo. No entra en la huella.

El mapeo de un estándar dirige los hallazgos por su data.details (ver Packs), y una tendencia queda fuera de él, así que skip-link copia ahí también la dirección de su tendencia (core 1.16.0, experimental hasta la 1.18.0): data.details.lean es fail o pass, lo mismo que lean.toward, y no aparece cuando el hallazgo no tiene tendencia.

Cómo comprobarlo

Un cantTell le pasa una pregunta a una persona. howToCheck le dice cómo responderla: steps, unas pocas acciones en orden, empezando por el elemento que nombra el hallazgo (“Ve con Tab hasta el elemento.”, “Observa si el indicador de foco se queda en él.”), y luego passWhen y failWhen, lo que ve si cumple y si falla, nombrando el criterio que incumple. Core los tiene para cada código de motivo de cada regla de core que puede devolver cantTell, guardados con los procedimientos para evaluar a mano cada criterio (publicados como los diccionarios de revisión, @surea11y/core/review/<locale>), y cada ocurrencia de nivel cantTell recibe la entrada de su código, en el idioma del análisis. El hallazgo de una variante (variantOf) recibe los de su regla base cuando no tiene propios. Una regla de un pack también puede escribirlos, en inglés, y los diccionarios de su pack pueden traducirlos (ver Packs); sus hallazgos los reciben cuando se conocen los packs, como los conocen runDomRulesInPage con engineOptions.packs y addHowToCheck(result, { packs }). No aparece en una ocurrencia decidida, en el hallazgo de una regla personalizada, en el de una que reemplaza a otra (una regla personalizada o de un pack en overriddenBuiltinIds), ni en el de una regla de un pack que no escribe ninguno.

Los pasos se añaden después del análisis, en Node, no los añade el motor en la página: el motor se inyecta en cada página y frame que abre un análisis, y no le sirven de nada mil frases que ninguna regla lee. runDomRulesInPage los añade a su resultado. Un resultado de runa11yCoreInPage ejecutado en una página (el de un binding, el de una extensión) vuelve sin ellos; addHowToCheck(result) devuelve una copia con ellos, y howToCheckFor(ruleId, reasonCode, locale) da los de un hallazgo. Ambos leen del disco los diccionarios de revisión de core, así que necesitan Node; un binding cuyo código se ejecuta en un navegador (Cypress) llama a applyHowToCheck(result, { en, fr }) de @surea11y/core/how-to-check con los diccionarios que importa de @surea11y/core/review/<locale>, y obtiene los mismos pasos (BINDING_AUTHORS_GUIDE.md muestra cómo lo hace un binding). El informe HTML (renderHtmlReport) los añade en Node a un resultado que llega sin ellos; en el navegador (surea11y.report.js) muestra los que lleva el resultado. Una herramienta que muestra un resultado en otro idioma que el del análisis pasa { locale } a addHowToCheck o applyHowToCheck (addHowToCheck(result, { locale: 'de' }), o una lista de locales, la preferida primero; renderHtmlReport no lo admite): los pasos se dan en ese idioma, incluidos los que ya estaban, con inglés para cualquier paso que le falte al locale.

Los pasos dan por hecho un navegador, sus herramientas de desarrollo (el árbol de accesibilidad), un teclado y, en algunos casos, un lector de pantalla. A diferencia de uncertainty.needed, que dice en una frase qué resolvería la cuestión, ellos dicen cómo resolverla. Como una tendencia, son una guía, no parte de la identidad de un hallazgo, y su redacción puede mejorar en cualquier versión.

Pasos que nombran el caso. Desde core 1.15.0 un paso, passWhen o failWhen puede nombrar lo que encontró su hallazgo: {{name|text}} se lee como el valor del hallazgo para name, de sus i18n.params o de sus data.details, y como text cuando no tiene ninguno. Así, un paso “Open the popup, which aria-haspopup says is a {{expectedRole|menu}}” se lee “…is a listbox” en un hallazgo cuyos detalles dan expectedRole: 'listbox', y “…is a menu” en howToCheckFor, que no tiene hallazgo, y en una página de procedimientos. Un valor es una línea de 120 caracteres como máximo, y viene de la página: muéstralo como texto, como hace el informe HTML. howToCheckFor(ruleId, code, locale, { values }) los rellena con los valores dados.

Las palabras propias de un estándar. El estándar de un pack puede dar sus propios pasos para un código de una regla de core (standard.review): un hallazgo por el que solo preguntan los perfiles del estándar los lee en lugar de los de core, en inglés, así que la pregunta de un análisis de WAI-ARIA nombra WAI-ARIA, no WCAG 4.1.2. Cuando también pregunta un perfil de WCAG, en un análisis de varios, el hallazgo lee los de core.

Un resultado compuesto (rulesResults[i])

Los compuestos agregan varias reglas atómicas en un solo criterio de éxito de WCAG (por ejemplo, wcag-1.1.1-non-text-content agrega 21 reglas atómicas). Con el perfil de un estándar que tiene resultados agregados propios, también están esos, con la redacción del estándar como title y su nombre como meta.standard. La estructura es la misma que la de un resultado de comprobación, con un data.details específico de compuestos:

{
  ruleId: string,              // e.g. "wcag-1.1.1-non-text-content"
  outcome: "pass" | "fail" | "cantTell" | "notApplicable",
  severity, confidence, type, title, description, meta, engineOptions, schemaVersion,  // as on a check result, except that
                                // meta.normativeMappings names the criterion in a shorter form:
                                // { standard, requirement, level }
  occurrences: [],              // always empty — composites are rollups, not element-level findings
  data: {
    details: {
      reasonCode: string,       // e.g. "composite.rollup.fail.anyFail"
      standard?: string,        // a standard's own rollup only, with version and criterion
      version?: string,
      criterion?: string,
      checksIds: string[],      // every atomic ruleId it rolls up, custom rules mapped to its criteria included
      customChecksIds?: string[], // the custom rules among them; absent when none
      restatesWcag?: string[],  // a standard's rollup that restates WCAG criteria (applicability: 'wcag'): those criteria
      partial?: true,           // a standard's requirement its rules don't check in full (partial: true)
      contributors: Array<{ testId: string, outcome: string, severity?: string | null, custom?: true, notSelected?: true,
                            byReasonCode?: true, checkOutcome?: string, requirements?: string[] }>,
      metrics: { failCount, cantTellCount, notApplicableCount, passCount, missingCount }
    }
  }
}

Precedencia de la agregación (determinista, en este orden): cualquier contribuyente fail → compuesto fail; si no, cualquier cantTell (o una regla contribuyente que no se ejecutó en absoluto, missingCount > 0) → compuesto cantTell; si no, todos los contribuyentes notApplicable → compuesto notApplicable, donde las reglas encuentran todos los casos a los que se aplica el criterio, y cantTell (partialCoverage) en caso contrario; si no, pass, donde las reglas comprueban todo lo que pide el criterio, y cantTell (partialCheck) en caso contrario. Todavía no hay ningún criterio de WCAG catalogado como comprobado por completo, así que hoy ningún resultado agregado de WCAG da pass. Consulta Conformidad para ver qué implica esto en una afirmación de conformidad global.

El resultado agregado propio de un estándar puede juzgar una regla por sus hallazgos en lugar de entera (ver Packs): su contribuyente indica entonces byReasonCode: true, outcome es el resultado de la regla en este resultado agregado (un fail cuyos hallazgos pertenecen todos a otro sitio es aquí un pass) y checkOutcome el propio de la regla. Cuando los hallazgos que cuentan para el resultado agregado indican a cuál de sus requisitos pertenecen, requirements los enumera, y el meta.normativeMappings del resultado agregado nombra esos para esa regla, no todos los requisitos que comprueba la regla.

Las reglas de un resultado agregado de WCAG son su propia lista y cada regla de engineOptions.customRules que se ejecutó y se asocia a uno de sus criterios (mediante meta.wcagSc o una entrada de WCAG en meta.normativeMappings), marcada con custom: true entre los contribuyentes y enumerada en customChecksIds, para que un lector vea cuándo una regla personalizada decidió el resultado. Los resultados agregados propios de un estándar conservan sus listas.

Un criterio comprobado en parte. Un análisis que nombra reglas en lugar de criterios (includeRuleIds: ['link-name-present']) también recibe los resultados agregados de los criterios que comprueban esas reglas, cuando la selección no los selecciona por sí misma (ver Qué criterios informa un análisis). La precedencia anterior los decide como a cualquier otro, así que una regla que falla hace fallar el criterio, y las reglas que el análisis no seleccionó impiden que pase. Cada una de ellas es un contribuyente con outcome: "missing" y notSelected: true, contado en missingCount como antes. Cuando son lo que hace cantTell al resultado agregado, su reasonCode es composite.rollup.cantTell.notSelectedChild, y el informe HTML dice «Comprobado en parte: 1 de 2 comprobaciones no se seleccionó para este análisis». composite.rollup.cantTell.missingChild sigue significando una regla que no se ejecutó por otro motivo, como una que excluye el perfil (engine.profileExcludes), que nunca se marca como notSelected.

Valores de outcome

En las reglas integradas de core, fail es, de forma intencional, el outcome más estrecho y de mayor exigencia: reservado para violaciones deterministas y normativas; la persecución de cobertura de reglas nunca debe diluir esto.

Valores de severity y confidence

• severity: minor < moderate < serious < critical: la evaluación del autor de la regla sobre el impacto en el usuario, independiente de confidence. Un perfil puede dar a una regla otra gravedad (el severity de un perfil en un estándar o en la lista de comprobación de un pack): bajo ese perfil, el resultado muestra la del perfil, conserva la propia de la regla como ruleSeverity (presente solo entonces), y los resultados agregados toman la del perfil. En un análisis de varios perfiles, es la gravedad más alta que le da a la regla cualquier perfil que la hace fallar o pregunta por ella (la más alta de todas cuando ninguno lo hace), sea cual sea el orden en que se enumeran los perfiles.
• confidence: low < medium < high: cuán seguro está el motor de que un veredicto fail/cantTell es correcto. Ambos son metadatos informativos para priorizar; ninguno cambia el significado de outcome.

Un fail no siempre tiene confidence: "high", y eso no es una contradicción. El outcome describe el procedimiento de decisión (resolvió la cuestión sin adivinar), mientras que confidence describe el modelo contra el que se tomó esa decisión. Un puñado de reglas automáticas deciden de forma determinista contra algo que en sí mismo es una aproximación (las tablas curadas de roles WAI-ARIA, los mapeos de roles nativos, un árbol de accesibilidad inferido a partir de marcado estático) y devuelven medium: aria-required-children, aria-prohibited-children, aria-required-parent, aria-allowed-attr, form-control-programmatic-label-present, identical-iframes-same-purpose, svg-image-text-alternative-present, video-poster-text-alternative-present, target-size-minimum y text-spacing-content-loss. confidence está presente en todo resultado, así que un consumidor que solo quiera los fallos más seguros puede filtrar directamente por él; policy.allowedConfidence no hará eso por ti, ya que un valor no permitido se sustituye por el defaultConfidence propio de la regla en lugar de cambiar el outcome (consulta POLICY.md).

Ejemplo resuelto

Analizando <img src="logo.png"> (sin alt) y <button></button> (sin nombre accesible), limitado a esas dos reglas mediante runOnly: { includeRuleIds: [...] } (ver Opciones del motor; desde la 1.10.0, un array simple de ids de regla hace lo mismo):

const result = runDomRulesInPage(
  'https://example.test/',
  null,
  {},
  { includeRuleIds: ['img-alt-present', 'button-name-present'] }
);

{
  "engine": {
    "tag": "a11ycore",
    "version": "1.14.0",
    "schemaVersion": "1.0.0",
    "locale": { "requested": "en", "resolved": "en", "reason": "ok" },
    "wcagVersion": "2.2",
    "environment": { "layout": false }
  },
  "url": "https://example.test/",
  "title": "Example",
  "timestamp": null,
  "perfStats": null,
  "contextSelector": null,
  "contextMatch": null,
  "checksResults": [
    {
      "ruleId": "button-name-present",
      "outcome": "fail",
      "severity": "serious",
      "confidence": "high",
      "type": "automatic",
      "occurrences": [
        {
          "selector": "html > body > button",
          "html": "<button></button>",
          "structuralPath": [1, 1],
          "summary": "This button has no accessible name.",
          "hint": "Give the button visible text, or name it with aria-label, so screen reader users know what it does.",
          "data": {
            "visibilityFilter": { "eligible": true, "reasons": [], "targetSet": "acc", "accEligible": true },
            "details": { "reasonCode": "name_missing" }
          }
        }
      ]
    },
    {
      "ruleId": "img-alt-present",
      "outcome": "fail",
      "severity": "serious",
      "confidence": "high",
      "type": "automatic",
      "occurrences": [
        {
          "selector": "html > body > img",
          "html": "<img src=\"logo.png\">",
          "structuralPath": [1, 0],
          "summary": "This <img> has no alt attribute.",
          "hint": "Add an alt attribute that says what the image shows, or alt=\"\" if the image is purely decorative.",
          "data": {
            "details": { "reasonCode": "TEXT_ALTERNATIVE_MISSING" },
            "visibilityFilter": { "eligible": true, "reasons": [], "targetSet": "acc", "accEligible": true }
          }
        }
      ]
    }
  ],
  "rulesResults": [
    {
      "ruleId": "wcag-1.1.1-non-text-content",
      "outcome": "fail",
      "severity": "serious",
      "title": "Non-text content: text alternatives",
      "occurrences": [],
      "data": {
        "details": {
          "reasonCode": "composite.rollup.fail.anyFail",
          "checksIds": ["area-alt-present", "img-alt-decorative", "img-alt-quality", "..."],
          "contributors": [
            { "testId": "area-alt-present", "outcome": "missing", "notSelected": true },
            "...",
            { "testId": "img-alt-present", "outcome": "fail", "severity": "serious" },
            "..."
          ],
          "metrics": { "failCount": 1, "cantTellCount": 0, "notApplicableCount": 0, "passCount": 0, "missingCount": 20 }
        }
      }
    },
    {
      "ruleId": "wcag-4.1.2-name",
      "outcome": "fail",
      "severity": "serious",
      "title": "Name, role, value: accessible name",
      "occurrences": [],
      "data": {
        "details": {
          "reasonCode": "composite.rollup.fail.anyFail",
          "metrics": { "failCount": 1, "cantTellCount": 0, "notApplicableCount": 0, "passCount": 0, "missingCount": 23 }
        }
      }
    }
  ],
  "overriddenBuiltinIds": [],
  "skippedCustomRules": []
}

(Recortado por legibilidad: el resultado real también incluye title/description/i18n/meta/engineOptions/schemaVersion en cada entrada, según la estructura completa mostrada arriba, y cada contribuyente de cada resultado agregado. rulesResults contiene los criterios que comprueban las dos reglas nombradas: 1.1.1 para img-alt-present y 4.1.2 para button-name-present, cada uno fail porque su regla falló. Las demás reglas de esos criterios no se seleccionaron, así que son missing con notSelected: true; sin una regla que falle, los criterios serían cantTell (notSelectedChild), comprobados en parte. El rollupIds de cada resultado de comprobación nombra su resultado agregado.)