Überblick

Barrierefreiheitstests, die Ihnen sagen, was sie nicht beurteilen können.

Deterministische Barrierefreiheitstests für Playwright, Cypress, Puppeteer, Selenium, WebdriverIO, Jest/Vitest und CI-Pipelines.

@surea11y/core ist eine Engine für Barrierefreiheitstests, die Sie in Ihrer eigenen Testsuite, Ihrer CI-Pipeline oder über die Kommandozeile ausführen.

Was sie unterscheidet, ist ihr Umgang mit den Fällen, die automatisierte Tests nicht entscheiden können. Sie implementiert das offene Accessibility Conformance Testing (ACT) Rules Format des W3C und wird am veröffentlichten Testkorpus von ACT geprüft, statt sich nur an sich selbst zu messen. Sie meldet Befunde, Nicht-Befunde und, was selten ist, ausdrückliche Unsicherheit. Die Ergebnisse lassen sich so nachprüfen, statt nur zu beruhigen.

Sure heißt Gewissheit über das, was feststeht, und Ehrlichkeit über das, was nicht feststeht. Sie sagt Ihnen, was sie nicht sagen kann.

145 Barrierefreiheitsregeln · 60 W3C-ACT-Regeln an den Testfällen des W3C geprüft · 957 Referenzfälle · deterministische Ergebnisse · ausgewiesene Unsicherheit

Änderungen im neuesten Release ansehen

Kein einzelnes Produkt

surea11y ist eine Familie von Paketen mit einer gemeinsamen Engine, kein Tool mit nur einem Installationsbefehl. Installieren Sie das Paket, das zu Ihrer bisherigen Art zu testen passt, zusammen mit @surea11y/core, der Engine, die es ausführt. core allein installieren Sie, um die Engine auf ein DOM anzuwenden, das Sie bereits haben, oder um ein eigenes Tool darauf aufzubauen:

Installation und Verwendung pro Binding finden Sie unter Erste Schritte. Wenn Sie ein Tool entwickeln, beschreibt BUILDING_ON_CORE.md (auf GitHub, auf Englisch) den stabilen Vertrag, das Ausführen von Scans, die Wahl der Prüfungen und wie man Ergebnisse darstellt, ohne mehr zu behaupten, als sie aussagen.

Für einen ersten Blick ohne Testsuite laden Sie das Standalone-Bundle in eine Seite und scannen sie aus der Browserkonsole: await a11ycore.run() scannt die Seite, a11ycore.table(result) listet die Befunde auf, a11ycore.highlight(result) umrahmt sie auf der Seite, und await a11ycore.openReport(result) öffnet den HTML-Bericht. INTEGRATION.md (auf GitHub, auf Englisch) listet die weiteren Hilfsfunktionen auf, etwa a11ycore.inspect('headings') für die Überschriften, Landmarks, Namen oder die Fokusreihenfolge einer Seite.

Wie sich die Ergebnisse unterscheiden

Jede Regel trifft eine deterministische Entscheidung aus einem festen Vokabular von vier Ergebnissen, nicht in der Form violations/passes/incomplete/inapplicable, die andere verbreitete Tools für Barrierefreiheitstests verwenden:

• ✕fail (fail): ein Verstoß, der sich am DOM belegen lässt. Objektiven, normativen Fällen vorbehalten.
• ✓pass (pass): Die konkrete Bedingung dieser Regel ist erfüllt. Keine Aussage, dass die Seite barrierefrei ist.
• ?can't tell (cantTell): Das muss ein Mensch entscheiden, und das Ergebnis sagt, was unklar war.
• –n/a (notApplicable): Die Vorbedingung der Regel ist nicht gegeben.

cantTell ist der Kern des Projekts. Eine Engine, die stillschweigend verwirft, was sie nicht bestimmen kann, liefert einen kürzeren Bericht und den trügerischen Eindruck vollständiger Abdeckung. Die vollständige Struktur eines Ergebnisses finden Sie unter Ergebnisse und Berichte, und unter Konformität, wie sich einzelne Ergebnisse zu einem WCAG-Urteil zusammenfassen, einschließlich der Frage, wie eine Ziel-Version von WCAG (2.0/2.1/2.2) ermittelt und angewendet wird.

