Engine-Optionen

Jeder Runner (runDomRulesInPage, runa11yCoreInPage) nimmt dieselben vier Argumente entgegen: (pageUrl, contextSelector, engineOptions, runOnly). Diese Seite dokumentiert engineOptions und runOnly vollständig. Um eine Seite gegen eine WCAG-Version und -Stufe zu prüfen, beginnen Sie mit runOnly.wcag.

Auswählen, welche Regeln laufen

Nennen Sie, wogegen Sie prüfen, und die Engine wählt die Regeln. Ohne Auswahl laufen die Standardregeln: jede Regel außer den Opt-in-Regeln einer Norm oder eines Packs, die erst laufen, wenn sie freigeschaltet sind (siehe Opt-in-Regeln).

// WCAG 2.2 AA, with the best practices:
runDomRulesInPage(url, null, {}, {
  wcag: { version: '2.2', level: 'AA' },
  bestPractices: true
});

Jede Regel prüft entweder WCAG-Kriterien oder ist eine Best Practice, daher führt { wcag: { version: '2.2', level: 'AAA' }, bestPractices: true } jede Regel aus außer denen für 4.1.1 Syntaxanalyse, das WCAG 2.2 entfernt hat. Für alles Feinere, etwa ein einzelnes Kriterium, eine Liste von Regeln oder einen Ausschluss, siehe „Erweiterte Auswahl: Tags und Regel-IDs“; diese Felder lassen sich mit den obigen kombinieren. Ein Scan, der Regeln benennt, meldet auch die Kriterien, die sie prüfen („Welche Kriterien ein Scan meldet“).

Auswahl nach WCAG-Ziel (runOnly.wcag)

runOnly.wcag nennt eine WCAG-Version und eine Konformitätsstufe und wählt die Regeln für die Kriterien dieses Ziels aus:

// WCAG 2.2 Level A and AA:
runDomRulesInPage(url, null, {}, { wcag: { version: '2.2', level: 'AA' } });

• version ist '2.0', '2.1' oder '2.2'; level ist 'A', 'AA' oder 'AAA' (unabhängig von Groß- und Kleinschreibung).
• Eine Regel wird ausgewählt, wenn eines der Kriterien, die sie nennt, zum Ziel gehört: in dieser Version gültig (in ihr oder davor eingeführt und weder in ihr noch davor entfernt), auf der Stufe des Ziels oder darunter, nach der Stufe, die das Kriterium in dieser Version hat. Die Stufen stammen aus WCAG_CRITERIA in @surea11y/core/wcag, das eine Stufe pro Version enthält.
• 4.1.1 Syntaxanalyse, das 2.2 entfernt hat, gehört also zu Zielen mit { version: '2.1' }, nicht aber zu solchen mit { version: '2.2' }: duplicate-id läuft beim ersten und nicht beim zweiten, wo die Versions-Tags es ausführen würden.
• Eine Regel, die kein Kriterium nennt (eine Best-Practice-Regel), gehört zu keinem Ziel. Ergänzen Sie diese mit bestPractices: true (nächster Abschnitt) oder einzelne Regeln mit tags oder includeRuleIds: Neben wcag wählen sie alle zusätzlich Regeln aus, die Vereinigung aus den Regeln des Ziels und dem, was die anderen auswählen. excludeTags, excludeRuleIds und excludeTestIds wirken wie immer danach.
• Die Version des Ziels ist das WCAG-Ziel des Laufs (engine.wcagVersion), sofern engineOptions.wcagVersion nicht gesetzt ist; seine Stufe entscheidet, welche WCAG-Zusammenfassungen gemeldet werden, wie es ein Stufen-Tag tut, sofern engineOptions.wcagLevel nicht gesetzt ist („Die Stufe eines Scans angeben, der Prüfungen benennt“).
• Ein Ziel schließt Regeln ein, wählt sie also anstelle von engineOptions.profile aus, wie es tags tun. getProfileWcagTarget(profile) liefert das Ziel, auf das ein Profil hinausläuft (siehe „Konformitätsprofile“), und getChecksForRunOnly(runOnly, engineOptions) listet die Regeln, die ein runOnly mit wcag ausführt, und getRulesForRunOnly(runOnly, engineOptions) die Zusammenfassungen, die es meldet.
• Alles andere wirft INVALID_RUN_ONLY und nennt, was falsch ist: runOnly.wcag.version must be "2.0", "2.1" or "2.2", not "3.0".

// WCAG 2.1 AA, plus the best-practice rules, without one of them:
{ wcag: { version: '2.1', level: 'AA' }, tags: ['best-practice'], excludeRuleIds: ['region'] }

Best Practices ergänzen (runOnly.bestPractices)

bestPractices: true wählt die Best-Practice-Regeln aus: die Regeln, die kein WCAG-Kriterium nennen, etwa region, landmark-one-main, heading-order, page-has-heading-one, skip-link, tabindex und image-redundant-alt. Es sind die Regeln mit dem Tag best-practice, daher ist es dasselbe, wie dieses Tag hinzuzufügen. Ein Befund einer dieser Regeln ist gute Praxis, kein WCAG-Verstoß: Keine WCAG-Zusammenfassung zählt ihn. Die meisten melden cantTell; eine, deren Befund selbst eine Barriere ist, meldet fail, wie empty-heading bei einer Überschrift ohne Namen.

• Neben wcag, tags oder Regel-IDs fügt es diese Regeln dem hinzu, was jene auswählen; Ausschlüsse wirken danach, daher lässt excludeRuleIds: ['region'] region weiterhin weg.
• Allein angegeben wählt es nur die Best-Practice-Regeln aus.
• false oder das Weglassen fügt nichts hinzu. Allein ist { bestPractices: false } eine leere Auswahl, daher laufen die Standardregeln, wie bei {}.
• Jeder andere Wert wirft INVALID_RUN_ONLY: runOnly.bestPractices must be true or false, not "yes".
• Neben engineOptions.profile fügt es die Best-Practice-Regeln denen des Profils hinzu, und das Profil gilt weiterhin: seine Regeln, seine Zusammenfassungen, seine Zuordnungen und engine.profile, wie ohne die Option. { bestPractices: true } mit profile: 'en301549-v4.1.1' führt diese Norm und die Best Practices aus. Die Best-Practice-Regeln zählen in keiner der Zusammenfassungen des Profils, da sie kein WCAG-Kriterium prüfen.

// WCAG 2.1 AA and the best practices, without one of them:
{ wcag: { version: '2.1', level: 'AA' }, bestPractices: true, excludeRuleIds: ['region'] }

Konformitätsprofile

engineOptions.profile benennt ein Konformitätsziel, statt dessen Tag-Set auszuschreiben:

getProfileWcagTarget(profile) liefert das runOnly.wcag-Ziel, auf das das Tag-Set eines Profils hinausläuft, oder null für einen Namen, der kein Profil ist. Ein Profil wählt weiterhin über seine Tags aus, wie in der Tabelle: Unter wcag22-aa läuft duplicate-id (4.1.1) und kann kein fail ergeben, während { wcag: getProfileWcagTarget('wcag22-aa') } die Regel weglässt.

runDomRulesInPage(url, null, { profile: 'en301549-v3.2.1' }, null);

Die Norm oder Checkliste eines Packs bringt eigene Profile in diese Liste ein.

Das WCAG-Ziel ergibt sich aus den Tags wie bei einem von Hand geschriebenen Set (siehe „Filtern nach WCAG-Version“ unten), daher zielt en301549-v3.2.1 auf WCAG 2.1 und en301549-v4.1.1 auf WCAG 2.2. Eine doppelte id kann unter en301549-v3.2.1 noch fail ergeben, weil sein Profil den Text von 4.1.1 beibehält (keepsParsing, siehe unten); unter en301549-v4.1.1 nicht. Das Profil eines Packs kann seine Version stattdessen mit wcagVersion nennen (Packs): Ein Profil, das nur die Regeln ausführt, die seine Norm zuordnet, hat keine WCAG-Tags, aus denen sich eine ergäbe. Bei Namen spielt Groß- und Kleinschreibung keine Rolle. Ein Lauf, der ein Profil verwendet hat, meldet es als engine.profile zurück.

Vorrang: Alles, was Regeln einschließt, wählt sie anstelle des Profils aus — ein runOnly mit wcag, tags, includeRuleIds oder includeTestIds oder ein include in engineOptions.rules/.tags/.tests. Ausschlüsse gelten weiterhin zusätzlich zum Profil, ob sie aus runOnly stammen (excludeTags, excludeRuleIds, excludeTestIds, sodass das disableTags() eines Bindings das Profil einschränkt, statt es zu ersetzen) oder, ohne runOnly-Filter, aus engineOptions (tags.exclude, rules.exclude, tests.exclude), und ein explizites engineOptions.wcagVersion hat weiterhin Vorrang vor der Version, die das Profil impliziert oder nennt. Ein Profil ohne Wirkung — ein unbekannter Name oder eines, das wie oben übersteuert wird — ist kein Fehler: Der Lauf geht weiter, als wäre keines angegeben, schreibt ein console.warn mit dem Grund und enthält kein engine.profile. runOnly.bestPractices: true ist kein solches Einschließen: Es fügt die Best-Practice-Regeln denen des Profils hinzu, und das Profil gilt („Best Practices ergänzen“).

