Schéma de sortie

Voici la forme exacte de l’objet renvoyé par runDomRulesInPage(...) / runa11yCoreInPage(...) (voir INTEGRATION.md pour savoir lequel appeler). Chaque exemple de cette page est une sortie réelle du moteur actuel (schemaVersion: "1.0.0"), pas un exemple écrit à la main. runa11yCoreAcrossFrames renvoie une forme différente, récursive, qui enveloppe celle-ci ; voir Résultat multi-frames ci-dessous.

Résultat de premier niveau

{
  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,      // "wcag22-aa", "en301549-v4.1.1", "en301549-v3.2.1", "section508", or a registered standard's own
    mappings?: string[],   // e.g. ["en301549"] or ["en301549:V3.2.1"]
    profileExcludes?: { rules: string[], criteria: string[] },
    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,
      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 }>
}

Résultat multi-frames (runa11yCoreAcrossFrames)

runa11yCoreAcrossFrames (voir INTEGRATION.md) renvoie une forme différente, récursive, au lieu d’un simple résultat de premier niveau :

{
  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 a exactement la forme du résultat de premier niveau, pour le frame dans lequel la fonction a été appelée.
• frames contient une entrée par <iframe>/<frame> enfant direct dans le périmètre analysé (shadow roots ouvertes comprises, ainsi que le périmètre lui-même quand c’est un frame), sauf un frame que la page n’affiche pas et un frame qu’exclut excludeSelectors, qui sont écartés avec tout leur document. Chaque entrée nomme son élément frame : selector est un sélecteur CSS de l’<iframe>/<frame> dans le document parent, et title est l’attribut title de l’élément, ou null, si bien que des frames qui chargent le même document se distinguent. url est le document qu’affiche le frame ou, pour un frame qui n’a pas encore navigué, son src. Un enfant joignable (qui a appelé a11yCoreEnableFrameResponder()) fournit son propre { url, topFrame, frames } complet, y compris ses propres frames imbriqués, récursivement, puisqu’un petit-enfant plus profond n’est joignable que par l’intermédiaire de son parent immédiat. Un enfant injoignable (le cas courant pour la plupart des contenus tiers intégrés : pas de responder coopératif, ou délai dépassé) fournit à la place { url, error }, sans interrompre le reste de l’analyse.
• Il s’agit d’un arbre, pas d’une liste à plat : une différence délibérée avec le .frames(true) du binding @surea11y/playwright, qui peut aplatir parce que le page.frames() de Playwright fournit déjà tous les frames quelle que soit leur profondeur d’imbrication ; un relais postMessage n’a pas cette vue globale, donc l’imbrication est exprimée par la structure.
• Les générateurs de rapports prennent l’arbre tel quel. renderHtmlReport, renderSarifReport, renderJunitReport, buildBaselineEntries, matchBaseline et renderEarlReport en rapportent chaque frame : chaque frame qui a répondu, avec ses propres constats, localisés dans son propre document, et chaque frame qui n’a pas répondu comme non analysé, pour que le trou dans la couverture ne se lise pas comme une réussite. Un frame est nommé par son chemin, les selector des éléments frame qui y mènent depuis la page, du plus extérieur au plus intérieur (#checkout → iframe:nth-of-type(2)). Ils lèvent une TypeError pour tout ce qui n’est ni un résultat d’analyse ni un résultat multi-frames (un tableau, null ou undefined issu d’une analyse qui a échoué), au lieu de le présenter comme une analyse qui n’a rien trouvé.
• Ils acceptent aussi l’analyse de frames d’un binding. Le .frames(true) des bindings navigateur renvoie { topFrame, frames }, chaque frame étant un résultat simple (ou { url, error }) plutôt qu’une entrée imbriquée ; les générateurs de rapports, getMargins et flattenCrossFrameResult lisent chacun de ces frames comme analysé, nommé par le chemin ['iframe'], puisqu’il ne porte pas de selector.
• flattenCrossFrameResult(result), de @surea11y/core, liste les frames tels que les lisent les générateurs de rapports : [{ frame: { path, title, url }, result }], ou error à la place de result pour un frame qui n’a pas répondu, la page d’abord et chaque frame avant les frames qu’il contient. Le path de la page est []. Un résultat d’analyse simple donne une seule entrée.

Un résultat de vérification (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
  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
  },
  error?: string           // present when the rule did not complete, or the engine noted a change — see below
}

Remarques :

• outcome et outcomeNormalized : identiques, sauf que notApplicable devient "inapplicable" dans outcomeNormalized. Les deux sont fournis pour que vous puissiez vous aligner soit sur votre propre vocabulaire, soit sur celui du moteur.
• Sous la politique par défaut a11y, les règles type: "manual" renvoient cantTell plutôt que fail. Si la logique propre d’une règle manuelle aurait conclu à fail, le moteur le convertit en cantTell et ajoute une note explicative à error. Ce comportement est imposé de façon centralisée (policy.coerceManualFailToCantTell, activé par défaut sous le contrat de politique a11y ; voir POLICY.md), et ce n’est pas à chaque règle d’y penser. Sous cette politique, fail est réservé aux constats déterministes type: "automatic" uniquement.
• meta.normativeMappings est ce qui relie un résultat de vérification à un critère de succès WCAG. Une liste vide signifie que la règle n’a aucune correspondance formelle dans ce résultat. Elle ne dit pas si la règle est automatique ou manuelle : c’est type qui l’indique (aria-allowed-role, par exemple, est automatique et n’a aucune correspondance WCAG). Voir Conformité pour la façon dont elles sont agrégées. La liste n’est pas réservée à WCAG. Quand l’analyse demande une autre norme (engineOptions.mappings, ou le profil d’une norme), chaque critère WCAG est suivi de l’exigence correspondante de cette norme, comme la clause d’EN 301 549 qui le reprend ({ standard: "EN 301 549", version: "V3.2.1" | "V4.1.1", requirement: "9.1.1.1", title, wcagSc: ["1.1.1"] }, une entrée par version qui inclut le critère) ; une règle peut aussi citer les documents Understanding de WCAG (type: "Understanding"). Filtrez sur standard (et sur l’absence de type) avant de lire requirement comme un critère de succès. L’entrée WCAG d’un composite vient toujours en premier. Voir EN 301 549.
• rollupIds liste les composites de rulesResults qui regroupent cette règle dans cette exécution, y compris celles signalées parce que la sélection a nommé la règle seule. Une liste vide signifie que les résultats de la règle n’apparaissent dans aucune agrégation : qui ne lit que rulesResults ne les voit jamais ; heading-order, par exemple, n’appartient à aucune agrégation WCAG.
• wcagVersionScope : présent uniquement lorsque la version WCAG cible de l’exécution a transformé le fail de cette règle en cantTell. Aujourd’hui, cela concerne une règle associée au critère 4.1.1 Analyse syntaxique (duplicate-id) : sous 2.2, qui a retiré ce critère, et sous 2.0 et 2.1, dont les errata de 2023 le considèrent comme toujours satisfait pour HTML et XML (by: "errata"). Un profil dont la norme conserve le texte du 4.1.1 (en301549-v3.2.1, ou le profil d’un pack avec keepsParsing) n’est pas converti. removedSc liste les critères concernés, target est la version de l’exécution, et coercedFrom est le résultat que la règle a elle-même renvoyé. Les occurrences sont celles de la règle, inchangées : rien n’a été supprimé, seul le verdict de conformité l’a été. Absent de tous les autres résultats, et jamais signalé via error : rien ne s’est mal passé. Voir Filtrer par version de WCAG.
• data : présent seulement sur une règle qui rapporte quelque chose sur la page entière, quel que soit son résultat. Aucune règle du cœur ne le fait aujourd’hui. Comme data.details sur une occurrence, ce n’est pas un contrat stable.
• margin : présent seulement sur une règle qui en déclare une dans le catalogue (getChecksCatalog()[i].margin, { measure, unit, limit, band? }), lorsqu’au moins un élément a atteint le seuil de la règle et, si la déclaration a une band, s’en est approché dans cette bande. band.relative est une fraction du seuil : contrast-minimum, contrast-enhanced et link-in-text-block, avec 0.1, ne rapportent une marge que pour un ratio à moins de 10 % de celui requis (de 4,5 à 4,95 pour 4,5:1, de 3 à 3,3 pour 3:1). band.absolute est une quantité en unit : target-size-minimum, avec 6, ne rapporte une cible que jusqu’à 30 px, et text-spacing-content-loss, avec 8, une ligne qu’à partir de 6 px du bord de sa boîte. Un texte à 21:1 ou un bouton de 48 px n’est proche de rien, et aucune marge ne le dit. Il désigne l’élément qui s’est le plus approché du seuil tout en le respectant, si bien qu’un pass à 4,52:1 pour un seuil de 4,5:1, ou à 0,4 px de tronquer le texte, se distingue d’un pass confortable. Il accompagne le résultat et n’est pas un constat : il n’ajoute, ne retire ni ne modifie jamais une occurrence, et les baselines, SARIF, JUnit et EARL l’ignorent. Il figure aussi sur les résultats fail et cantTell lorsque certains éléments ont satisfait la règle. limit vaut min quand la valeur doit atteindre le seuil (contraste, taille) et max quand elle doit rester en dessous (débordement) ; headroom est la marge restante, en unit, soit value - threshold pour min et threshold - value pour max, jamais négative. threshold est le seuil appliqué à cet élément, qui peut varier d’un élément à l’autre (3:1 pour du texte de grande taille). Les pixels sont donnés à une décimale : les pixels CSS et des seuils comme la moitié d’une police de 15px sont fractionnaires, et un affichage les arrondit pour les personnes. Un rapport de contraste n’est pas arrondi, puisque les WCAG n’arrondissent pas le contraste. En cas d’égalité, c’est le premier élément dans l’ordre du document qui l’emporte, si bien qu’une page donne toujours la même marge. measure et unit sont des ensembles ouverts qui peuvent s’enrichir dans une version mineure ; context est propre à la règle et, comme data.details, ce n’est pas un contrat stable. getMargins(result) renvoie toutes les marges d’un résultat sous la forme [{ ruleId, ...margin }], triées par ruleId ; pour un résultat multi-frames, celles de chaque frame, celles d’un frame enfant avec frame, le chemin qui y mène.
• error : présent quand la règle ne s’est pas terminée, ou quand le moteur a modifié ou ignoré une partie de ce que la règle a renvoyé. Une règle qui a levé une exception (ou renvoyé quelque chose qui n’est pas un résultat) apparaît toujours sous la forme outcome: "cantTell" avec occurrences: [] et error contenant le message de l’exception : cantTell sans occurrence et avec une error permet donc de reconnaître une règle qui ne s’est pas terminée ; le moteur ne laisse jamais une règle défaillante faire planter toute l’analyse. Sinon, error contient les notes du moteur, jointes par | après toute error que la règle a elle-même renvoyée : la conversion des échecs manuels décrite ci-dessus, un outcome ou une severity hors de son ensemble, un type différent de celui de son meta, des occurrences qui ne sont pas des objets (écartées), un policyOutcome ou un ruleSeverity renvoyé par la règle (non retenu : le moteur définit les deux), un uncertainty.code hors de l’ensemble fermé, et un fail ramené à cantTell parce que le parcours des ancêtres, limité à 200 étapes, s’est arrêté avant chacun des éléments signalés. Ces résultats gardent leurs occurrences : la règle s’est terminée.
• policyOutcome : présent quand les allowedOutcomes de la politique n’autorisent pas le résultat trouvé par la règle. Le résultat est alors cantTell, avec ici le résultat propre de la règle et sans error, pour que les générateurs de rapports ne le lisent pas comme une règle qui ne s’est pas terminée.
• engineOptions sur chaque résultat est l’objet d’options résolu (après application des valeurs par défaut de locale et de contraste), et non littéralement ce que vous avez passé. Utile pour vérifier ce qu’une règle donnée a réellement reçu, en particulier la locale résolue et contrast.mode/contrast.rootCanvasFallback. contrast.rootCanvasFallback vaut blanc lorsque l’appelant n’en a donné aucun, et contrast.rootCanvasFallbackSet indique lequel des deux : true pour une couleur donnée par l’appelant, false pour la valeur par défaut. Il omet messages, les dictionnaires avec lesquels l’exécution a traduit (un fichier de locale séparé dans le bundle pour navigateur, ou vos propres chaînes) : ce sont des données, pas un réglage, et une copie sur chaque résultat faisait peser une analyse des dizaines de mégaoctets. engine.locale indique quel dictionnaire a été utilisé. Trois autres options sont reprises telles que les règles les ont vues, pour que le résultat reste de simples données que JSON.stringify et structuredClone (postMessage) peuvent transporter : probes sous la forme de la copie plafonnée que lisent les règles, customRules sous la forme [{ id }], une entrée par règle personnalisée dotée d’un id, sans ses fonctions, et styleSheetTexts sous la forme [{ href }], une entrée par feuille fournie, sans son texte, puisque le CSS d’une page répété sur chaque résultat était multiplié par le nombre de règles.

Une occurrence (occurrences[i])

Un fail en a toujours au moins une : le fail d’une règle personnalisée qui ne nomme aucun élément en reçoit une sur l’élément du document (selector: "html", code de raison FAIL_WITHOUT_OCCURRENCE). Normalement présente uniquement lorsque outcome vaut fail ou cantTell : un résultat pass a occurrences: [], puisque ce moteur n’énumère pas les éléments qu’il a validés, seulement ceux qu’il a signalés. Les règles de contraste font exception : leur pass porte une occurrence qui décrit l’analyse (la quantité de texte éligible et calculable), avec un selector vide, pour qu’un pass sans aucun texte se distingue d’un pass sur une page pleine de texte.

notApplicable est la seule exception. Une règle qui n’avait rien à juger peut joindre une occurrence unique expliquant pourquoi, et c’est exactement ce que font les règles de contraste lorsqu’aucun texte n’avait d’arrière-plan calculable : la différence entre « vérifié, rien à signaler » et « impossible à vérifier » est une différence que ce moteur signale au lieu de la masquer. Une telle occurrence décrit l’analyse, pas un élément, donc son selector est vide. Ne lisez pas occurrences.length comme un nombre de violations sans vérifier d’abord 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
  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
  }
}

