Erste Schritte
Installation
Es gibt keinen einzelnen Installationsbefehl — surea11y besteht aus einer Core-Engine und einer Familie separat veröffentlichter Bindings. Welche Pakete Sie installieren, hängt also davon ab, wie Sie Tests oder Skripte bereits ausführen. Wählen Sie Ihren Stack:
Nutzen Sie Playwright, um eine echte Webanwendung zu scannen, oder die CLI, um statisches HTML im Terminal oder in einer CI-Pipeline zu prüfen.
| Bedarf | Empfohlene Option | Begründung |
|---|---|---|
| Eine echte Webanwendung analysieren | Playwright | Steuert einen echten Browser und ist eine Integration, die moderne Testsuiten bereits nutzen, sodass die Ergebnisse das tatsächliche Layout und Rendering widerspiegeln. |
| Statisches HTML analysieren | CLI | Keine Integration zu schreiben — ein einziger Befehl gegen Dateien, URLs, eine Sitemap oder in einem CI-Schritt; mit --browser scannt sie auch Seiten, die ihr JavaScript rendert. |
| Sie nutzen bereits Cypress, Selenium, Puppeteer oder WebdriverIO | Das passende Binding | Fügt sich direkt in Ihre bestehende Testumgebung ein. |
| Unit- oder Komponententests | test-matchers | Direkte Jest-/Vitest-Integration gegen jsdom. |
| Eigene Integration oder direkter Zugriff auf die Engine | @surea11y/core | Maximale Kontrolle über Ausführung und Ergebnisse. |
Ein Beispiel in 5 Minuten
Mit der CLI sehen Sie am schnellsten ein echtes Ergebnis — ohne Browser-Setup, ohne Test-Framework. Scannen Sie eine minimale Seite:
<html lang="en"><body><main><h1>Welcome</h1><p style="color: #999999; background-color: #ffffff;">This text has low contrast.</p><a href="/details">Click here</a></main></body></html>
$ npm install -g @surea11y/cli$ surea11y scan ./index.html
surea11y scan: file:///path/to/index.htmlengine: @surea11y/core 1.14.1pass: 14 fail: 3 cantTell: 2 notApplicable: 126occurrences by tier: fail: 3 cantTell: 2needs review: likely fail: 0 likely pass: 0 needs a person: 2FAIL (3 rule(s)):contrast-enhanced (serious, 1 fail occurrence(s))- html > body > main > pElement has insufficient color contrast (AAA) of 2.85:1 (foreground:#999999, background: #ffffff, font size: 16px, font weight: normal).Expected contrast ratio of 7:1 (normal text).hint: Change the text color, the background color, or both, so thecontrast ratio reaches at least 7:1.contrast-minimum (serious, 1 fail occurrence(s))- html > body > main > pElement has insufficient color contrast of 2.85:1 (foreground:#999999, background: #ffffff, font size: 16px, font weight: normal).Expected contrast ratio of 4.5:1 (normal text).hint: Change the text color, the background color, or both, so thecontrast ratio reaches at least 4.5:1.page-title-present (serious, 1 fail occurrence(s))- head > titleThis page has no <title> element.hint: Add a <title> that says what the page is about or what it is for.cantTell — needs human review (2 rule(s)): link-name-quality,manual-reviewcriteria (WCAG 2.2):fail 1.4.3 Contrast: minimum; 1.4.6 Contrast: enhanced; 2.4.2 PagetitledcantTell 1.1.1 Non-text content: text alternatives; 1.2.1 Audio-onlyand video-only (prerecorded): transcript; 1.2.2 Captions(Prerecorded); 1.3.1 Info and Relationships; 1.3.4Orientation; 1.3.5 Identify Input Purpose; 1.4.1 Use ofColor; 1.4.2 Audio Control; 1.4.4 Resize Text; 1.4.5 Imagesof Text; 1.4.12 Text Spacing; 2.1.1 Keyboard; 2.1.3 Keyboard(No Exception); 2.2.1 Timing Adjustable; 2.2.2 Pause, Stop,Hide; 2.2.4 Interruptions; 2.4.1 Bypass Blocks; 2.4.3 Focusorder; 2.4.4 Link Purpose (In Context); 2.4.6 Headings andLabels; 2.4.7 Focus visible; 2.4.9 Link Purpose (Link Only);2.5.8 Target size: minimum; 3.1.1 Language of page; 3.1.2Language of Parts; 3.2.5 Change on Request; 3.3.1 ErrorIdentification; 3.3.2 Labels or Instructions; 3.3.8Accessible Authentication (Minimum); 4.1.2 Name, role, value:accessible name; 4.1.2 Name, role, value: ARIA validity;4.1.3 Status MessagesnotApplicable: 2A criterion that passes here means the checks that ran found nothing init, not that the page conforms.
Zwei Probleme, bei denen sich die Engine sicher ist, sodass sie fail ergeben: der kontrastarme Text, der sowohl am AA- als auch am AAA-Verhältnis scheitert, und das fehlende <title>. Dann eine cantTell-Liste zur manuellen Prüfung (ist „Click here“ ein guter Linkname, gibt es hier etwas, das manuell angesehen werden muss); die Zeile needs review zeigt, dass keine der beiden Fragen in eine Richtung tendiert, beide brauchen also eine Person. Unter den 126 notApplicable-Ergebnissen ist target-size-minimum: Diese Regel kann ohne echtes CSS-Layout nicht laufen, und das hat ein Scan von statischem HTML nicht (--browser gibt ihr eines).
Der letzte Block zeigt dasselbe Ergebnis nach WCAG-2.2-Erfolgskriterium: 1.4.3, 1.4.6 und 2.4.2 ergeben fail; jedes andere Kriterium, das der Scan prüft, ist cantTell und bleibt einer Person überlassen; und die 2, bei denen es nichts zu beurteilen gab, werden nur gezählt. Keines steht unter pass: Seit @surea11y/core 1.14 gilt ein Kriterium nur dann als bestanden, wenn seine Regeln alles prüfen, was es verlangt, und das tut noch keines. Ergeben sie alle pass, bleibt der Rest also Sache einer Person. Unter Ergebnisse und Berichte erfahren Sie, was jedes Feld eines vollständigen Ergebnisses bedeutet.
- End-to-End-Tests mit einem echten oder Headless-Browser: Cypress, Playwright, Puppeteer, Selenium oder WebdriverIO.
- Unit- und Komponententests gegen jsdom: test-matchers, für Jest oder Vitest.
- Seiten im Terminal oder in einer CI-Pipeline, als statisches HTML oder im Browser: die CLI.
- Kein Test-Framework, kein Build-Schritt: Standalone — installieren Sie
@surea11y/coredirekt oder binden Sie das Browser-Bundle ein.
Verwendung
Egal, wie Sie einen Scan ausführen — jsdom, ein echter Browser, ein beliebiges Binding, die CLI —, er liefert dieselbe native Ergebnisform: checksResults (ein Eintrag pro Regel, einschließlich jedes pass/notApplicable — keine Liste nur mit Verstößen) und rulesResults (Zusammenfassungen pro WCAG-Erfolgskriterium). Das ist nicht die Form violations/passes/incomplete/inapplicable, die andere verbreitete Werkzeuge für Barrierefreiheitstests verwenden — die Methodennamen der einzelnen Bindings orientieren sich an gängigen Konventionen in diesem Bereich, damit der Umstieg vertraut wirkt, aber das reichhaltigere Ergebnisschema bleibt unverändert. Das vollständige Schema finden Sie unter Ergebnisse und Berichte.