Ein cantTell lässt Sie nicht mit einer bloßen Frage zurück. Jeder Befund dieser Art, den eine Regel von core meldet, sagt, wie er sich beantworten lässt: einige Schritte, ausgehend von dem Element, das er nennt, und was Sie sehen, wenn es erfüllt ist und wenn nicht, in der Sprache des Scans. Wo die Seite Anhaltspunkte liefert, zeigt der Befund außerdem eine Tendenz zu pass oder fail, mit den Fakten, die er gelesen hat, seiner Begründung und dem, was ihn falsch machen könnte. Jede Tendenz wird an den ACT-Testfällen des W3C gezählt, und sobald sie an mindestens fünf gezählt wurde, sagt sie, wie oft sie richtig lag; bis dahin trägt sie gar keine Zahl, nie eine Schätzung. Das Ergebnis bleibt cantTell: Eine Tendenz ordnet die Fragen, beantworten muss sie weiterhin eine Person. Siehe So prüfen Sie es und Tendenzen im Ausgabeschema sowie LEANS.md (auf GitHub, auf Englisch) dazu, wann ein Befund eine Tendenz bekommt und wie weit man ihr trauen kann.

Der HTML-Bericht ordnet die Fragen so, wie eine prüfende Person sie abarbeitet: „Wahrscheinlich nicht erfüllt: bitte bestätigen“, „Wahrscheinlich erfüllt: bitte bestätigen“ und „Muss eine Person prüfen“. Jede Karte hat ihre Schritte unter „So prüfen Sie es“, und die in den ersten beiden Gruppen sagen, warum sie tendieren. In CI können die JUnit- und SARIF-Berichte außerdem an den Befunden scheitern, die zu fail tendieren, standardmäßig ausgeschaltet, und eine Baseline kann die akzeptieren, die eine Seite schon hat, sodass nur neue den Build brechen. Siehe HTML-Bericht und Baseline / Allowlist, oder öffnen Sie einen Beispielberichtzu einer kleinen Bezahlseite.

Ein pass, der knapp war, sagt es. Regeln, die gegen einen Grenzwert messen (Kontrast, Zielgröße, Textabstände), melden eine margin, wenn der knappste Fall nahe am Grenzwert lag: das Element, das ihm am nächsten kam und ihn trotzdem einhielt. Text mit 4,52:1 bei einem Minimum von 4,5:1 besteht, und die margin zeigt es. So können Sie ihn korrigieren, bevor eine kleine Änderung ein fail daraus macht. Siehe Ausgabeschema.

Nennen Sie den Standard, und die Engine wählt die Regeln. { wcag: { version: '2.2', level: 'AA' } } führt die Regeln für die A- und AA-Kriterien von WCAG 2.2 aus, nach der Stufe, die jedes Kriterium in dieser Version hat, und bestPractices: true ergänzt die Prüfungen, die WCAG nicht verlangt. Ein Standard über WCAG hinaus, etwa ein nationaler oder die eigene Richtlinie Ihrer Organisation, kommt als Pack: Seine Regeln, Profile und Checklistenpunkte laufen neben denen von core und erscheinen in jedem Bericht. Siehe Engine-Optionen und Packs.

Nennen Sie Prüfungen statt eines Standards, und das Ergebnis zeigt trotzdem, welche WCAG-Kriterien sie betreffen. Ein Scan, der nur link-name-present ausführt, meldet auch 2.4.4 und 4.1.2, dazu das AAA-Kriterium 2.4.9, wenn der Scan keine Stufe festlegt, und ein Kriterium, dessen übrige Prüfungen der Scan ausgelassen hat, ergibt cantTell („Teilweise geprüft“ im HTML-Bericht), nicht pass. wcagLevel: 'AA' legt die Stufe der Kriterien fest, die ein Scan meldet, und die JUnit-, SARIF- und EARL-Berichte folgen ihr. So schlägt ein AA-Build nicht wegen eines AAA-Kriteriums fehl.