Das Profil einer Norm kann auch Regeln weglassen, wenn seine Norm auf ein WCAG-Kriterium verzichtet oder eine WCAG-Prüfung durch eine eigene ersetzt: Die Regeln, die es nennt, die Regeln, auf deren sämtliche Kriterien es verzichtet, und die WCAG-Zusammenfassungen der erlassenen Kriterien laufen nicht, und der Regelkatalog lässt sie ebenfalls weg. Eine Regel, die auch ein Kriterium prüft, das das Profil behält, läuft weiterhin (link-name-present, das 2.4.4 und 4.1.2 prüft, unter einem Profil, das auf 2.4.4 verzichtet), und engine.profileExcludes nennt, was weggelassen wurde. Derzeit schließt kein eingebautes Profil etwas aus.

Ein Profil wählt nur aus, welche Regeln laufen. Es sagt nichts darüber aus, ob das Bestehen dieser Regeln die namensgebende Norm erfüllt: Die meisten Erfolgskriterien erfordern menschliches Urteil, das keine automatisierte Regel abdeckt (siehe was diese Engine nicht aussagen kann).

Ein EN-301-549-Profil schaltet außerdem die EN-301-549-Klauseln der angepeilten Version ein, als wäre mappings: ['en301549:V4.1.1'] (oder V3.2.1) übergeben worden; siehe „Andere Normen“ unten. Das Profil jeder Norm schaltet auf dieselbe Weise seine eigene Version ein. Ein Profil mit mappedRules führt außerdem, unabhängig von ihren Tags, die Regeln aus, denen seine Norm zugeordnet ist: Die ohne WCAG-Zuordnung, etwa heading-order und skip-link, haben kein WCAG-Tag, über das sie ausgewählt werden könnten. Eine Norm mit eigenen Anforderungen oder die Checkliste einer Organisation kommt als Pack in die Engine und bringt eigene Profilnamen, Regeln und Zusammenfassungen mit. Die Engine selbst liefert keine solche Norm mit.

Opt-in-Regeln

Manche Regeln prüfen eigene Anforderungen einer Norm, die WCAG nicht stellt: Eine nationale Norm verlangt vielleicht einen Doctype oder verbietet präsentationale Attribute wie bgcolor. Ein fail einer solchen Regel ist ein Verstoß gegen diese Norm, nicht gegen WCAG, daher sind diese Regeln standardmäßig aus. Jede trägt das Regel-Tag ihrer Norm und läuft nur, wenn die Auswahl sie anfordert:

• über das Profil der Norm, das das Tag enthält,
• über dieses Tag (tags: { include: '<tag>' }, allein oder mit anderen),
• über ihre id (rules: { include: '<rule id>' } oder runOnly.includeRuleIds),
• über die id einer eigenen Zusammenfassung ihrer Norm, die sie gruppiert (rules: { include: '<rollup id>' } führt die Regeln dieser Zusammenfassung aus, ob Opt-in oder nicht), oder
• indem sie mit engineOptions.optInRules freigeschaltet wird, siehe unten.

Nichts anderes wählt sie aus: kein Standardlauf, kein WCAG-Tag-Set, kein WCAG- oder EN-301-549-Profil, keine WCAG-Zusammenfassungs-id. Ausschlüsse gelten für sie wie für jede Regel. Wird nur das Tag ausgewählt, laufen die eigenen Regeln dieser Norm, nicht die WCAG-Regeln, denen sie ebenfalls zugeordnet ist; das beantwortet „was verlangt die Norm über WCAG hinaus“ und ist keine Prüfung gegen sie. Für eine Prüfung verwenden Sie das Profil der Norm: Unter einem Tag allein melden ihre eigenen Zusammenfassungen cantTell für jede Anforderung, deren Regeln nicht gelaufen sind. Eine über customRules hinzugefügte Regel, die das Tag trägt, unterliegt derselben Sperre. Keine der eingebauten Normen der Engine hat derzeit Opt-in-Regeln; das Namensraum-Tag eines Packs funktioniert auf diese Weise.

Alle Regeln ausführen (optInRules)

Um jede Regel der Engine auszuführen, gleich zu welcher Norm sie gehört, lassen Sie das Profil weg und schalten die Opt-in-Regeln frei:

runDomRulesInPage(url, null, { optInRules: 'all' }, null);

'all' schaltet die Opt-in-Regeln aller Normen frei; eine Liste von Tags nur diese. Die Option hebt die Sperre auf und sonst nichts: Die übrige Auswahl entscheidet weiterhin, welche Regeln laufen. Ohne Filter und ohne Profil wie oben deckt der Lauf also jede Regel und die Zusammenfassungen aller Normen ab; unter profile: 'wcag22-aa' laufen weiterhin nur die WCAG-Regeln, da Opt-in-Regeln kein WCAG-Tag tragen. Ausschlüsse gelten wie üblich. Ein Tag, das kein Opt-in-Tag ist, wird mit einem console.warn ignoriert. Nur diese Engine-Option schaltet frei: runOnly hat keinen Schlüssel optInTags, einer dort ist also ein unbekannter Schlüssel, der allein INVALID_RUN_ONLY wirft und neben Schlüsseln, die runOnly liest, mit einer Warnung ignoriert wird; die Meldung verweist auf engineOptions.optInRules.

Das ist dafür gedacht, alles zu sehen, was die Engine melden kann, während der Entwicklung oder beim Erkunden einer Website. Es ist kein Konformitätsziel: Ein solcher Lauf lässt eine Seite an Dingen scheitern, die WCAG erlaubt und nur eine andere Norm verbietet. Das Ergebnis weist darauf hin: engine.optInRules listet die Tags, deren Regeln gelaufen sind, und HTML-Bericht, SARIF und JUnit zeigen es neben dem Profil. Es fügt den Ergebnissen keine Nummern anderer Normen hinzu; übergeben Sie dafür mappings, zum Beispiel { optInRules: 'all', mappings: ['<key>'] }.

Andere Normen (mappings)

Das meta.normativeMappings jedes Ergebnisses nennt die WCAG-Erfolgskriterien, die es prüft. engineOptions.mappings fügt die entsprechende Anforderung einer anderen Norm zu jedem hinzu. Standardmäßig fügt es keine hinzu: Eine Klausel einer Norm, gegen die Sie nicht prüfen, ist Rauschen in jedem SARIF-Tag, jeder JUnit-Eigenschaft und jedem Bericht.

runDomRulesInPage(url, null, { mappings: ['en301549:V3.2.1'] }, null);

Die Option nimmt ein Array oder einen kommagetrennten String; bei Namen und Versionen spielt Groß- und Kleinschreibung keine Rolle. Unter profile: 'en301549-v4.1.1' sind die V4.1.1-Klauseln ohne Anforderung vorhanden, und mappings kann weitere hinzufügen. Ein Name oder eine Version ohne Tabelle in der Engine wird mit einem console.warn ignoriert. Ein Lauf, der eine andere Norm enthält, meldet welche in engine.mappings, in kanonischer Schreibweise (["en301549:V3.2.1"] oder ["en301549"] für alle Versionen).

Sie ändert nur, was ein Ergebnis nennt, nie welche Regeln laufen oder ihre Ergebnisse. Der Regelkatalog folgt derselben Option: getChecksCatalog(engineOptions), getCheckDefById(ruleId, engineOptions), getChecksForRunOnly(runOnly, engineOptions), getRulesCatalog(engineOptions), getRulesForRunOnly(runOnly, engineOptions) und getCompositeRuleById(id, engineOptions) nennen die Normen, die ein Scan mit diesen Optionen nennen würde, ein Profil eingeschlossen, wenn es greifen würde, sodass Katalogeintrag und Ergebnis immer übereinstimmen. Ohne Optionen nennen sie nur WCAG. Eine über customRules hinzugefügte Regel behält genau die Zuordnungen, die sie deklariert. Was die Klauseln sind und wie sich die beiden Versionen unterscheiden, steht unter WCAG-Konformitätszuordnung.

Erweiterte Auswahl: Tags und Regel-IDs

Die folgenden Felder wählen nach den Tags aus, die Regeln tragen, und nach Regel-IDs. Greifen Sie zu ihnen für das, was ein WCAG-Ziel und bestPractices nicht ausdrücken: ein einzelnes Kriterium (tags: ['wcag1412']), eine Liste von Regeln, einen Ausschluss oder ein eigenes Tag-Set. Sie lassen sich mit wcag und bestPractices kombinieren: Was sie einschließen, kommt zu dem hinzu, was jene auswählen, und was sie ausschließen, wird danach abgezogen.

Es gibt zwei voneinander unabhängige Wege, sie anzugeben: das 4. Argument (runOnly) oder engineOptions.rules/.tags/.tests/.includeMode. Enthält runOnly irgendeinen Filter, gewinnt es vollständig; andernfalls greift die Engine auf engineOptions zurück. Mischen Sie beide nicht in der Erwartung, dass beide gelten. Entscheiden Sie sich für einen. engineOptions.rules, .tags und .tests nehmen { include, exclude } an; eine einfache Liste oder ein String ist die Include-Liste.

