Ausgabeschema

Dies ist die genaue Struktur des Objekts, das runDomRulesInPage(...) / runa11yCoreInPage(...) zurückgibt (welche davon Sie aufrufen, steht in INTEGRATION.md). Jedes Beispiel auf dieser Seite ist echte Ausgabe der aktuellen Engine (schemaVersion: "1.0.0"), nicht von Hand geschrieben. runa11yCoreAcrossFrames gibt eine andere, rekursive Struktur zurück, die diese umschließt, siehe Frame-übergreifendes Ergebnis unten.

Ergebnis auf oberster Ebene

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

Frame-übergreifendes Ergebnis (runa11yCoreAcrossFrames)

runa11yCoreAcrossFrames (siehe INTEGRATION.md) gibt statt eines einfachen Ergebnisses auf oberster Ebene eine andere, rekursive Struktur zurück:

{
  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 hat genau die Struktur des Ergebnisses auf oberster Ebene, für den Frame, in dem die Funktion aufgerufen wurde.
• frames hat einen Eintrag pro direktem Kind-<iframe>/<frame> im gescannten Bereich (offene Shadow Roots eingeschlossen, und der Bereich selbst, wenn er ein Frame ist), außer einem Frame, den die Seite nicht zeigt, und einem Frame, den excludeSelectors ausschließt; diese werden mit ihrem ganzen Dokument weggelassen. Jeder Eintrag benennt sein Frame-Element: selector ist ein CSS-Selektor für das <iframe>/<frame> im Dokument des Eltern-Frames, und title ist das title-Attribut des Elements oder null, sodass sich Frames, die dasselbe Dokument laden, unterscheiden lassen. url ist das Dokument, das der Frame zeigt, oder bei einem Frame, der noch nicht navigiert hat, sein src. Ein erreichbares Kind (eines, das a11yCoreEnableFrameResponder() aufgerufen hat) liefert sein eigenes vollständiges { url, topFrame, frames }, einschließlich seiner eigenen verschachtelten frames, rekursiv, denn ein tiefer verschachteltes Enkel-Frame ist nur über sein unmittelbares Eltern-Frame erreichbar. Ein nicht erreichbares Kind (der Normalfall bei den meisten Einbettungen von Drittanbietern: kein kooperierender Responder, oder er hat das Zeitlimit überschritten) liefert stattdessen { url, error } und bricht den Rest des Scans nicht ab.
• Das ist ein Baum, keine flache Liste. Das ist ein bewusster Unterschied zu .frames(true) im Binding @surea11y/playwright, das abflachen kann, weil page.frames() in Playwright ohnehin jedes Frame unabhängig von der Verschachtelungstiefe liefert. Ein postMessage-Relay hat keine solche Gesamtsicht, deshalb wird die Verschachtelung stattdessen strukturell abgebildet.
• Die Reporter nehmen den Baum, wie er ist. renderHtmlReport, renderSarifReport, renderJunitReport, buildBaselineEntries, matchBaseline und renderEarlReport melden jeden Frame darin: jeden Frame, der geantwortet hat, mit seinen eigenen Befunden, verortet in seinem eigenen Dokument, und jeden, der nicht geantwortet hat, als nicht gescannt, sodass eine Lücke in der Abdeckung nicht wie ein Bestehen aussieht. Ein Frame wird über seinen Pfad benannt, die selectors der Frame-Elemente, die von der Seite zu ihm führen, das äußerste zuerst (#checkout → iframe:nth-of-type(2)). Sie werfen einen TypeError bei allem, was weder ein Scan-Ergebnis noch ein Frame-übergreifendes Ergebnis ist (ein Array, null oder undefined aus einem fehlgeschlagenen Scan), statt es als Scan ohne Befunde darzustellen.
• Sie nehmen auch den Frame-Scan eines Bindings. .frames(true) der Browser-Bindings gibt { topFrame, frames } zurück, wobei jeder Frame ein einfaches Ergebnis (oder { url, error }) statt eines verschachtelten Eintrags ist; die Reporter, getMargins und flattenCrossFrameResult lesen jeden solchen Frame als gescannt, benannt mit dem Pfad ['iframe'], da er keinen selector trägt.
• flattenCrossFrameResult(result) aus @surea11y/core listet die Frames so, wie die Reporter sie lesen: [{ frame: { path, title, url }, result }], oder error statt result bei einem Frame, der nicht geantwortet hat, die Seite zuerst und jeder Frame vor den Frames darin. Der path der Seite ist []. Ein einfaches Scan-Ergebnis ist ein einziger Eintrag.

Ein Prüfergebnis (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
}

Hinweise:

• outcome vs. outcomeNormalized: identisch, nur dass notApplicable in outcomeNormalized zu "inapplicable" wird. Beide werden geliefert, damit Sie entweder Ihr eigenes Vokabular oder das interne der Engine abgleichen können.
• Unter der Standard-Policy a11y melden Regeln mit type: "manual" cantTell statt fail. Würde die eigene Logik einer manuellen Regel fail ergeben, wandelt die Engine das zu cantTell um und hängt einen erklärenden Hinweis an error an. Das wird zentral durchgesetzt (policy.coerceManualFailToCantTell, im Policy-Vertrag a11y standardmäßig aktiv; siehe POLICY.md) und muss nicht von jeder Regel selbst beachtet werden. Unter dieser Policy ist fail ausschließlich deterministischen Befunden mit type: "automatic" vorbehalten.
• meta.normativeMappings verknüpft ein Prüfergebnis mit einem WCAG-Erfolgskriterium. Eine leere Liste bedeutet, dass die Regel in diesem Ergebnis keine formale Zuordnung hat. Ob die Regel automatisch oder manuell ist, sagt sie nicht: Das zeigt type (aria-allowed-role etwa ist automatisch und hat keine WCAG-Zuordnung). Wie diese zusammengefasst werden, steht unter Konformität. Die Liste enthält nicht nur WCAG. Fordert der Scan eine andere Norm an (engineOptions.mappings oder das Profil einer Norm), folgt auf jedes WCAG-Kriterium die entsprechende Anforderung dieser Norm, etwa die EN-301-549-Klausel, die es wiedergibt ({ standard: "EN 301 549", version: "V3.2.1" | "V4.1.1", requirement: "9.1.1.1", title, wcagSc: ["1.1.1"] }, ein Eintrag pro Version, die das Kriterium enthält); außerdem kann eine Regel die Understanding-Dokumente der WCAG zitieren (type: "Understanding"). Filtern Sie nach standard (und nach fehlendem type), bevor Sie requirement als Erfolgskriterium lesen. Der WCAG-Eintrag einer zusammengesetzten Regel steht immer zuerst. Siehe EN 301 549.
• rollupIds listet die zusammengesetzten Regeln in rulesResults, die diese Regel in diesem Lauf gruppieren, einschließlich derer, die gemeldet werden, weil die Auswahl die Regel einzeln genannt hat. Eine leere Liste bedeutet, dass die Befunde der Regel in keiner Zusammenfassung erscheinen; wer nur rulesResults liest, sieht sie also nie. heading-order gehört zum Beispiel zu keiner WCAG-Zusammenfassung.
• wcagVersionScope: nur vorhanden, wenn die WCAG-Zielversion des Laufs das fail dieser Regel in ein cantTell verwandelt hat. Derzeit betrifft das eine auf Erfolgskriterium 4.1.1 „Syntaxanalyse“ abgebildete Regel (duplicate-id): unter 2.2, das dieses Kriterium entfernt hat, und unter 2.0 und 2.1, deren Errata von 2023 es für HTML und XML als immer erfüllt werten (by: "errata"). Ein Profil, dessen Norm den Text von 4.1.1 beibehält (en301549-v3.2.1 oder das Profil eines Packs mit keepsParsing), wird nicht umgewandelt. removedSc listet die betroffenen Kriterien, target ist die Version des Laufs, und coercedFrom ist das Ergebnis, das die Regel selbst gemeldet hat. Die Vorkommen sind die der Regel, unverändert: Nichts wurde verworfen, nur das Konformitätsurteil. Fehlt bei jedem anderen Ergebnis und wird nie über error gemeldet: Es ist nichts schiefgegangen. Siehe Filtern nach WCAG-Version.
• data: nur bei einer Regel vorhanden, die unabhängig von ihrem Ergebnis etwas über die ganze Seite meldet. Keine Core-Regel tut das derzeit. Wie data.details bei einem Vorkommen ist es kein stabiler Vertrag.
• margin: nur bei einer Regel vorhanden, die im Katalog eine deklariert (getChecksCatalog()[i].margin, { measure, unit, limit, band? }), und nur, wenn mindestens ein Element den Schwellenwert der Regel erfüllt hat und, falls die Deklaration ein band hat, innerhalb davon lag. band.relative ist ein Bruchteil des Schwellenwerts: contrast-minimum, contrast-enhanced und link-in-text-block melden mit 0.1 eine Marge nur für ein Verhältnis innerhalb von 10 % des geforderten (4,5 bis 4,95 bei 4,5:1, 3 bis 3,3 bei 3:1). band.absolute ist ein Betrag in unit: target-size-minimum meldet mit 6 ein Ziel nur bis 30 px, und text-spacing-content-loss mit 8 eine Zeile nur ab 6 px innerhalb des Rands ihrer Box. Text mit 21:1 oder ein 48-px-Button ist nirgends knapp, und keine Marge sagt etwas anderes. Es nennt das Element, das dem Schwellenwert am nächsten kam und ihn dabei erfüllte. So lässt sich ein pass mit 4,52:1 bei geforderten 4,5:1 oder 0,4 px vor abgeschnittenem Text von einem mit reichlich Abstand unterscheiden. Es steht neben dem Ergebnis und ist kein Befund: Es fügt nie ein Vorkommen hinzu, entfernt oder ändert keines, und Baselines, SARIF, JUnit und EARL ignorieren es. Es wird auch bei fail- und cantTell-Ergebnissen gemeldet, wenn einige Elemente bestanden haben. limit ist min, wenn der Wert den Schwellenwert erreichen muss (Kontrast, Größe), und max, wenn er darunter bleiben muss (Überlauf); headroom ist der verbleibende Abstand in unit, also value - threshold bei min und threshold - value bei max, nie negativ. threshold ist der Schwellenwert, an dem dieses Element gemessen wurde; er kann sich zwischen Elementen unterscheiden (3:1 für großen Text). Pixel werden mit einer Nachkommastelle angegeben: CSS-Pixel und Schwellenwerte wie die Hälfte einer 15px-Schrift sind Bruchzahlen, und eine Anzeige rundet sie für Menschen. Ein Verhältnis wird nicht gerundet, da WCAG Kontrast nicht rundet. Bei Gleichstand gewinnt das in der Dokumentreihenfolge erste Element, sodass eine Seite jedes Mal denselben Wert ergibt. measure und unit sind offene Mengen, die in einem Minor-Release wachsen können; context ist regelspezifisch und, wie data.details, kein stabiler Vertrag. getMargins(result) gibt alle Werte eines Ergebnisses als [{ ruleId, ...margin }] zurück, sortiert nach ruleId; bei einem Frame-übergreifenden Ergebnis die Werte jedes Frames, die eines Kind-Frames mit frame, dem Pfad zu ihm.
• error: vorhanden, wenn die Regel nicht abgeschlossen wurde oder wenn die Engine einen Teil dessen, was die Regel zurückgegeben hat, geändert oder ignoriert hat. Eine Regel, die eine Exception geworfen hat (oder etwas zurückgegeben hat, das kein Ergebnis ist), erscheint immer als outcome: "cantTell" mit occurrences: [] und der Exception-Meldung in error; an cantTell ohne Vorkommen und mit einem error erkennen Sie also eine Regel, die nicht abgeschlossen wurde. Die Engine lässt nie zu, dass eine einzelne defekte Regel den ganzen Scan zum Absturz bringt. Sonst enthält error die Hinweise der Engine, mit | verbunden nach einem error, den die Regel selbst zurückgegeben hat: die oben beschriebene Umwandlung manueller fail-Ergebnisse, ein outcome oder eine severity außerhalb ihrer Menge, ein type, der von dem in ihrem meta abweicht, Vorkommen, die keine Objekte sind (weggelassen), ein policyOutcome oder eine ruleSeverity, die die Regel zurückgegeben hat (nicht übernommen: Die Engine setzt beide), ein uncertainty.code außerhalb der geschlossenen Menge und ein fail, das zu cantTell herabgestuft wurde, weil der Durchlauf über die Vorfahren nach 200 Schritten vor jedem gemeldeten Element abgebrochen ist. Diese Ergebnisse behalten ihre Vorkommen: Die Regel wurde abgeschlossen.
• policyOutcome: vorhanden, wenn allowedOutcomes der Policy das Ergebnis, das die Regel gefunden hat, nicht zulässt. Das Ergebnis ist dann cantTell, mit dem eigenen Ergebnis der Regel hier und ohne error, sodass die Reporter es nicht als Regel lesen, die nicht abgeschlossen wurde.
• engineOptions ist in jedem Ergebnis das aufgelöste Optionsobjekt (nach Anwendung der Standardwerte für Locale und Kontrast), nicht wörtlich das, was Sie übergeben haben. Nützlich, um zu prüfen, was eine bestimmte Regel tatsächlich gesehen hat, insbesondere die aufgelöste locale und contrast.mode/contrast.rootCanvasFallback. contrast.rootCanvasFallback ist Weiß, wenn der Aufruf keine Farbe angegeben hat, und contrast.rootCanvasFallbackSet sagt, welcher Fall vorliegt: true für eine angegebene Farbe, false für den Standardwert. Es lässt messages weg, die Wörterbücher, mit denen der Lauf übersetzt hat (eine separate Locale-Datei im Browser-Bundle oder Ihre eigenen Strings): Sie sind Daten, keine Einstellung, und eine Kopie in jedem Ergebnis machte einen Scan zig Megabyte groß. engine.locale gibt an, welches Wörterbuch verwendet wurde. Drei weitere Optionen werden so wiedergegeben, wie die Regeln sie gesehen haben, damit das Ergebnis einfache Daten bleibt, die JSON.stringify und structuredClone (postMessage) transportieren können: probes als die gekappte Kopie, die die Regeln lesen, customRules als [{ id }], ein Eintrag je eigener Regel mit ID, ohne ihre Funktionen, und styleSheetTexts als [{ href }], ein Eintrag je übergebenem Stylesheet, ohne seinen Text, da das CSS einer Seite, in jedem Ergebnis wiederholt, mit der Zahl der Regeln multipliziert wurde.

Ein Vorkommen (occurrences[i])

Ein fail hat immer mindestens eines: Das fail einer eigenen Regel, das kein Element nennt, erhält eines am Dokumentelement (selector: "html", Reason-Code FAIL_WITHOUT_OCCURRENCE). Normalerweise nur vorhanden, wenn outcome fail oder cantTell ist: Ein pass-Ergebnis hat occurrences: [], da diese Engine nicht die Elemente aufzählt, die bestanden haben, sondern nur die markierten. Die Kontrastregeln sind die Ausnahme: Ihr pass trägt ein Vorkommen, das den Scan beschreibt (wie viel Text in Frage kam und berechenbar war), mit leerem selector, damit sich ein pass ohne jeden Text von einem über eine Seite voller Text unterscheiden lässt.

notApplicable ist die einzige Ausnahme. Eine Regel, die nichts zu beurteilen hatte, kann ein einzelnes Vorkommen mit der Begründung anhängen, und die Kontrastregeln tun genau das, wenn kein Text einen berechenbaren Hintergrund hatte. Den Unterschied zwischen „geprüft, nichts zu melden“ und „konnte nicht prüfen“ meldet diese Engine, statt ihn zu verbergen. Ein solches Vorkommen beschreibt den Scan, kein Element, deshalb ist sein selector leer. Lesen Sie occurrences.length nicht als Anzahl der Verstöße, ohne vorher outcome zu prüfen.

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

Unsicherheitscodes

Ein cantTell besagt, dass die Engine nicht entschieden hat. uncertainty sagt warum, aus einem geschlossenen Vokabular, sodass ein Konsument nach dem Grund verzweigen kann, statt einen Zusammenfassungs-String zu parsen. Es ist nur bei einem Vorkommen der cantTell-Stufe vorhanden: Ein Vorkommen der fail-Stufe würde behaupten, dass die Regel zugleich entschieden und nicht entschieden hat, daher entfernt die Engine es dort. Eine Unsicherheit, deren code keiner der Codes unten ist, wird ebenfalls weggelassen, und der error der Regel nennt den Code.

needed nennt in einem Satz, was die Frage klären würde, also das, was eine prüfende Person nachsehen muss. evidence enthält, was die Regel tatsächlich festgestellt hat, damit die Prüfung auf der Arbeit der Engine aufbaut, statt sie zu wiederholen; die Struktur ist regelspezifisch und, wie data.details, kein stabiler Vertrag. Der code dagegen schon: Neue Codes können in einem Minor-Release hinzukommen, aber ein bestehender ändert seine Bedeutung nicht. Verzweigen Sie also nach den Codes, die Sie kennen, und behandeln Sie einen unbekannten als „muss geprüft werden“, nicht als Fehler.

Jede automatische Regel, die cantTell melden kann, liefert dieses Feld, und ein Test stellt das sicher, damit keine neue Regel ohne es hinzukommt. Den Code out-of-scope hängt die Engine an, nicht eine Regel, und zwar an genau die Vorkommen, die auf Ergebnisebene ein wcagVersionScope erzeugen. Manuelle Regeln liefern es nicht: judgement-required ist genau das, was type: "manual" bereits bedeutet, eine Wiederholung pro Vorkommen würde also nichts sagen, was das Ergebnis nicht schon sagt.

Tendenzen

Ein cantTell kann trotzdem in eine Richtung weisen. lean gibt an, in welche, wenn die Seite Anhaltspunkte dafür liefert: toward ist die Antwort, die diese Anhaltspunkte wahrscheinlich machen, why sagt, worin sie bestehen, und signals listet die Fakten, die die Regel gelesen hat, jeweils ein Name in Kebab-Case und ein einfacher Wert, damit ein Tool sie anzeigen oder gewichten kann. caution sagt, was die Tendenz falsch machen könnte, wenn das nicht schon aus uncertainty.needed hervorgeht. Das Ergebnis bleibt cantTell: Eine Tendenz ist ein Hinweis, kein Urteil, und nichts, was Ergebnisse oder Stufen liest, ändert sich durch sie. LEANS.md ist der Leitfaden für alle, die Berichte lesen oder Tools bauen: welche Befunde eine Tendenz haben und warum, wie eine Tendenz gemessen wird und wie weit man ihr trauen kann.

lean ist nur vorhanden, wo die Regel Anhaltspunkte hat. Auch das Fehlen ist eine Information: Diesen Befund kann nur eine Person beurteilen. Es ist nur bei einem Vorkommen der cantTell-Stufe vorhanden, wie uncertainty; die Engine entfernt es bei einem entschiedenen Vorkommen und entfernt ein fehlerhaftes (ein toward außer pass oder fail, oder kein why), ohne den Befund anzutasten. measured erscheint, sobald eine Tendenz an mindestens fünf Fällen mit bekannter Antwort gezählt wurde: wie oft sie richtig lag (agreed), von wie vielen (cases), aus welchem Korpus die Fälle stammen (corpus, mit dem Datum, an dem er gelesen wurde) und welche core-Version sie gezählt hat (coreVersion). Gezählt wird je Regel, Reason-Code und Richtung, anhand der Testfälle der W3C ACT Rules, und die Engine führt die Zahlen mit, sodass ein Ergebnis aus jedem Einstiegspunkt sie hat. Eine nie oder an weniger Fällen gezählte Tendenz hat keine; eine Konfidenzzahl gibt es nicht. Bisher hat noch keine eine: Die erste Zählung, in jsdom, sah 9 Tendenzen, keine an fünf Fällen.

why und caution stehen in der Locale des Scans; i18n enthält ihre Schlüssel und Parameter, wie das i18n eines Vorkommens für summary und hint. Die Engine selbst gibt einem Befund eine Tendenz: Eine Regel, die nur auf ein Kriterium abgebildet ist, das die WCAG-Zielversion entfernt hat oder das die Errata von 2023 als erfüllt werten, tendiert zu pass, neben ihrer Unsicherheit out-of-scope.

reviewGroupOf(check, occurrence) aus @surea11y/core gibt an, wohin ein Vorkommen in einer Prüfung gehört: 'fail', 'leanFail', 'leanPass' oder 'open' (nur eine Person kann es beurteilen), die Gruppen des HTML-Berichts. leaningFailures(result, { wcagOnly }) listet die Befunde, die zu fail tendieren, also die, die eine Schranke mit leanFailAs zählt (JUnit, SARIF).

Neue Tendenzen kommen in Minor-Releases hinzu, Regel für Regel, und eine Tendenz kann entfernt werden, wenn die Messung zeigt, dass sie zu oft falsch liegt: Behandeln Sie eine Tendenz als Hinweis, der da sein kann oder nicht, nie als Teil der Identität eines Befunds. Sie geht nicht in den Fingerprint ein.

So prüfen Sie es

Ein cantTell übergibt eine Frage an eine Person. howToCheck sagt ihr, wie sie sie beantwortet: steps, einige Handlungen der Reihe nach, beginnend bei dem Element, das der Befund nennt („Gehen Sie mit der Tabulatortaste zum Element.“, „Achten Sie darauf, ob der Fokusindikator darauf bleibt.“), dann passWhen und failWhen, was sie sieht, wenn die Anforderung erfüllt ist und wenn nicht, mit dem Kriterium, das dann nicht erfüllt ist. Jede Core-Regel, die cantTell melden kann, schreibt diese Texte für jeden ihrer Reason-Codes (ihr meta.review), und jedes Vorkommen der cantTell-Stufe erhält den Eintrag seines Codes, in der Locale des Scans. Der Befund einer Variante (variantOf) erhält den ihrer Basisregel, wo sie keinen eigenen hat. Eine Regel eines Packs kann sie ebenfalls schreiben, auf Englisch (siehe Packs); ihre Befunde erhalten sie, wenn die Packs bekannt sind, wie sie runDomRulesInPage mit engineOptions.packs und addHowToCheck(result, { packs }) kennen. Es fehlt bei einem entschiedenen Vorkommen, beim Befund einer eigenen Regel, bei dem einer Überschreibung (einer eigenen Regel oder Regel eines Packs in overriddenBuiltinIds) und bei dem einer Pack-Regel, die keine schreibt.

Die Schritte werden nach dem Scan in Node hinzugefügt, nicht von der Engine in der Seite: Die Engine wird in jede Seite und jeden Frame eingefügt, die ein Scan öffnet, und hat keine Verwendung für tausend Sätze, die keine Regel liest. runDomRulesInPage fügt sie seinem Ergebnis hinzu. Ein Ergebnis von runa11yCoreInPage, in einer Seite ausgeführt (das eines Bindings, einer Erweiterung), kommt ohne sie zurück; addHowToCheck(result) gibt eine Kopie mit ihnen zurück, und howToCheckFor(ruleId, reasonCode, locale) liefert die eines einzelnen Befunds. Beide lesen die Prüf-Wörterbücher von core von der Festplatte und brauchen daher Node; ein Binding, dessen Code im Browser läuft (Cypress), ruft applyHowToCheck(result, { en, fr }) aus @surea11y/core/how-to-check mit den Wörterbüchern auf, die es aus @surea11y/core/review/<locale> importiert, und erhält dieselben Schritte (BINDING_AUTHORS_GUIDE.md zeigt, wie ein Binding das macht). Der HTML-Bericht (renderHtmlReport) fügt sie in Node einem Ergebnis hinzu, das ohne sie kommt; im Browser (surea11y.report.js) zeigt er die, die das Ergebnis mitführt. Ein Tool, das ein Ergebnis in einer anderen Sprache als der des Scans anzeigt, übergibt { locale } an addHowToCheck oder applyHowToCheck (addHowToCheck(result, { locale: 'de' }) oder eine Liste von Locales, die gewünschteste zuerst; renderHtmlReport nimmt keine): Die Schritte kommen in dieser Sprache, auch die bereits vorhandenen, mit Englisch für jeden Schritt, der in der Locale fehlt.

Die Schritte setzen einen Browser voraus, seine Entwicklerwerkzeuge (den Accessibility Tree), eine Tastatur und für manche einen Screenreader. Anders als uncertainty.needed, das in einem Satz sagt, was die Frage klären würde, sagen sie, wie man sie klärt. Wie eine Tendenz sind sie eine Anleitung, nicht Teil der Identität eines Befunds, und ihr Wortlaut kann sich in jedem Release verbessern.

Ein zusammengesetztes Ergebnis (rulesResults[i])

Zusammengesetzte Regeln fassen mehrere atomare Regeln zu einem WCAG-Erfolgskriterium zusammen (z. B. fasst wcag-1.1.1-non-text-content 21 atomare Regeln zusammen). Unter dem Profil einer Norm mit eigenen Zusammenfassungen gibt es zusätzlich diese, mit dem Wortlaut der Norm als title und ihrem Namen als meta.standard. Die Struktur ist dieselbe Hülle wie bei einem Prüfergebnis, mit spezifischen data.details für zusammengesetzte Regeln:

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

Vorrang bei der Zusammenfassung (deterministisch, in dieser Reihenfolge): irgendein Beitrag fail → zusammengesetzt fail; sonst irgendein cantTell (oder eine beitragende Regel, die gar nicht gelaufen ist, missingCount > 0) → zusammengesetzt cantTell; sonst alle Beiträge notApplicable → zusammengesetzt notApplicable, wo die Regeln jeden Fall finden, für den das Kriterium gilt, und sonst cantTell (partialCoverage); sonst pass, wo die Regeln alles prüfen, was das Kriterium verlangt, und sonst cantTell (partialCheck). Noch ist kein WCAG-Kriterium als vollständig geprüft geführt, daher ergibt derzeit keine WCAG-Zusammenfassung pass. Was das für eine Gesamtaussage zur Konformität bedeutet, steht unter Konformität.

Die eigene Zusammenfassung einer Norm kann eine Regel nach ihren Befunden statt als Ganzes beurteilen (siehe Packs): Ihre beitragende Regel gibt dann byReasonCode: true an, outcome ist das Ergebnis der Regel in dieser Zusammenfassung (ein fail, dessen Befunde alle woandershin gehören, ist hier ein pass) und checkOutcome das eigene Ergebnis der Regel. Nennen die Befunde, die für die Zusammenfassung zählen, zu welcher ihrer Anforderungen sie gehören, listet requirements diese auf, und die meta.normativeMappings der Zusammenfassung nennen für diese Regel genau diese, nicht jede Anforderung, die die Regel prüft.

Die Regeln einer WCAG-Zusammenfassung sind ihre eigene Liste und jede Regel aus engineOptions.customRules, die gelaufen ist und einem ihrer Kriterien zugeordnet ist (über meta.wcagSc oder einen WCAG-Eintrag in meta.normativeMappings), unter den beitragenden Regeln mit custom: true gekennzeichnet und in customChecksIds aufgeführt, sodass eine lesende Person sieht, wann eine eigene Regel das Ergebnis entschieden hat. Die eigenen Zusammenfassungen einer Norm behalten ihre Listen.

Ein teilweise geprüftes Kriterium. Ein Scan, der Regeln statt Kriterien nennt (includeRuleIds: ['link-name-present']), erhält auch die Zusammenfassungen der Kriterien, die diese Regeln prüfen, wenn die Auswahl sie nicht selbst auswählt (siehe Welche Kriterien ein Scan meldet). Die obige Rangfolge entscheidet sie wie jede andere: Eine Regel mit fail lässt das Kriterium scheitern, und Regeln, die der Scan nicht ausgewählt hat, verhindern, dass es pass ergibt. Jede davon ist eine beitragende Regel mit outcome: "missing" und notSelected: true, wie bisher in missingCount gezählt. Wenn sie es sind, die die Zusammenfassung zu cantTell machen, ist ihr reasonCode composite.rollup.cantTell.notSelectedChild, und der HTML-Bericht zeigt „Teilweise geprüft: 1 von 2 Prüfungen war für diesen Scan nicht ausgewählt“. composite.rollup.cantTell.missingChild steht weiterhin für eine Regel, die aus einem anderen Grund nicht gelaufen ist, etwa eine, die das Profil ausschließt (engine.profileExcludes); sie ist nie mit notSelected markiert.

Ergebniswerte

In den eingebauten Regeln von core ist fail bewusst das engste Ergebnis mit der höchsten Hürde: deterministischen, normativen Verstößen vorbehalten; das Streben nach mehr Regelabdeckung darf es nie verwässern.

Werte für Schweregrad und Konfidenz

• severity: minor < moderate < serious < critical: die Einschätzung der Regelautorin bzw. des Regelautors zu den Auswirkungen auf Nutzende, unabhängig von confidence. Ein Profil kann einer Regel einen anderen Schweregrad geben (die severity eines Profils in einer Norm oder in der Checkliste eines Packs): Darunter zeigt das Ergebnis den des Profils, behält den eigenen der Regel als ruleSeverity (nur dann vorhanden), und die Zusammenfassungen übernehmen den des Profils.
• confidence: low < medium < high: wie sicher die Engine ist, dass ein fail/cantTell-Urteil stimmt. Beides sind informative Metadaten zur Priorisierung; keins von beiden ändert die Bedeutung von outcome.

Ein fail hat nicht immer confidence: "high", und das ist kein Widerspruch. Das Ergebnis beschreibt das Entscheidungsverfahren (es hat die Frage ohne Raten beantwortet), während confidence das Modell beschreibt, gegen das entschieden wurde. Einige automatische Regeln entscheiden deterministisch gegen etwas, das selbst eine Näherung ist (die kuratierten WAI-ARIA-Rollentabellen, die Zuordnungen nativer Rollen, ein aus statischem Markup abgeleiteter Accessibility Tree), und melden 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 und text-spacing-content-loss. confidence steht in jedem Ergebnis, sodass ein Konsument, der nur die sichersten Verstöße will, direkt danach filtern kann; policy.allowedConfidence erledigt das nicht für Sie, da ein nicht zulässiger Wert durch den defaultConfidence der Regel ersetzt wird, statt das Ergebnis zu ändern (siehe POLICY.md).

Durchgerechnetes Beispiel

Scan von <img src="logo.png"> (ohne alt) und <button></button> (ohne zugänglichen Namen), eingegrenzt auf genau diese beiden Regeln über runOnly: { includeRuleIds: [...] } (siehe Engine-Optionen; seit 1.10.0 bewirkt ein reines Array von Regel-IDs dasselbe):

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

(Zur besseren Lesbarkeit gekürzt: Das echte Ergebnis enthält laut der vollständigen Struktur oben in jedem Eintrag zusätzlich title/description/i18n/meta/engineOptions/schemaVersion, und jede beitragende Regel jeder Zusammenfassung. rulesResults enthält die Kriterien, die die beiden genannten Regeln prüfen: 1.1.1 für img-alt-present und 4.1.2 für button-name-present, beide fail, weil ihre Regel fail ergab. Die übrigen Regeln dieser Kriterien wurden nicht ausgewählt und sind daher missing mit notSelected: true; ohne eine Regel mit fail wären die Kriterien cantTell (notSelectedChild), teilweise geprüft. Die rollupIds jedes Prüfergebnisses nennen seine Zusammenfassung.)