Codes d’incertitude

Un cantTell indique que le moteur n’a pas tranché. uncertainty indique pourquoi, à partir d’un vocabulaire fermé, pour qu’un consommateur puisse agir selon la raison plutôt que d’analyser une chaîne de résumé. Il n’est présent que sur une occurrence de niveau cantTell : une occurrence de niveau fail affirmerait que la règle a à la fois tranché et pas tranché, donc le moteur le retire. Une incertitude dont le code ne fait pas partie des codes ci-dessous est également écartée, et l’error de la règle nomme ce code.

needed indique, en une phrase, ce qui permettrait de trancher : ce que la personne qui relit doit aller vérifier. evidence contient ce que la règle a établi, pour que cette personne parte du travail du moteur au lieu de le refaire ; sa forme est propre à la règle et, comme data.details, ne constitue pas un contrat stable. Le code, lui, en est un : de nouveaux codes peuvent être ajoutés dans une version mineure, mais un code existant ne change pas de sens. Prévoyez donc un traitement pour les codes que vous connaissez et traitez un code inconnu comme « à revoir » plutôt que comme une erreur.

Toute règle automatique susceptible de renvoyer cantTell le fournit, et un test y veille pour qu’une nouvelle règle ne puisse pas arriver sans lui. Le code out-of-scope est ajouté par le moteur et non par une règle, sur les mêmes occurrences que celles qui produisent un wcagVersionScope au niveau du résultat. Les règles manuelles ne le portent pas : judgement-required est précisément ce que signifie déjà type: "manual", donc le répéter pour chaque occurrence n’apporterait rien que le résultat ne dise déjà.