Über runOnly (4. Argument)

runDomRulesInPage(url, null, {}, {
  includeRuleIds: ['img-alt-present', 'button-name-present'],
  excludeRuleIds: ['region'],
  tags: ['wcag412'],
  excludeTags: ['best-practice'],
  includeMode: 'and'   // 'and' (default) | 'or' — see below
});

Ein einfaches Array oder ein String funktioniert als Kurzform: runOnly: ['img-alt-present', 'button-name-present'] führt diese Regeln aus (eine Composite-ID bringt ihre Regeln mit), und runOnly: ['wcag2a', 'wcag2aa'] ist dasselbe wie { tags: ['wcag2a', 'wcag2aa'] }. Ein Array kann Regel-IDs und Tags nicht mischen, und jeder Wert muss eine Regel (eingebaut, Composite oder eine aus engineOptions.customRules) oder einen Tag benennen: Alles andere wirft einen Fehler, damit ein Tippfehler nicht unbemerkt jede Regel oder keine ausführt. Verwenden Sie die Objektform, um IDs und Tags zu kombinieren oder um auszuschließen. Vor 1.10.0 wurde ein einfaches Array ignoriert, und jede Regel lief.

Jedes dieser Felder akzeptiert entweder ein Array oder einen kommagetrennten String, passend zur engineOptions-Form weiter unten: includeRuleIds: 'img-alt-present, button-name-present' und includeRuleIds: ['img-alt-present', 'button-name-present'] sind gleichwertig.

Namen werden geprüft, hier und in engineOptions.rules/.tags weiter unten. Eine Include-Liste (includeRuleIds, includeTestIds, tags, das ältere values, rules.include, tags.include), in der kein Wert eine Regel oder einen Tag benennt (einen, den eine Regel oder eine Zusammenfassung trägt, sodass das Tag einer Norm bekannt ist, auch wenn nur ihre Zusammenfassungen es tragen), wirft einen Fehler mit code: 'INVALID_RUN_ONLY' und einer Meldung, die das Feld und die Werte nennt, denn sie würde nichts auswählen, und ein Lauf ohne Regeln liest sich wie ein Scan ohne Befunde. Eine Auswahl, deren Namen alle existieren, deren Teile sich aber gegenseitig aufheben (eine Regel, die zugleich eingeschlossen und ausgeschlossen ist, Regeln und Tags ohne gemeinsame Regel unter includeMode: 'and'), führt ebenfalls keine Regel aus: Der Scan warnt und nennt die Teile, und unter strictOptions wirft er INVALID_RUN_ONLY. includeMode ist 'and' oder 'or'; ein anderer Wert wird als 'and' gelesen, mit einer Warnung, und wirft unter strictOptions einen Fehler; in einem Browser-Binding setzt ihn .includeMode('or'). Ein Wert, der nichts benennt, neben anderen, die etwas benennen, oder in einer Exclude-Liste wird mit einem console.warn ignoriert. Vor 1.10.0 wurde jeder solche Wert stillschweigend ignoriert.

Die neun WCAG-Tags für Version und Stufe, wcag2a bis wcag22aaa, sind immer bekannt, ob eine Regel eines davon trägt oder nicht. Einige tragen derzeit keine (wcag21aaa, wcag22a, wcag22aaa): Für ihre Kriterien gibt es keine automatische Regel, und das ist kein Tippfehler. In einer Include-Liste neben anderen Werten wird ein solches Tag mit einem console.info vermerkt, nicht mit einer Warnung:

[surea11y] runOnly.tags: no rules for WCAG 2.2 Level A ("wcag22a"); its criteria need manual review.

engineOptions.logUntestedWcag: false lässt diese Zeile weg. Ist jeder Wert einer Include-Liste ein solches Tag, würde nichts laufen, daher wirft sie weiterhin INVALID_RUN_ONLY und sagt, warum. Neben einem runOnly.wcag-Ziel oder bestPractices: true, die eigene Regeln auswählen, wird es nur vermerkt. In einer Exclude-Liste bleibt es unbeachtet.

Regel-IDs stehen ohne Präfix (kein Engine-Präfix), z. B. 'img-alt-present'. Aus Gründen der Abwärtskompatibilität akzeptiert der Abgleich auch eine ältere, mit a11ycore- präfixierte Form derselben ID ('a11ycore-img-alt-present'). IDs werden wie Tags unabhängig von Groß- und Kleinschreibung abgeglichen: 'IMG-ALT-PRESENT' wählt img-alt-present aus, in jeder Liste, die Regeln nennt (runOnly in jeder Form, engineOptions.rules und engineOptions.tests, Ein- und Ausschluss). Keine zwei Regeln haben IDs, die sich nur in der Schreibweise unterscheiden, so kann das nicht die falsche auswählen.

Als gesamter runOnly-Wert wird außerdem die { type, values }-Form akzeptiert: { type: 'tag', values: ['wcag2a', 'wcag2aa'] } ist { tags: ['wcag2a', 'wcag2aa'] }, und { type: 'rule', values: ['img-alt-present'] } ist { includeRuleIds: ['img-alt-present'] } ('tags' und 'rules' funktionieren auch). values kann ein kommagetrennter String sein, seine Namen werden wie alle Regel-IDs oder Tags geprüft, und die anderen Schlüssel daneben (excludeTags, excludeRuleIds...) gelten weiterhin. Ein Set von Namen wird als die Liste gelesen, die es enthält. Ein Schlüssel, den die Objektform nicht liest, neben solchen, die sie liest, wird mit einer Warnung ignoriert. Jeder andere type wirft INVALID_RUN_ONLY, ebenso ein runOnly, das eine Zahl oder ein Boolean ist, oder ein Objekt, von dessen Keys die Engine keinen liest ({ includeRuleId: [...] }): Jeder dieser Fälle führte früher jede Regel aus. Ein leeres Array, ein leerer String oder ein leeres Objekt bedeutet weiterhin die Standardauswahl.

Welche Kriterien ein Scan meldet

Ein Scan meldet die Zusammenfassung eines Kriteriums (rulesResults), wenn die Auswahl sie auswählt: ein WCAG-Ziel oder ein Tag für Version und Stufe, ein Profil, die eigene ID der Zusammenfassung oder gar keine Auswahl. Außerdem meldet er die Zusammenfassung jedes Kriteriums, das eine von der Auswahl eigens benannte Regel prüft, wenn diese Regel gelaufen ist:

• über ihre ID (includeRuleIds, includeTestIds, rules.include oder die eigene Regelliste eines Profils),
• über ein Tag, das kein WCAG-Tag ist (das einer eigenen Regel, eines Packs oder einer Norm; die Tags der WCAG sind die Tags für Version und Stufe, die Kriteriums-Tags wie wcag244 und wcag22-removed, ein eigenes Tag wie wcagteam ist also keines),
• über optInRules oder
• als Best-Practice-Regel (bestPractices).

Eine Regel, die das Profil einer Norm nur ausführt, weil ihre Norm sie zuordnet (mappedRules), ist für diese Norm benannt, nicht eigens: Sie ergänzt die Anforderungen der Norm und keines ihrer WCAG-Kriterien. Ein Profil, das nur ausführt, was seine Norm verlangt, meldet also nur diese Norm (Packs); eine Regel, die seine rules-Liste nennt, ergänzt auch ihre WCAG-Kriterien. Vor 1.12.0 hatte ein Scan, der Regeln statt Kriterien benannte, ein leeres rulesResults.

// The unnamed link fails link-name-present, and with it 2.4.4 and 4.1.2:
runDomRulesInPage(url, null, {}, { includeRuleIds: ['link-name-present'] });
// rulesResults: wcag-2.4.4-link-purpose-in-context: fail, wcag-4.1.2-name: fail