Kein WCAG-Kriterium gilt als bestanden, nur weil Regeln, die einen Teil davon prüfen, bestanden haben. Ein Kriterium ergibt pass nur, wenn seine Regeln alles prüfen, was es verlangt, und noch keines wird so vollständig geprüft. Wo alle Regeln eines Kriteriums bestehen, ergibt das Kriterium daher cantTell: Die Teile, die die Regeln prüfen, sind erfüllt, den Rest prüft eine Person. Ein Bericht ohne Fehlschlag sagt dasselbe unter seiner Überschrift: Keine Regel ist fehlgeschlagen, und das ist keine Aussage über Konformität. Diese Kriterien als bestanden auszuweisen, wäre genau der trügerische Eindruck vollständiger Abdeckung, den diese Engine vermeiden soll. Siehe WCAG-Konformitätszuordnung.

Web Components werden nach dem beurteilt, was sie bereitstellen. Ein Custom Element, das sich über ElementInternals einen Namen, Zustände oder eine Rolle gibt, wird daran geprüft, wo die Engine sie lesen kann, und als Frage gemeldet, wo nicht. Für Test- und Audit-Läufe ist internalsHookScript() ein optionales Skript, mit dem ein Scan die internals liest, die eine Komponente privat hält. Solche Elemente ergeben dann pass oder fail statt cantTell. INTEGRATION.md (auf GitHub) zeigt, wie Sie es vor den Skripten der Seite installieren.

Die Regeln erreichen drei Kriterien, die bisher keine Regel abdeckte: 3.3.1 „Fehlererkennung“ (ein als ungültig markiertes Feld, dessen Fehlermeldung fehlt, verborgen oder nicht mit ihm verknüpft ist), 4.1.3 „Statusmeldungen“ (eine Live-Region, die assistive Technologien nicht erreichen) und 1.4.5 „Bilder eines Textes“ (in ein Bild gezeichneter Text, der echter Text sein könnte). Alle drei stellen eine Frage, statt fehlzuschlagen. Die Tastaturregeln lesen Event-Handler aus dem Markup; mit listenerHookScript(), einem weiteren optionalen Skript, das vor den Skripten der Seite installiert wird, beurteilen sie auch per Skript hinzugefügte Listener. Ein role="button" in der Tab-Reihenfolge mit einem Klick-Listener und ohne Tasten-Listener an einer Stelle, die seine Tasten erreichen können (am Element, darin, an seinen Vorfahren, an einem Shadow Root, in dem es liegt, am Dokument oder am Fenster), und ohne Fokus-Listener, der einen hinzufügen könnte, ergibt fail: Eingabe- und Leertaste bewirken nichts. INTEGRATION.md (auf GitHub) zeigt, wie Sie es installieren, und sein Gegenstück für Statusmeldungen, den Live-Region-Hook.

Im Browser wird Kontrast so gemessen, wie die Seite gezeichnet wird: Text auf einer Seite ohne eigenen Hintergrund, auf der Fläche, die der Browser malt, hell oder dunkel; generierter Text aus ::before, ::after und Listenmarkern; ein geschlossenes <select>. Diese Fälle wurden früher übersprungen oder als Frage gemeldet. Text, der nur durch eine Kontur oder einen Schatten gezeichnet wird, ergibt jetzt fail, wo jede Farbe, in der er gezeichnet wird, unter dem Verhältnis liegt. Ein einzelnes Zeichen, das für den Namen eines Bedienelements steht, wie das „X“ in einer Schaltfläche namens „Schließen“, wird als Frage gemeldet statt als fail: Ob es ein Icon oder ein Buchstabe ist, muss eine Person entscheiden.

Geprüft am ACT-Korpus

Die Engine bringt 145 Regeln mit. Diejenigen mit einer Entsprechung in den W3C ACT Rules laufen gegen die Testfälle, die das W3C dafür veröffentlicht, also die Menge, die die Implementierungsliste des W3C bewertet: 957 Beispiele über 60 ACT-Regeln. Für keines der Beispiele, die ACT als bestanden oder nicht anwendbar markiert, meldet die Engine fail; gegenüber diesem Korpus gibt es also keine Falsch-Positive. Das ist ein Ergebnis für diese Beispiele, keine Garantie für jede Seite. Wo die Engine einen Fall nicht entscheiden kann, meldet sie cantTell, was ACT einer automatisierten Implementierung erlaubt.