Tendances

Un cantTell peut tout de même pencher d’un côté. lean indique lequel, lorsque la page fournit des indices en ce sens : toward est la réponse que ces indices rendent probable, why dit en quoi consistent ces indices, et signals liste les faits que la règle a lus, chacun sous la forme d’un nom en kebab-case et d’une valeur simple, pour qu’un outil puisse les afficher ou les pondérer. caution dit ce qui pourrait rendre la tendance fausse, lorsque uncertainty.needed ne le dit pas clairement. Le résultat reste cantTell : une tendance est un conseil, pas un verdict, et rien de ce qui lit les résultats ou les niveaux ne change à cause d’elle. LEANS.md est le guide pour les personnes qui lisent des rapports et celles qui construisent des outils : quels constats penchent et pourquoi, comment une tendance est mesurée, et quelle confiance lui accorder.

lean n’est présent que là où la règle dispose d’indices. Son absence est aussi une information : seule une personne peut juger ce constat. Il n’est présent que sur une occurrence de niveau cantTell, comme uncertainty ; le moteur le retire d’une occurrence tranchée, et retire une tendance mal formée (un toward autre que pass ou fail, ou sans why) sans toucher au constat. measured apparaît une fois qu’une tendance a été comptée sur au moins cinq cas dont la réponse est connue : combien de fois elle a eu raison (agreed) sur combien de cas (cases), de quel corpus ils proviennent (corpus, avec la date de lecture) et quelle version de core les a comptés (coreVersion). Les comptes se font par règle, code de raison et sens, à partir des cas de test des règles ACT du W3C, et le moteur les embarque, si bien qu’un résultat obtenu par n’importe quel point d’entrée les a. Une tendance jamais comptée, ou comptée sur moins de cas, n’en a pas ; il n’y a pas de score de confiance. Aucune n’en a encore : le premier comptage, dans jsdom, a vu 9 tendances, aucune sur cinq cas.