• Das Ergebnis ist das der Zusammenfassung. Eine fehlschlagende Regel lässt das Kriterium fehlschlagen. Eine bestandene Regel lässt es nicht bestehen, wenn der Scan die übrigen Regeln des Kriteriums weggelassen hat: Es ist cantTell, mit reasonCode composite.rollup.cantTell.notSelectedChild, und jede Regel, die der Scan nicht ausgewählt hat, steht unter den Beitragenden als missing mit notSelected: true. Sind alle ausgewählt und bestanden, bleibt ein WCAG-Kriterium dennoch cantTell (composite.rollup.cantTell.partialCheck), da die Regeln noch keines Kriteriums alles prüfen, was es verlangt (siehe WCAG-Konformitätszuordnung). Der HTML-Bericht zeigt darunter „Teilweise geprüft: 1 von 2 Prüfungen war für diesen Scan nicht ausgewählt“. Siehe das Ausgabeschema.
• Ein Kriteriums-Tag benennt sein eigenes Kriterium. tags: ['wcag244'] meldet 2.4.4, nicht die anderen Kriterien, die seine Regeln prüfen (4.1.2 bei link-name-present). Eine Regel, die über die ID einer Zusammenfassung, ein WCAG-Ziel, ein Tag für Version oder Stufe oder ein WCAG-Profil hinzukommt, ergänzt kein Kriterium: Dort benennt die Auswahl die Kriterien. Ein Scan, der seine Kriterien auswählt, meldet also, was er bisher gemeldet hat.
• WCAG-Version und -Stufe des Laufs gelten. Ein Kriterium kommt nur hinzu, wenn es in engine.wcagVersion gilt (duplicate-id allein ergänzt unter 2.2 kein 4.1.1, unter wcagVersion: '2.1' schon) und auf der Stufe des Laufs oder darunter liegt, wie bei einem Ziel: engineOptions.wcagLevel, wenn angegeben (nächster Abschnitt), sonst die Stufe, die die Auswahl vorgibt (runOnly.wcag.level oder die Tags für Version und Stufe neben den Regel-IDs). Gibt es keines von beiden, wird jede Stufe gemeldet.
• Ausschlüsse gelten. Eine Zusammenfassung, die die Auswahl ausschließt (excludeRuleIds: ['wcag-4.1.2-name'] oder ein Tag), kommt nicht hinzu. Eine Regel, die Sie ausgeschlossen haben, gilt als nicht ausgewählt. Eine Regel, die ein Profil ausschließt, schränkt das Kriterium ein: Sie ist missing ohne notSelected, und ein Kriterium, auf das das Profil verzichtet, kommt nie hinzu.
• Die eigenen Zusammenfassungen einer Norm (eine pro Anforderung) kommen ebenso hinzu, aber nur, solange die Norm im Spiel ist: Das angewendete Profil zielt auf sie, oder die Auswahl nennt ihr Tag, oder optInRules schaltet sie frei. Ein WCAG-Scan zeigt nie die Anforderungen einer Norm, nach der niemand gefragt hat. Ein Profil ohne Wirkung und mappings allein bringen keine Norm ins Spiel. Unter ihrem Profil kommt nur die Version des Profils hinzu; freigeschaltet ohne Profil kommt jede Version hinzu, so wie ein über ihr Tag ausgewählter Scan sie meldet. Das gilt für eine Norm oder Checkliste aus einem Pack wie für eine eingebaute: Ein Checklistenprofil, das seine Regeln nennt (tags: [], rules: [...]), erhält deren WCAG-Kriterien und seine eigenen Punkte.
• Die Liste vor dem Scan. getRulesForRunOnly(runOnly, engineOptions) listet die Zusammenfassungen, die ein Scan mit dieser Auswahl und diesen Optionen meldet, die hinzugekommenen eingeschlossen, als Einträge von getRulesCatalog. Sie ermittelt sie mit dem eigenen Zusammenfassungsschritt des Scans, sodass beide übereinstimmen; getChecksForRunOnly listet die Regeln. getRulesCatalog(engineOptions) listet jede Zusammenfassung, die die Optionen verfügbar machen, unabhängig von der Auswahl. Ein Tool kann so festhalten, was ein Scan prüft, bevor es ihn ausführt; die Builder der Browser-Bindings liefern dieselben Listen als plannedChecks() und plannedCriteria().

Die Stufe eines Scans angeben, der Prüfungen benennt (wcagLevel)

Ein Scan, der als WCAG 2.2 AA gemeint ist und nur einige Prüfungen ausführt, benennt diese und gibt die Version in engineOptions.wcagVersion an. Damit ist keine Stufe gesagt, also werden die Kriterien dieser Prüfungen auf jeder Stufe gemeldet: contrast-computable prüft 1.4.3 (AA) und 1.4.6 (AAA), und beide werden gemeldet. engineOptions.wcagLevel gibt die Stufe an:

// Only the contrast checks of a WCAG 2.2 AA scan: 1.4.3 is reported, 1.4.6 is not.
runDomRulesInPage(url, null,
  { wcagVersion: '2.2', wcagLevel: 'AA' },
  { includeRuleIds: ['contrast-computable'] });

• Werte. 'A', 'AA' oder 'AAA', in beliebiger Schreibweise. Ein anderer Wert wird mit einem console.warn ignoriert (engineOptions.wcagLevel: ignoring "AA+"; use "A", "AA" or "AAA". ...) und wirft unter strictOptions INVALID_ENGINE_OPTIONS. Der Lauf meldet eine gültige Stufe als engine.wcagLevel, geschrieben als 'A', 'AA' oder 'AAA'; ohne die Option ist engine.wcagLevel die Stufe, die sich aus der Auswahl ergibt, und fehlt, wenn sich keine ergibt.
• Sie entscheidet, was gemeldet wird, nie, was läuft. Was läuft, entscheidet die Auswahl, wie ohne die Option. Eine Prüfung oberhalb der Stufe, die die Auswahl benennt, läuft weiterhin und meldet ihr eigenes Ergebnis; nur ihre Kriterien oberhalb der Stufe fehlen in rulesResults.
• Sie gilt für jede WCAG-Zusammenfassung, nicht nur für die Kriterien, die für benannte Prüfungen hinzukommen. wcagLevel: 'AA' bei einem vollständigen Scan, einem Profil oder einer Tag-Auswahl lässt die AAA-Kriterien aus rulesResults weg, während ihre Prüfungen weiterhin laufen und in checksResults melden. Das unterscheidet sie von wcagVersion, das nie eine Zusammenfassung entfernt, die die Auswahl auswählt: Ein 2.2-Scan meldet weiterhin 4.1.1, mit seinen Regeln zu cantTell umgewandelt. Ein Scan ohne die Option meldet, was er bisher gemeldet hat.
• Sie hat Vorrang vor der Stufe, die sich aus der Auswahl ergibt (runOnly.wcag.level oder die höchste Stufe, die ihre Tags für Version und Stufe nennen), so wie ein explizites wcagVersion Vorrang vor der Version hat, die sich aus ihnen ergibt. Vor einem Widerspruch zwischen beiden wird nicht gewarnt, ebenso wenig wie zwischen wcagVersion und der Version eines Ziels; engine.wcagLevel zeigt die Stufe, nach der die Kriterien gefiltert wurden.
• Eine per ID benannte Zusammenfassung wird wie benannt gemeldet. includeRuleIds: ['wcag-1.4.6-contrast-enhanced'] mit wcagLevel: 'AA' meldet 1.4.6: Die Option sagt, welche Kriterien gemeldet werden, nicht, dass eines wegfällt, nach dem Sie gefragt haben. Eine Stufe, die sich aus den eigenen Tags der Auswahl ergibt, filtert eine benannte Zusammenfassung weiterhin, wie ohne die Option.
• Die eigenen Zusammenfassungen einer Norm haben keine WCAG-Stufe und werden von ihr nicht gefiltert. Das Profil eines Packs kann keine Stufe angeben (seine Tags ergeben eine); wer es aufruft, kann wcagLevel übergeben.
• getRulesForRunOnly(runOnly, engineOptions) berücksichtigt sie, listet also, was der Scan meldet, und warnt bei einem ungültigen Wert wie der Scan, bzw. wirft unter strictOptions einen Fehler.

Ohne die Option ergeben auch Tags für Version und Stufe neben den Regel-IDs eine Stufe, denn der Standard includeMode: 'and' behält die benannten Regeln, die eines davon tragen: { includeRuleIds: ['contrast-computable'], tags: wcagTags('2.2') } führt contrast-computable aus und meldet nur 1.4.3. Die Tags entscheiden aber auch, was läuft: Eine benannte Regel ohne WCAG-Tag (eine Best-Practice-Regel wie region, eine eigene Regel ohne WCAG-Tags) oder eine, die nur AAA-Kriterien prüft, fällt aus dem Lauf, und ein Tag für Version und Stufe, das keine Regel trägt (wcag22a), wird mit einem console.info vermerkt. wcagLevel gibt die Stufe an, ohne zu ändern, was läuft. In einem Browser-Binding setzt sie die Builder-Methode .wcagLevel('AA').

Filtern nach WCAG-Version (2.0, 2.1, 2.2)

Jede Regel und jede zusammengesetzte Regel trägt genau ein Level-Tag für ihre WCAG-Ursprungsversion: wcag2a/wcag2aa/wcag2aaa für ein Erfolgskriterium, das schon zur Basis von WCAG 2.0 gehört, wcag21a/wcag21aa/wcag21aaa für eines, das mit WCAG 2.1 neu hinzukam (z. B. 1.3.5 Identify Input Purpose), wcag22a/wcag22aa/wcag22aaa für eines, das mit WCAG 2.2 neu hinzukam (z. B. 2.5.8 Target Size Minimum). Eine Regel erhält nur das Tag der tatsächlichen Ursprungsversion ihres Kriteriums: Ein in 2.1 eingeführtes Kriterium trägt nie zusätzlich wcag2aa, da es bei einem Konformitätsziel WCAG 2.0 gar nicht existiert.

runOnly.wcag wählt ein Konformitätsziel in einem einzigen Feld aus (oben) und lässt 4.1.1 unter 2.2 weg. Mit Tags wählen Sie, da die Versionen kumulativ sind (2.1 = 2.0 + Neues; 2.2 = 2.0 + 2.1 + Neues), ein Konformitätsziel für eine WCAG-Version durch Kombinieren von Tag-Sets aus. Den Rest erledigt der ODER-Abgleich der Engine auf tags (ein einziger Treffer schließt die Regel ein):