Das gilt an beiden Orten, an denen die Engine läuft: in jsdom, wie test-matchers und die CLI sie standardmäßig ausführen, und in Chromium, wie die Browser-Bindings es tun, wobei jeder Testfall als echte Seite geladen wird, mit seinen Skripten und verlinkten Stylesheets. 22 Beispiele, die ACT als nicht bestanden markiert, erkennt die Engine in jsdom nicht, in Chromium 18. Meist geht es um Ermessensfragen wie die, ob eine Überschrift den Inhalt darunter beschreibt; die vier, die der Browser erkennt, brauchen die Skripte oder Stylesheets der Seite selbst, die jsdom nicht ausführt. Jedes einzelne, mit Begründung, steht in ACT_RULE_MAPPING.md.

Zwei EARL-Implementierungsberichte halten das Ergebnis für jeden dieser Fälle fest, bestandene und nicht anwendbare eingeschlossen. So lässt sich eine Regel, die stumm blieb, weil nichts anwendbar war, von einer unterscheiden, die gar nicht implementiert ist: SureA11y, ausgeführt in jsdom, und SureA11y in a browser, ausgeführt in Chromium. Zum Format siehe EARL-Bericht.

Grundprinzipien

• Deterministische Ausführung. Dieselbe Seite, unter denselben Bedingungen gerendert und mit denselben Optionen gescannt, erhält dieselben Entscheidungen. Laufzeiten, Zeitstempel und Angaben zur Umgebung im Ergebnis können sich zwischen Läufen trotzdem unterscheiden. Laufende Animationen und Übergänge werden für den Scan angehalten, sodass eine laufende Einblendung nicht verändert, was die Regeln messen.
• Bewusst konservativ. Die Regeln von core behalten fail objektiven, normativen Verstößen vor, damit Fehlalarme selten bleiben.
• Rückverfolgbarkeit zu Standards. Regeln sind, wo sinnvoll, dem zutreffenden WCAG-Erfolgskriterium zugeordnet.
• Stabile maschinenlesbare Ausgabe. Regel-IDs bleiben unabhängig von der Sprache stabil.
• Framework-unabhängig. Läuft in jsdom oder in jedem Framework zur Browser-Automatisierung.
• Erweiterbar. Eigene Regeln hinzufügen, Policies registrieren und Scans nach Regel-IDs, Tags oder WCAG-Version filtern.
• Lokalisierte Berichte. Lesbare Meldungen lassen sich übersetzen, ohne die maschinenlesbaren Daten zu berühren; derzeit mit en, fr, de, es und ja.

Philosophie

Automatisieren, was sich objektiv bestimmen lässt. Nie so tun, als ließe sich automatisieren, was sich nicht bestimmen lässt.

Manche WCAG-Anforderungen lassen sich mit voller Sicherheit prüfen. Andere brauchen menschliches Urteil, Kenntnis des Kontexts oder eine Bewertung der Gebrauchstauglichkeit. Eine einzelne Punktzahl oder ein Urteil „bestanden/nicht bestanden“ verwischt diesen Unterschied; surea11y weist ihn aus. Deshalb gibt es cantTell und notApplicable als Ergebnisse, und das prägt jede Regel der Engine.

Was surea11y nicht findet

Die Grenzen der Automatisierung klar zu benennen, gehört zur selben Philosophie. surea11y wird zum Beispiel nicht:

• bestätigen, dass ein Alternativtext aussagekräftig ist, nur dass er vorhanden ist (ein alt-Attribut "image123.png" besteht die objektive Prüfung und wird als Dateiname mit Tendenz zu fail als Frage gemeldet);
• beurteilen, ob eine Farbkombination ästhetisch passt, nur ob sie das geltende Kontrastverhältnis erfüllt;
• feststellen, ob eine Fehlermeldung das Problem tatsächlich erklärt, denn das hängt von Validierungslogik ab, die ein statischer Scan nicht sieht;
• eine Tastaturfalle oder bei 400 % Zoom abgeschnittenen Inhalt erkennen, denn beides erfordert, echte Benutzerinteraktion über die Zeit zu simulieren, statt das DOM zu einem einzigen Zeitpunkt zu lesen.

Einige implementierte Prüfungen melden cantTell, wenn eine Person entscheiden muss. Andere Aspekte, darunter Tastaturfallen und Reflow beim Zoomen, prüft die Engine gar nicht; sie brauchen eigene Tests. Kein cantTell steht für sie, ein Ergebnis ohne cantTell heißt also nicht, dass sie abgedeckt wurden. Die vollständige Liste finden Sie unter Bekannte Einschränkungen.