why et caution sont dans la langue de l’analyse ; i18n contient leurs clés et paramètres, comme le fait le i18n d’une occurrence pour summary et hint. Le moteur fait lui-même pencher un constat : une règle associée uniquement à un critère que la version WCAG cible a retiré, ou que les errata de 2023 considèrent comme satisfait, penche vers pass à côté de son incertitude out-of-scope.

reviewGroupOf(check, occurrence), de @surea11y/core, indique où une occurrence se place dans une revue : 'fail', 'leanFail', 'leanPass' ou 'open' (seule une personne peut juger), les groupes du rapport HTML. leaningFailures(result, { wcagOnly }) liste les constats qui penchent vers l’échec, ceux que compte un contrôle avec leanFailAs (JUnit, SARIF).

De nouvelles tendances arrivent dans les versions mineures, règle par règle, et une tendance peut être retirée si la mesure montre qu’elle se trompe trop souvent : traitez une tendance comme un conseil présent ou absent, jamais comme une partie de l’identité d’un constat. Elle n’entre pas dans l’empreinte.

Comment vérifier

Un cantTell confie une question à une personne. howToCheck lui dit comment y répondre : steps, quelques actions dans l’ordre, en partant de l’élément que nomme le constat (« Tab to the element. », « Watch whether the focus indicator stays on it. »), puis passWhen et failWhen, ce qu’elle constate si la vérification réussit et si elle échoue, en nommant le critère en cause. Chaque règle de core susceptible de renvoyer cantTell les rédige pour chacun de ses codes de raison (son meta.review), et chaque occurrence de niveau cantTell reçoit l’entrée de son code, dans la langue de l’analyse. Le constat d’une variante (variantOf) reçoit celle de sa règle de base lorsqu’il n’en a pas de propre. Une règle de pack peut aussi les rédiger, en anglais (voir Packs) ; ses constats les reçoivent lorsque les packs sont connus, comme runDomRulesInPage avec engineOptions.packs et addHowToCheck(result, { packs }) les connaissent. Il est absent d’une occurrence tranchée, du constat d’une règle personnalisée, de celui d’une règle de remplacement (une règle personnalisée ou de pack dans overriddenBuiltinIds), et de celui d’une règle de pack qui n’en rédige pas.