// WCAG 2.0 AA only (excludes every 2.1/2.2-introduced SC, even at level AA):
{ tags: ['wcag2a', 'wcag2aa'] }
 
// WCAG 2.1 AA conformance (2.0 baseline + everything 2.1 added, both at A and AA):
{ tags: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] }
 
// WCAG 2.2 AA conformance (2.0 baseline + 2.1 additions + 2.2 additions):
{ tags: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa'] }
 
// Just the SCs 2.2 introduced, nothing else:
{ tags: ['wcag22a', 'wcag22aa', 'wcag22aaa'] }

Ein Kriterium geht den umgekehrten Weg. WCAG 2.2 hat Erfolgskriterium 4.1.1 „Syntaxanalyse“ entfernt, das einzige Kriterium, das je gestrichen statt hinzugefügt wurde. Eine darauf abgebildete Regel trägt wie jede andere Basisregel ihr 2.0-Ursprungs-Tag (wcag2a) und zusätzlich wcag22-removed. Die obigen Versions-Tag-Sets schließen sie deshalb auch bei einem 2.2-Ziel ein, wo sie nicht hingehört.

Sie müssen dafür nichts tun. Die Engine ermittelt für jeden Lauf eine WCAG-Zielversion, und ist dieses Ziel 2.2, kann eine Regel mit wcag22-removed kein fail melden: Sie läuft weiterhin, meldet weiterhin jedes gefundene Vorkommen, aber ihr Ergebnis wird zu cantTell umgewandelt, und das Ergebnis enthält ein Feld wcagVersionScope, das den Grund nennt (siehe das Ausgabeschema). Nichts fällt stillschweigend weg, und ein 2.2-Lauf wird nicht durch ein Kriterium blockiert, das es in 2.2 nicht gibt.

Bei einem 2.0- oder 2.1-Ziel gilt dasselbe: Die Errata von 2023 zu WCAG 2.0 und 2.1 werten 4.1.1 für Inhalte in HTML oder XML als immer erfüllt, daher fragt die Regel nach, statt fehlzuschlagen, und wcagVersionScope.by ist "errata". Die einzige Ausnahme ist ein Profil, dessen Norm den Text von 4.1.1 beibehält, etwa en301549-v3.2.1 (keepsParsing im Profil der Norm, siehe Packs): Dort kann eine doppelte id noch fail ergeben. Ab core 1.14.0; davor ließ ein 2.0- oder 2.1-Ziel sie fehlschlagen.

Die Zielversion wird in dieser Reihenfolge ermittelt:

1. engineOptions.wcagVersion: '2.0', '2.1' oder '2.2', sofern Sie es setzen.
2. Das wcagVersion des Pack-Profils, das der Lauf anwendet, falls es eines nennt: Eine Norm auf Basis von WCAG 2.1, deren Profil nur die Regeln ausführt, die sie zuordnet, wählt kein WCAG-Tag aus und nennt die Version daher selbst. Es hat Vorrang vor der Version, die sich aus den eigenen Tags des Profils ergibt. Ein Profil ohne Wirkung (von einer eigenen Auswahl übersteuert) bringt keine Version mit.
3. Die Version eines runOnly.wcag-Ziels.
4. Die Versionsursprungs-Tags in Ihrem eigenen Filter: Ein Set, das bei wcag21a/wcag21aa endet, gilt als 2.1-Ziel, eines mit irgendeinem wcag22*-Tag als 2.2, eines nur mit wcag2*-Tags als 2.0. Nur diese neun Tags zählen; ein Kriteriums-Tag (wcag411) oder best-practice sagt nichts über eine Version aus.
5. Andernfalls '2.2', das Standardziel dieser Engine.

// Nothing to declare: a plain run already targets 2.2, so a duplicate id
// comes back cantTell rather than fail.
runDomRulesInPage(url, null, {}, null);
 
// Conformance-testing against 2.1, where SC 4.1.1 still exists:
runDomRulesInPage(url, null, { wcagVersion: '2.1' }, null);
 
// Same thing, implied by the tag set — no extra option needed:
runDomRulesInPage(url, null, {}, { tags: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] });

Die ermittelte Zielversion steht in jedem Ergebnis als engine.wcagVersion, sodass Sie prüfen können, welche ein Lauf tatsächlich verwendet hat.

Wenn Sie die Regel unter 2.2 lieber gar nicht sehen möchten, schließen Sie sie ausdrücklich aus. Genau dafür ist das Tag weiterhin da:

// WCAG 2.2 AA conformance, with the removed criterion left out entirely:
{
  tags: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa'],
  excludeTags: ['wcag22-removed']
}

duplicate-id ist derzeit die einzige Regel mit diesem Tag. Bleibt sie drin, meldet sie weiterhin etwas Reales (eine doppelte ID macht <label for>, Fragment-Links und getElementById kaputt, ganz gleich, was der Standard sagt), es ist nur kein Konformitätsverstoß gegen 2.2.

Über engineOptions (ohne runOnly)

Dieselbe Filterung, ausgedrückt als kommagetrennte Strings (oder Arrays) innerhalb von engineOptions:

runDomRulesInPage(url, null, {
  rules: { include: 'img-alt-present, button-name-present', exclude: 'region' },
  tags: { include: 'wcag412', exclude: 'best-practice' },
  includeMode: 'and'
}, null);

rules.include/.exclude, tags.include/.exclude, tests.include/.exclude (Alias von rules) und includeMode auf oberster Ebene entsprechen genau den runOnly-Feldern oben. Kommagetrennte Strings werden automatisch getrimmt, dedupliziert und von leeren Einträgen befreit. Eine einfache Liste oder ein String, etwa rules: ['img-alt-present'], wird als Include-Liste gelesen.

engineOptions: der Rest

const engineOptions = {
  strictOptions: false,            // default false — true throws on an unknown option or a value of the wrong type
  locale: 'en',                    // default 'en'; de-DE falls back to de, then to en per string
  wcagVersion: '2.2',              // default '2.2' — the conformance target
  wcagLevel: 'AA',                 // optional — the level of the criteria reported
  profile: 'wcag22-aa',            // optional — a named conformance target
  mappings: ['en301549'],          // optional — standards besides WCAG to name on each result
  optInRules: 'all',               // optional — also run rules other standards add beyond WCAG
  messages: { de: { /* key: text */ } },  // optional caller-supplied dictionaries; win over built-in ones
  includeHiddenElements: false,    // default false — set true to evaluate hidden/collapsed subtrees too
  includeShadowDom: true,          // default true — opt OUT with false to skip open shadow roots
  fragment: false,                 // default false — set true when the scan target isn't a real page
  excludeSelectors: ['#cookie-banner', '.third-party-widget'],  // array or comma-separated string
  styleSheetTexts: [{ href: 'https://cdn.example/site.css', text: '/* its CSS */' }],  // sheets the page can't read
  timestamp: '2026-07-20T12:00:00Z',  // optional — engine has no built-in clock
  perfStats: false,                // default false — internal timing counters, debug-only shape
  profileRules: false,             // default false — per-rule timings; needs perfStats
 
  contrast: {
    mode: 'strictConformance',     // 'strictConformance' (default) | 'auditorAssist'
    rootCanvasFallback: '#ffffff', // a canvas to measure on in place of the page's own; unset, the page's color scheme gives it
    rootCanvasFallbackSet: true    // echoed on each result: whether rootCanvasFallback was given; read back, false means the default
  },
  visibilityMode: undefined,       // 'styleOnly' | 'styleAndGeometry'; unset: geometry with a layout, else styles
 
  policyContract: 'a11y',          // 'a11y' (default) | 'generic' | inline contract object
  policy: {                        // optional overrides on top of policyContract
    coerceManualFailToCantTell: true
  },
 
  output: {
    includeSelector: true,         // set false to suppress auto-filled selectors
    includeHtml: true,
    detail: 'full'                 // 'findings': pass/notApplicable results keep only rule, outcome, type
  },
 
  rules: {
    'some-rule-id': {
      excludeSelectors: ['.some-noisy-widget']  // narrows candidates for THIS rule only
    }
  },
 
  probes: { /* optional host-supplied evidence */ },
 
  customRules: [ /* runtime-registered rules, see below */ ],
  packs: [ /* rules and standards from outside core, see Packs */ ],
 
  // Only read by runa11yCoreAcrossFrames. Ignored by runDomRulesInPage/runa11yCoreInPage.
  pingWaitTime: 500,               // ms to wait for a child frame to answer a ping
  frameWaitTime: 60000             // ms to wait for a child frame's full scan result
};

Fehler in den Optionen abfangen (strictOptions)

Eine Option, die die Engine nicht liest, wird durchgereicht: Eine eigene Regel kann eigene Einstellungen aus ctx.engineOptions lesen, und eine in einem späteren Release entfernte Option bricht keinen Scan. Standardmäßig wird eine falsch geschriebene Option daher ignoriert, und der Scan läuft, als wäre sie nicht da. Zwei Dinge weisen darauf hin:

• Immer gibt es eine Warnung zu einem Schlüssel, der ein oder zwei Buchstaben von einem bekannten entfernt ist (unabhängig von Groß- und Kleinschreibung), verschachtelte Schlüssel eingeschlossen: lcoale erhält [surea11y] engineOptions: unknown option "lcoale" (did you mean "locale"?); ignored.
• Immer gibt es eine Warnung zu einem Wert vom falschen Typ, und er wird als nicht angegeben gelesen, ebenso ein engineOptions, das kein Objekt ist. Ein/Aus-Optionen (includeShadowDom, includeHiddenElements, fragment, perfStats, profileRules, output.includeHtml, output.includeSelector) nehmen true oder false an, oder 'true', 'false', '1', '0', 1 und 0, so wie eine Kommandozeile sie schreibt: perfStats: 'false' ist aus.
• Mit strictOptions: true (oder 'true', '1' oder 1) wird jede Option vor dem Scan geprüft, und jeder Fehler wirft einen Fehler mit code: 'INVALID_ENGINE_OPTIONS', der jeden davon nennt, wobei problems sie als { path, kind, message, suggestion } auflistet: ein unbekannter Schlüssel (kind: 'unknown') in engineOptions oder in einem seiner Objekte und ein Wert vom falschen Typ oder außerhalb seiner Menge (kind: 'invalid'), etwa includeHiddenElements: 'yes' oder contrast.mode: 'strict'.

runDomRulesInPage(url, null, { strictOptions: true, lcoale: 'de' }, null);
// Error: engineOptions: unknown option "lcoale" (did you mean "locale"?). (strictOptions)

Die Katalogfunktionen, die engineOptions entgegennehmen (getChecksCatalog, getRulesCatalog, getCheckDefById, getCompositeRuleById, getChecksForRunOnly, getRulesForRunOnly, getTestsForRunOnly), prüfen sie auf dieselbe Weise und mit denselben Worten: getRulesForRunOnly(runOnly, { wcagLevel: 'AA+' }) warnt, behandelt die Stufe als nicht angegeben und listet, was ein Scan mit diesen Optionen meldet; mit strictOptions: true wirft sie INVALID_ENGINE_OPTIONS, wie der Scan. Eine Auswahl, die sich selbst aufhebt (eine Regel zugleich ein- und ausgeschlossen, Teile ohne gemeinsame Regel), wird so gemeldet, wie der Scan sie meldet: mit einer Warnung und unter strictOptions mit INVALID_RUN_ONLY.

Nicht geprüft werden: die eigenen Einstellungen einer Regel (rules[ruleId]), die Schlüssel von messages und probes, die die Engine ungelesen weitergibt, sowie die eigenen Regeln, die eigene Prüfungen haben (skippedCustomRules). In TypeScript ist StrictEngineOptions dieselbe Menge von Optionen ohne die Index-Signatur, mit der jeder Schlüssel kompiliert, daher ist eine falsch geschriebene Option auch dort ein Fehler.

excludeSelectors pro Regel

Das excludeSelectors auf oberster Ebene gilt für jede Regel. Damit lässt sich ein Element nicht von nur einer Regel ausschließen, während alle anderen Regeln weiterhin dagegen laufen. rules[ruleId].excludeSelectors schließt diese Lücke: Es grenzt die Kandidaten nur für diese eine Regel ein, zusätzlich zur globalen Liste (nie an ihrer Stelle).

const engineOptions = {
  excludeSelectors: ['#cookie-banner'],   // applies to every rule, as always
  rules: {
    'aria-required-children': {
      excludeSelectors: ['mat-select', 'mat-stepper', 'mat-horizontal-stepper', 'mat-vertical-stepper']
    },
    'aria-allowed-attr': {
      excludeSelectors: ['mat-progress-spinner']
    }
  }
};

Wozu das gut ist: <mat-select> aus Angular Material baut seine interne ARIA-Struktur so auf, dass speziell bei aria-required-children ein falsch positives Ergebnis entsteht, obwohl die Komponente ansonsten in Ordnung ist. Mit nur dem globalen excludeSelectors lässt sich dieses falsch positive Ergebnis nur über excludeSelectors: ['mat-select'] unterdrücken. Das verbirgt mat-select aber auch vor allen anderen Regeln, darunter contrast-minimum und aria-allowed-attr, und lässt damit stillschweigend echte Abdeckung wegfallen, mit der diese Prüfungen nie ein Problem hatten. Das Beispiel oben hält mat-select für jede Regel vollständig sichtbar, außer für die eine, die dort fälschlich anschlägt.

Die wirksamen Ausschlüsse für eine Regel sind die Vereinigung aus der globalen Liste und der eigenen Liste der Regel: Ein Element, auf das eine der beiden passt, fällt aus den Kandidaten dieser Regel heraus. Eine Regel, deren einzige Elemente, die sonst fail ergeben würden, alle auf diese Weise ausgeschlossen sind, meldet outcome: 'pass' oder 'notApplicable' (je nach eigener Konvention der Regel für den Fall ohne Kandidaten) mit occurrences: [], nie outcome: 'fail' mit leerem occurrences-Array, denn das fail einer eingebauten Regel nennt immer, was fehlgeschlagen ist. (Eine Regel, die eine Exception wirft, ist ein anderer Fall: Sie meldet cantTell mit gesetztem error, siehe das Ausgabeschema.)

Akzeptiert dieselben Formen wie die globale Option: ein Array (['mat-select', 'mat-stepper']) oder einen kommagetrennten String ('mat-select, mat-stepper').

Wenn Sie ein Binding-Paket verwenden (@surea11y/binding-base und seine Wrapper für Playwright/Puppeteer), prüfen Sie in der README des jeweiligen Bindings, ob dessen Builder-Methode .exclude() schon eine Form pro Regel hat. Diese engineOptions-Struktur ist hier auf Engine-Ebene dokumentiert; nicht jedes Binding hat sie bereits übernommen.

Rezepte: Optionen für reale Szenarien kombinieren

CI-Gate: nur WCAG 2.2 AA, ein Drittanbieter-Widget ignorieren, das Sie nicht kontrollieren

runDomRulesInPage(url, null, {
  excludeSelectors: ['#cookie-banner', '.intercom-launcher']
}, { wcag: { version: '2.2', level: 'AA' } });

Ergänzen Sie bestPractices: true neben wcag, um auch die Best-Practice-Regeln auszuführen, die ein WCAG-Gate üblicherweise meldet, ohne daran zu scheitern. Einige davon können fail ergeben (empty-heading), sodass ein Gate, das bei jedem fail scheitert, auch an ihnen scheitert.

Manuelles Audit: gründliche Kontrastprüfung im echten Browser: etwas Schutz vor falsch positiven Ergebnissen gegen mehr Befunde eintauschen. Im echten Browser prüfen die Kontrastregeln bereits das Layout, nicht nur die berechneten Styles, daher muss nur der Kontrastmodus gesetzt werden. Gezeigt mit page.evaluate von Puppeteer (akzeptiert mehrere Argumente); mit Playwright fassen Sie die vier Positionsargumente zuerst in einem einzigen Objekt zusammen, siehe INTEGRATION.md:

const result = await page.evaluate(runa11yCoreInPage, url, null, {
  contrast: { mode: 'auditorAssist' }
}, null);

Eingegrenzter erneuter Scan eines Bereichs nach einer UI-Änderung, ohne Shadow DOM: nützlich in einem Komponententest, bei dem Sie nur das gerade geänderte Widget interessiert:

runDomRulesInPage(url, '#checkout-form', {
  includeShadowDom: false
}, { includeRuleIds: ['form-control-programmatic-label-present', 'button-name-present'] });

Ausgabe für Snapshot-Tests: Legen Sie einen timestamp fest, damit sich der Zeitstempel des Ergebnisses zwischen Läufen nicht ändert, und lassen Sie perfStats und profileRules aus: Ihre Laufzeiten schwanken, und ihre Form gehört nicht zur stabilen Ausgabe. Ein Snapshot braucht außerdem bei jedem Lauf dasselbe DOM, dieselben Optionen und dieselben Rendering-Bedingungen (Browser, Viewport, Schriften); der Zeitstempel allein macht zwei Ergebnisse nicht identisch.

runDomRulesInPage(url, null, {
  timestamp: '2026-01-01T00:00:00Z'
}, null);

Eine eigene, organisationsspezifische Regel neben den eingebauten, nur für diesen einen Aufruf:

runDomRulesInPage(url, null, {
  customRules: [{
    id: 'org-no-inline-onclick',
    meta: { title: 'No inline onclick handlers', defaultSeverity: 'moderate' },
    runInPage(ctx) {
      // queryAllSmart applies excludeSelectors, the scope's shadow roots and
      // the hidden-content filter; queryAll is the plain light-DOM query.
      // ctx.helpers.dom reads the DOM so the page's markup can't redirect it.
      const dom = ctx.helpers.dom;
      const els = ctx.helpers.queryAllSmart('[onclick]');
      const occurrences = els.map((el) => ({
        selector: ctx.helpers.buildSelector(el),
        html: dom.outerHTML(el),
        summary: 'Inline onclick handler found.',
        hint: 'Move event handling into an external script.'
      }));
 
      return { ruleId: ctx.rule.ruleId, outcome: occurrences.length ? 'fail' : 'pass', severity: 'moderate', occurrences };
    }
  }]
}, null);