Les étapes sont ajoutées après l’analyse, dans Node, et non par le moteur dans la page : le moteur est injecté dans chaque page et chaque frame qu’ouvre une analyse, et n’a que faire d’un millier de phrases qu’aucune règle ne lit. runDomRulesInPage les ajoute à son résultat. Un résultat de runa11yCoreInPage exécuté dans une page (celui d’un binding, d’une extension) revient sans elles ; addHowToCheck(result) en renvoie une copie qui les contient, et howToCheckFor(ruleId, reasonCode, locale) donne celles d’un constat. Les deux lisent les dictionnaires de revue de core sur le disque, et ont donc besoin de Node ; un binding dont le code s’exécute dans un navigateur (Cypress) appelle applyHowToCheck(result, { en, fr }) de @surea11y/core/how-to-check avec les dictionnaires qu’il importe de @surea11y/core/review/<locale>, et obtient les mêmes étapes (BINDING_AUTHORS_GUIDE.md montre comment un binding s’y prend). Le rapport HTML (renderHtmlReport) les ajoute dans Node à un résultat qui arrive sans elles ; dans le navigateur (surea11y.report.js), il affiche celles que porte le résultat. Un outil qui affiche un résultat dans une autre langue que celle de l’analyse passe { locale } à addHowToCheck ou applyHowToCheck (addHowToCheck(result, { locale: 'de' }), ou une liste de langues, la plus souhaitée en premier ; renderHtmlReport n’en prend aucune) : les étapes sont données dans cette langue, y compris celles déjà présentes, avec l’anglais pour toute étape qui manque dans la langue.

Les étapes supposent un navigateur, ses outils de développement (l’arbre d’accessibilité), un clavier et, pour certaines, un lecteur d’écran. Contrairement à uncertainty.needed, qui dit en une phrase ce qui trancherait la question, elles disent comment la trancher. Comme une tendance, elles sont une aide, pas une partie de l’identité d’un constat, et leur formulation peut s’améliorer dans n’importe quelle version.

Un résultat composite (rulesResults[i])

Les composites agrègent plusieurs règles atomiques en un seul critère de succès WCAG (par ex. wcag-1.1.1-non-text-content agrège 21 règles atomiques). Sous le profil d’une norme dotée de ses propres agrégations, il y a aussi celles-ci, avec la formulation de la norme comme title et son nom comme meta.standard. Leur forme reprend l’enveloppe d’un résultat de vérification, avec un data.details propre aux composites :

{
  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 }
    }
  }
}

Ordre de priorité de l’agrégation (déterministe, dans cet ordre) : au moins une règle contributrice en fail → composite fail ; sinon au moins un cantTell (ou une règle contributrice qui ne s’est pas exécutée du tout, missingCount > 0) → composite cantTell ; sinon toutes les contributrices en notApplicable → composite notApplicable, lorsque les règles trouvent chaque cas auquel le critère s’applique, et cantTell (partialCoverage) sinon ; sinon pass, lorsque les règles vérifient tout ce que demande le critère, et cantTell (partialCheck) sinon. Aucun critère WCAG n’est encore répertorié comme entièrement vérifié, si bien qu’aucune agrégation WCAG ne donne pass aujourd’hui. Voir Conformité pour ce que cela implique pour une déclaration de conformité globale.

L’agrégation propre à une norme peut juger une règle d’après ses constats plutôt que dans son ensemble (voir Packs) : sa contributrice indique alors byReasonCode: true, outcome est le résultat de la règle dans cette agrégation (un fail dont tous les constats relèvent d’ailleurs y est un pass) et checkOutcome le résultat propre de la règle. Lorsque les constats qui comptent pour l’agrégation nomment l’exigence à laquelle ils se rattachent, requirements les liste, et le meta.normativeMappings de l’agrégation nomme celles-là pour cette règle, et non toutes les exigences que la règle vérifie.