customRules: zur Laufzeit registrierte Regeln

Jede ausgelieferte Regel wird beim Build fest in src/core.js eingebaut. engineOptions.customRules ist der Ausweg zur Laufzeit: ein Array von Regel-Deskriptoren, die nur für diesen einen Aufruf registriert werden. Dem statischen Katalog wird nichts hinzugefügt, und zwischen Aufrufen bleibt nichts erhalten. Die Katalogfunktionen nehmen dieselben engineOptions entgegen und listen, was ein Scan mit ihnen enthält: getChecksCatalog(engineOptions) listet die gültigen eigenen Regeln, jede Überschreibung an der Stelle ihrer eingebauten Regel, getCheckDefById(id, engineOptions) findet sie, getChecksForRunOnly(runOnly, engineOptions) wählt sie so aus wie der Scan, und getRulesForRunOnly(runOnly, engineOptions) listet die Zusammenfassungen, die sie ergänzen. Das ist Absicht und keine Einschränkung, die es zu umgehen gilt: surea11y nimmt ohnehin bei jedem Aufruf frische engineOptions entgegen, ohne veränderbare globale Konfiguration, und eigene Regeln folgen demselben Modell pro Aufruf.

Die Bibliothek direkt aufzurufen ist ein Weg; die CLI bietet das auch über --custom-rules <path> (eine lokale Datei, einmal pro Scan geladen), siehe die CLI-Dokumentation.

Eine eigene Regel läuft, wie die eines Packs, nach den eingebauten Regeln, und die ctx.helpers, ctx.engineOptions und ctx.inputs.probes, die sie erhält, sind schreibgeschützt: Etwas darauf zu setzen oder zu löschen wirft einen Fehler (die Regel wird mit diesem Fehler als cantTell gemeldet), sodass sie nicht ändern kann, was andere Regeln sehen. Sie darf die Seite nicht verändern: Eine, die es tut, wird in einem console.warn genannt. Die Ergebnisse behalten die Reihenfolge des Katalogs. Was immer sie wirft oder zurückgibt, der Scan liefert ein Ergebnis, und das Ergebnis der Regel wird zu einfachen Daten gemacht, sodass sich das Ergebnis des Scans als JSON schreiben und klonen lässt.

Ein Deskriptor hat dieselbe Form wie der Export eines internen Regelmoduls: Wenn Sie schon wissen, wie man eine Regeldatei für diese Engine schreibt, kennen Sie diese API bereits:

{
  id: 'my-org-custom-rule',          // required
  meta: { title, description, tags, defaultSeverity, defaultConfidence, /* same fields as a rule module's meta */ },
  runInPage(ctx) { /* same ctx shape and same return contract as any built-in rule */ },
  applicability(ctx) { return true; }, // optional, same contract as a built-in rule's applicability
  data: { /* optional, JSON-serializable */ }
}

• runInPage/applicability kann eine echte Funktion oder ein Funktionsquelltext als String sein (also fn.toString()). Übergeben Sie eine echte Funktion, wenn engineOptions den aktuellen JS-Realm nie verlässt (reine Nutzung mit Node/jsdom). Übergeben Sie einen String, wenn es ihn verlässt, z. B. bei einem Aufruf page.evaluate(runa11yCoreInPage, { engineOptions }) in Playwright, bei dem engineOptions eine JSON- bzw. Structured-Clone-Grenze überquert, die keine lebende Function-Referenz transportieren kann, wohl aber einen String. Die Engine rekonstruiert einen String über new Function, denselben Mechanismus, mit dem der Build den Quelltext jeder eingebauten Regel in den In-Page-Runner einbettet. Der Quelltext jeder Funktion funktioniert: eine Pfeilfunktion, eine function-Deklaration oder eine Methode in Kurzschreibweise wie im Beispiel oben (runInPage(ctx) {…}, auch async), deren toString() für sich allein kein Ausdruck ist. Die Rekonstruktion setzt voraus, dass eval erlaubt ist; eine Seite, deren Content Security Policy 'unsafe-eval' verbietet, überspringt daher eine als String übergebene Regel, und deren Grund in skippedCustomRules nennt die Policy als Ursache. Übergeben Sie dort eine echte Funktion.
• meta erhält dieselben Standardwerte und dieselbe Validierung wie eine Regel aus dem Build. Lassen Sie weg, was Sie nicht brauchen; defaultSeverity ist standardmäßig moderate, defaultConfidence medium, type automatic usw. Ein Wert außerhalb seiner Menge (minor/moderate/serious/critical; high/medium/low; automatic/manual, Groß- und Kleinschreibung egal) ist ein meta, das die Validierung nicht besteht, und die Regel wird übersprungen. Eine severity, die eine Regel außerhalb der Menge zurückgibt, wird durch ihren Standardwert ersetzt, mit einem Hinweis in error.
• Eine eigene Regel, deren id mit einer eingebauten kollidiert, überschreibt diese für den jeweiligen Scan, statt dass beide laufen. Da eine gleichnamige eigene Regel genauso gut eine versehentliche Kollision wie ein gewolltes Überschreiben sein kann, wird jede Kollision auf zwei Wegen sichtbar gemacht: durch ein console.warn mit der oder den IDs und durch ein Array overriddenBuiltinIds auf oberster Ebene des Ergebnisses (leer, wenn es keine Kollision gibt). Siehe das Ausgabeschema. IDs werden unabhängig von Groß- und Kleinschreibung abgeglichen: Eine eigene Regel IMG-ALT-PRESENT überschreibt img-alt-present und übernimmt dessen ID, und eine zweite Warnung nennt beide Schreibweisen.
• Eine eigene Regel, die gelaufen ist, zählt für die WCAG-Zusammenfassung (rulesResults) jedes Kriteriums, dem sie über meta.wcagSc oder einen WCAG-Eintrag in meta.normativeMappings zugeordnet ist, genau wie eine eingebaute Regel: Schlägt sie fehl, schlägt die Zusammenfassung fehl. Die Zusammenfassung kennzeichnet sie unter ihren beitragenden Regeln mit custom: true und listet sie in data.details.customChecksIds. Eine eigene Regel, die die Auswahl eigens benennt (über ihre ID oder eines ihrer Tags) und die gelaufen ist, meldet die Zusammenfassungen ihrer Kriterien, auch wenn die Auswahl keines davon nennt („Welche Kriterien ein Scan meldet“). Eine Überschreibung zählt dort, wo ihre eigene Zuordnung es sagt: an der Stelle ihrer eingebauten Regel, wenn sie diesem Kriterium zugeordnet ist, und in keiner Zusammenfassung, wenn sie keinem zugeordnet ist, mit einer Warnung, die die verlassenen Zusammenfassungen nennt.
• Eine eigene Regel wird wie eine eingebaute ausgewählt, über ihre ID und ihre meta.tags. Ein runOnly, das eine eigene Regel nennt, die der Scan übersprungen hat, wirft INVALID_RUN_ONLY mit dem Grund, aus dem sie übersprungen wurde. customRules ist eine Liste: Eine einzelne, allein übergebene Regel wird nicht ausgeführt und in skippedCustomRules aufgeführt. Unter einem Profil oder einem WCAG-Ziel gehört eine Regel mit dem Tag best-practice oder ohne WCAG-Tag nicht zum Lauf: Sie wird mit einem console.warn in skippedCustomRules aufgeführt und läuft, wenn Sie ihr die Tags der Kriterien geben, die sie prüft ('wcag111'), oder runOnly.bestPractices: true ergänzen. Eine eigene Regel, die die Auswahl ausschließt (excludeRuleIds: ['org-b'], rules.exclude …), steht dort ebenfalls, mit dem Grund excluded by the selection. und excluded: true, ohne Warnung. Eine Überschreibung läuft überall dort, wo ihre eingebaute Regel gelaufen wäre.
• Eine eigene Regel kann wie eine eingebaute eine Marge melden: Deklarieren Sie meta.margin ({ measure, unit, limit }) und geben Sie marginCandidates zurück (siehe RULE_AUTHORING.md, meta.margin, die Anleitung zum Schreiben von Regeln auf GitHub). Ein fehlerhaftes meta.margin wird ignoriert, diese Regel meldet dann keine Marge; der Scan läuft weiter.
• Ein ungültiger Deskriptor (fehlende oder nicht als String angegebene id, ein runInPage, das weder eine Funktion noch ein rekonstruierbarer Quelltext-String ist, eine applicability, die sich nicht in eine Funktion umwandeln lässt, ein meta, das die Validierung nicht besteht, etwa deprecated: true ohne deprecation, eine ID, die schon eine andere eigene Regel in der Liste hat, oder die ID einer Composite-Regel) wird mit einem console.warn übersprungen, das die Regel und den Grund nennt, und im skippedCustomRules des Ergebnisses aufgeführt. Der Rest des Scans, einschließlich jeder eingebauten Regel, läuft ganz normal weiter. Das ist keine zu schließende Validierungslücke: Eine eigene Regel ist beliebiger, vom Aufrufer gelieferter Code, daher ist „nur diesen einen Eintrag verwerfen, den Scan nicht abbrechen“ der sicherere Standard. Das entspricht dem Umgang mit einer eingebauten Regel, die eine Exception wirft: Sie wird auf ein cantTell für diese Regel begrenzt, statt den Lauf abstürzen zu lassen.
• Regeln laufen synchron. Ein runInPage oder applicability, das ein Promise zurückgibt (eine async-Funktion), wird als cantTell gemeldet, mit einem error, der das sagt, ebenso ein runInPage, das etwas anderes als ein Ergebnisobjekt zurückgibt. Ein outcome außerhalb von pass, fail, cantTell und notApplicable (etwa 'failed') wird zu cantTell, und error nennt den zurückgegebenen Wert. Der type einer Regel stammt aus ihrem meta: Ein type in ihrer Rückgabe wird ignoriert, mit einem Hinweis in error.
• Ergebnisse erscheinen in checksResults genau wie die jeder anderen Regel, einschließlich des automatischen Ausfüllens von selector/html/structuralPath für fail/cantTell-Vorkommen, die nur { __node } anhängen (siehe das Ausgabeschema).
• Ein fail nennt, was fehlgeschlagen ist. Das fail einer eigenen Regel ohne Vorkommen (ein Fehlschlag der ganzen Seite) wird mit einem Vorkommen am Dokumentelement gemeldet (selector: 'html', Reason-Code FAIL_WITHOUT_OCCURRENCE), sodass JUnit, SARIF, Baselines und der HTML-Bericht es als den Fehlschlag zeigen, der es ist.

Packs: Regeln und Normen von außerhalb von core

Ein Pack bringt Regeln, Varianten der Regeln von core, eine Norm oder eine Checkliste und die Meldungen, die sie verwenden, aus einem eigenen Paket mit, ohne einen Build von core. Übergeben Sie Packs einem Scan in engineOptions.packs; der Scan läuft auf einer Engine, die mit ihnen vorbereitet wurde, in denselben Schritten, die der Build für die eigenen Regeln von core verwendet, sodass sich Norm, Profile, Zusammenfassungen und Opt-in-Regeln eines Packs wie eingebaute verhalten. Die Engine wird für den nächsten Scan mit denselben Pack-Objekten behalten, sodass ein Crawl, der jeder Seite dieselben Packs übergibt, sie nur einmal vorbereitet.

const { runDomRulesInPage, getChecksCatalog } = require('@surea11y/core');
const acmePolicy = require('./acme-policy-pack');
 
const result = runDomRulesInPage(url, null, { packs: [acmePolicy], profile: 'acme-web-2026' });
result.engine.packs; // ['@acme/a11y-policy@1.0.0']
getChecksCatalog({ packs: [acmePolicy] }); // core's rules and the pack's

Ein Pack, das nicht zu core passt (sein core-Bereich schließt diese Version aus, eine Regel-ID ohne den Namensraum, ein Wörterbuchschlüssel, den core hat), wird mit einem console.warn übersprungen, im skippedPacks des Ergebnisses als { name, reason } aufgeführt, und der Scan läuft ohne es; unter strictOptions wirft er einen Fehler mit code: 'INVALID_ENGINE_OPTIONS'. Packs, die miteinander kollidieren, werfen einen Fehler. In einer Seite wird ein Pack zuerst mit packScript(packs) registriert und in engineOptions.packs als name@version genannt. Was ein Pack enthält, wie man eines aus jedem Binding, den Test-Matchern und der CLI verwendet und wie man eines schreibt, steht unter Packs.

contextSelector (2. Runner-Argument, kein Feld von engineOptions)

Ein CSS-Selektor (oder ein Array von Selektoren), der den Scan auf einen oder mehrere Teilbäume eingrenzt. Aufgelöst über document.querySelectorAll (alle Treffer, nicht nur der erste). Übergeben Sie null, um das ganze Dokument zu scannen.

• Ein Selektor ohne Treffer scannt nichts. Jede Regel meldet notApplicable, auch die seitenweiten, und das contextMatch des Ergebnisses sagt es: { elementCount: 0, unmatchedSelectors: ['#mian'] } (siehe das Ausgabeschema). Der Lauf gibt außerdem ein console.warn aus. Ein Scope, den die Seite nicht hat, wird nicht auf die ganze Seite ausgeweitet: Ein Ergebnis für Inhalte, nach denen Sie nie gefragt haben, darunter ein seitenweites pass, würde sich wie ein Ergebnis für den Teil lesen, nach dem Sie gefragt haben. In einem Array wird ein Selektor ohne Treffer in unmatchedSelectors aufgeführt, während die anderen wie gewohnt gescannt werden; Inhalte, die nur manchmal auf der Seite sind, etwa ein Cookie-Banner, können also in der Liste stehen. Vor 1.10.0 fiel ein Scope ohne Treffer auf das ganze Dokument zurück, ohne dass das Ergebnis es erwähnte.
• Ein Selektor, den der Browser nicht parsen kann, wirft einen Fehler, allein oder in einem Array, bevor irgendeine Regel läuft: contextSelector: "#main[" is not a valid CSS selector. Der Fehler trägt code: 'INVALID_CONTEXT_SELECTOR' und selector, den fehlgeschlagenen Selektor. Anders als ein Selektor ohne Treffer ist er immer ein Fehler im Aufruf. runa11yCoreAcrossFrames lehnt mit demselben Fehler ab. Ein Fehler, der page.evaluate (Playwright, Puppeteer) überquert, behält nur seine Meldung; deshalb nennt die Meldung die Option und den Selektor. Vor 1.10.0 wurde ein ungültiger Selektor übersprungen, allein angegeben scannte er also das ganze Dokument.
• Alles außer einem Selektor, einem Array von Selektoren oder null wirft denselben Fehler und nennt, was übergeben wurde: ein Element, eine NodeList, ein Objekt { include, exclude }, eine Zahl oder ein Array-Eintrag, der kein String ist (contextSelector[1] must be a CSS selector, not the number 5.). Übergeben Sie stattdessen einen Selektor, der auf das Element passt, und setzen Sie, was ein exclude weglassen würde, in engineOptions.excludeSelectors.
• Ein einzelner String kann selbst eine kommagetrennte Selektorliste sein (normale CSS-Vereinigungssemantik): '#a, #b' scannt sowohl #a als auch #b.
• Ein Array von Strings scannt die Vereinigung der Treffer aller Selektoren: ['#a', '.card'] verhält sich genauso wie '#a, .card'; die Array-Form gibt es für Aufrufer, die die Liste programmatisch aufbauen.
• Shadow DOM. Mit includeShadowDom (Standard) umfasst ein Scope die Shadow Roots in ihm, und ein Scope, der selbst ein Shadow Host ist, umfasst seine eigene Shadow Root. Der Selektor wird gegen das Dokument abgeglichen, kann also kein Element innerhalb einer Shadow Root auswählen; grenzen Sie stattdessen auf ihren Host ein.
• Überlappende bzw. verschachtelte Bereiche werden automatisch dedupliziert: Ein Element, das von mehr als einer gefundenen Wurzel aus erreichbar ist, wird nur einmal gemeldet, nicht einmal pro Bereich.
• Was ein eingegrenztes Ergebnis bedeutet. Die meisten Regeln beurteilen jedes Element für sich und beurteilen die Elemente im Scope genau wie in einem Scan der ganzen Seite. Zwei Arten von Regeln hängen von der Seite um sie herum ab. Seitenweite Regeln (page-title-present, landmark-one-main und die übrigen, die oben unter fragment aufgeführt sind) melden notApplicable. Regeln, die Elemente über die Seite hinweg vergleichen (landmark-unique, landmark-no-duplicate-banner, -contentinfo und -main, landmark-banner-is-top-level, -complementary-, -contentinfo- und -main-is-top-level, accesskeys, heading-order, identical-links-same-purpose, identical-iframes-same-purpose), melden weiterhin, was sie im Scope finden, denn zwei Landmarks, die dort einen Namen teilen, teilen ihn auf jeder Seite, melden aber notApplicable statt pass: Der Scan hat nur einen Teil der Seite gesehen und kann daher nicht sagen, dass die Seite in Ordnung ist. duplicate-id und duplicate-id-aria vergleichen jedes Element im Scope mit dem ganzen Dokument, da sein Duplikat außerhalb des Scopes liegen kann, und melden ein Element im Scope, dessen ID irgendwo sonst vorkommt. Ihr pass bedeutet, dass kein Element im Scope seine ID mit einem anderen Element der Seite teilt; ein Duplikatpaar ganz außerhalb des Scopes wird, wie bei jeder Regel, nicht gemeldet, es sagt also nicht, dass die ganze Seite frei von Duplikaten ist. target-size-minimum beurteilt die Ziele im Scope gegen Nachbarn irgendwo im Dokument, da die Abstands-Ausnahme davon abhängt, was die Seite neben ein Ziel setzt. text-spacing-content-loss beurteilt den Text im Scope und prüft, ob er Text irgendwo auf der Seite zu überlappen beginnt.