Les règles d’une agrégation WCAG sont sa propre liste plus chaque règle de engineOptions.customRules qui s’est exécutée et qui est associée à l’un de ses critères (par meta.wcagSc ou une entrée WCAG dans meta.normativeMappings), marquée custom: true parmi les contributrices et listée dans customChecksIds, pour qu’un lecteur voie quand une règle personnalisée a déterminé le résultat. Les agrégations propres à une norme gardent leurs listes.

Un critère partiellement vérifié. Une analyse qui nomme des règles plutôt que des critères (includeRuleIds: ['link-name-present']) reçoit aussi les agrégations des critères que ces règles vérifient, quand la sélection ne les retient pas elle-même (voir Les critères que rapporte une analyse). La priorité ci-dessus les tranche comme les autres : une règle en échec fait échouer le critère, et les règles que l’analyse n’a pas sélectionnées l’empêchent de donner pass. Chacune d’elles est une contributrice avec outcome: "missing" et notSelected: true, comptée dans missingCount comme avant. Quand ce sont elles qui rendent l’agrégation cantTell, son reasonCode est composite.rollup.cantTell.notSelectedChild, et le rapport HTML indique « Vérifié en partie : 1 contrôle sur 2 n’a pas été sélectionné pour cette analyse ». composite.rollup.cantTell.missingChild désigne toujours une règle qui ne s’est pas exécutée pour une autre raison, comme une règle que le profil exclut (engine.profileExcludes), qui n’est jamais marquée notSelected.

Valeurs de résultat

Dans les règles intégrées à core, fail est volontairement le résultat le plus étroit et le plus exigeant : il est réservé aux violations normatives déterministes ; la recherche de couverture ne doit jamais le diluer.

Valeurs de sévérité et de confiance

• severity : minor < moderate < serious < critical ; l’évaluation par l’auteur de la règle de l’impact sur les utilisateurs, indépendante de confidence. Un profil peut donner une autre gravité à une règle (le severity d’un profil dans une norme ou dans la liste de contrôle d’un pack) : sous ce profil, le résultat affiche celle du profil, garde celle de la règle dans ruleSeverity (présent seulement dans ce cas), et les agrégations prennent celle du profil.
• confidence : low < medium < high ; le degré de certitude du moteur quant à l’exactitude d’un verdict fail/cantTell. Ce sont deux métadonnées informatives servant à prioriser ; aucune ne change le sens de outcome.

Un fail n’est pas toujours confidence: "high", et ce n’est pas une contradiction. Le résultat décrit la procédure de décision (elle a tranché la question sans deviner), tandis que confidence décrit le modèle par rapport auquel cette décision a été prise. Quelques règles automatiques décident de façon déterministe par rapport à quelque chose qui est lui-même une approximation (les tables de rôles WAI-ARIA maintenues à la main, les correspondances de rôles natifs, un arbre d’accessibilité déduit du balisage statique) et renvoient 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 et text-spacing-content-loss. confidence figure sur chaque résultat, donc un consommateur qui ne veut que les échecs les plus certains peut filtrer directement dessus ; policy.allowedConfidence ne le fera pas pour vous, puisqu’une valeur non autorisée est remplacée par le defaultConfidence propre à la règle au lieu de changer le résultat (voir POLICY.md).

Exemple commenté

Analyse de <img src="logo.png"> (sans alt) et de <button></button> (sans nom accessible), limitée à ces deux règles via runOnly: { includeRuleIds: [...] } (voir Options du moteur ; depuis la 1.10.0, un simple tableau d’ids de règles fait la même chose) :

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": []
}

(Version abrégée pour la lisibilité : le résultat réel inclut aussi title/description/i18n/meta/engineOptions/schemaVersion sur chaque entrée, conformément à la forme complète ci-dessus, et chaque contributrice de chaque agrégation. rulesResults contient les critères que vérifient les deux règles nommées : 1.1.1 pour img-alt-present et 4.1.2 pour button-name-present, chacun fail parce que sa règle a échoué. Les autres règles de ces critères n’ont pas été sélectionnées, elles sont donc missing avec notSelected: true ; sans règle en échec, les critères seraient cantTell (notSelectedChild), partiellement vérifiés. Le rollupIds de chaque résultat de vérification nomme son agrégation.)