HTML-Bericht

Ein eigenständiger HTML-Bericht, den Sie nach einem Scan im Browser öffnen können — ohne Server, ohne externe Ressourcen, ohne Netzwerkanfragen. Gedacht für Personen in QA und manueller Prüfung, die die Ergebnisse eines Scans durchblättern möchten, statt rohes JSON oder eine Zusammenfassung im Terminal zu lesen. Öffnen Sie einen Beispielbericht: eine kleine Bezahlseite, gescannt mit dem Listener- und dem Live-Region-Hook, mit einem Befund in jeder Gruppe.

$ surea11y scan ./dist/index.html --html report.html

Öffnen Sie report.html direkt von der Festplatte. Funktioniert zusammen mit jedem anderen Ausgabemodus — --html ersetzt weder --json noch die Standardzusammenfassung, sondern ist ein zusätzliches Artefakt, das unter dem angegebenen Pfad geschrieben wird.

Was er zeigt

Kopfbereich: eine Schlagzeile in einfacher Sprache („N von M anwendbaren Prüfungen bestanden“) plus ein gestapelter Balken mit Legende (Icon + Bezeichnung + Anzahl — der Status wird nie nur über Farbe vermittelt), aufgeschlüsselt nach Ergebnis (fail/cantTell/pass/notApplicable). Ist keine Regel fehlgeschlagen und waren einige anwendbar, sagt ein Hinweis unter der Schlagzeile, dass das keine Aussage über die Konformität der Seite ist, und nennt, was eine Person weiterhin prüft: die Befunde, die eine Prüfung brauchen, die Bedienung per Tastatur, wie ein Screenreader die Seite vorliest, und die Inhalte selbst.
Prüfenswert: eine Karte pro Regel mit fail-/cantTell-Vorkommen (nicht eine pro Vorkommen — eine Regel mit vielen identischen Vorkommen ist eine Sache, die Aufmerksamkeit verdient, nicht viele), jeweils mit Schweregrad, Chip(s) für das WCAG-Erfolgskriterium, einem repräsentativen Vorkommen und der Gesamtzahl der Vorkommen. Regeln mit dem Ergebnis fail stehen zuerst. Die Befunde, die eine Prüfung brauchen, folgen in drei Gruppen: die, deren Anhaltspunkte auf einen Fehler weisen („Wahrscheinlich nicht erfüllt: bitte bestätigen“), die, deren Anhaltspunkte auf ein Bestehen weisen („Wahrscheinlich erfüllt: bitte bestätigen“), und die, die nur eine Person beurteilen kann („Muss eine Person prüfen“), so wie reviewGroupOf(check, occurrence) aus @surea11y/core sie einordnet, damit ein Tool, das eine Prüfliste sortiert, sie genauso sortiert. Jede Karte der ersten beiden Gruppen sagt, warum sie in diese Richtung tendiert (das lean des Vorkommens). Jede dieser Karten hat einen standardmäßig eingeklappten Abschnitt „So prüfen Sie es“ mit den Schritten, um die Frage zu beantworten, und was als erfüllt und was als nicht erfüllt gilt (das howToCheck des Vorkommens). Eine Regel, deren Befunde in verschiedene Richtungen tendieren, hat in jeder Gruppe eine Karte. Innerhalb jeder Gruppe steht der höchste Schweregrad zuerst (von kritisch bis gering) und bei gleichem Schweregrad die Regel mit mehr Vorkommen. Begrenzt auf die 24 Regeln mit der höchsten Priorität, darüber hinaus mit einem Hinweis auf weitere. Eine Regel, die nicht abgeschlossen wurde (sie hat eine Ausnahme geworfen), erhält ebenfalls eine Karte, die das mit ihrem Fehler sagt, da die Seite nicht gegen sie geprüft wurde. Eine Regel mit einem http(s)-Hilfelink (meta.helpUrl, auch bei einer eigenen Regel) erhält auf ihrer Karte einen Link „How to fix <rule>“; eine Regel ohne einen solchen verlinkt das Understanding-Dokument des WCAG-Kriteriums, das sie prüft („Understanding 1.1.1 Non-text Content“).
Frames: nur bei einem Frame-übergreifenden Ergebnis (runa11yCoreAcrossFrames oder .frames(true) eines Bindings). Die Karten oben gehören zur Seite selbst; dieser Abschnitt hat eine Überschrift pro Frame, benannt nach seinem Pfad (den Selektoren der Frame-Elemente, die zu ihm führen), mit Titel und URL des Frames und seinen Karten, oder „Nicht gescannt“ samt Grund bei einem Frame, der nicht geantwortet hat. Der Rest des Berichts beschreibt die Seite selbst.
Am nächsten an der Grenze: erscheint, wenn der Scan Abstandswerte enthält (margin bei einem Prüfergebnis). Eine Zeile je Regel, deren knappstes bestandenes Element ihrem Schwellenwert nahe kam (innerhalb des Bands der Regel, etwa 10 % eines Kontrastverhältnisses), wie der Hinweis über der Tabelle sagt: ihr knappster bestandener Wert, die Grenze, der verbleibende Abstand und das Element. Pixel werden auf ganze Zahlen gerundet, unter einem Pixel steht „weniger als 1 px“; Verhältnisse zeigen zwei Nachkommastellen. Eine Regel, die nur knapp bestanden hat, kann schon durch eine kleine Änderung scheitern.
WCAG-Zusammenfassung: gruppiert nach Konformitätsstufe (A / AA / AAA), direkt aus den zusammengesetzten Zusammenfassungen der Engine in rulesResults[] (siehe Konformität) — eine Zeile pro Erfolgskriterium (mit den Anforderungen jeder anderen Norm in standards des Ergebnisses, auf die seine Regeln abgebildet sind, etwa der EN-301-549-Klausel, die es wiedergibt, sofern es eine gibt und der Scan EN-301-549-Klauseln angefordert hat) mit seinem Ergebnis, einer Aufschlüsselung nach bestanden/nicht bestanden/zu prüfen/nicht anwendbar (mit einer Zeile „Teilweise geprüft“, wenn die Regeln des Kriteriums nur einen Teil dessen prüfen, was es verlangt, sodass eine Person den Rest prüft, etwa „Teilweise geprüft: Die Prüfungen decken nur einen Teil dieses Kriteriums ab, den Rest prüft ein Mensch“, oder wenn der Scan nur einen Teil seiner Regeln ausgewählt hat, etwa „Teilweise geprüft: 1 von 2 Prüfungen war für diesen Scan nicht ausgewählt“, siehe Ein teilweise geprüftes Kriterium) und den atomaren Regeln, die dazu beigetragen haben, einschließlich einer eigenen Regel, die dem Kriterium zugeordnet ist. Das sind echte Engine-Daten, keine erfundene Gruppierung — dieselbe Zusammenfassung, die Sie auch aus rulesResults im rohen JSON erhalten.
Eigene Zusammenfassung einer Norm: nur wenn der Scan die Regeln einer Norm mit eigenen Zusammenfassungen ausgeführt hat (über ihr Profil oder engineOptions.optInRules), eine Zeile pro Zusammenfassung, mit dem Wortlaut der Norm, den Anforderungen der Regeln, die das Ergebnis entschieden haben, der Aufschlüsselung und den beitragenden Regeln. Das umfasst die Norm eines Packs und die Checkliste eines Packs, deren Punkte ihre Zusammenfassungen sind. Jede solche Norm ist in standards des Ergebnisses aufgeführt, sodass ein gespeichertes Ergebnis überall gleich dargestellt wird; fehlt diese Liste oder ist sie beschädigt, sagt der Bericht das über der WCAG-Zusammenfassung.
Vollständige technische Daten (standardmäßig eingeklappt): eine Übersicht (Kacheln pro Ergebnis) und eine durchsuchbare, (nach Ergebnis) filterbare, paginierte Tabelle aller einzelnen Vorkommen des gesamten Scans; ein Befund, der eine Prüfung braucht und eine Tendenz hat, zeigt sie unter seiner Zusammenfassung („Wahrscheinlich nicht erfüllt: …“), und die Suche findet sie. Zeigt sie kein Vorkommen, enthält sie eine Zeile, die das sagt: Der Scan hat keine erfasst, oder die Filter blenden alle aus.

Ein Element in einem Shadow Tree wird über die Selektoren der Shadow Hosts und dann seinen eigenen verortet, verbunden mit >>> : html > body > main > x-card >>> button. Die Karten, die Tabelle der Abstandswerte und die Tabelle der Vorkommen zeigen es alle so, ebenso SARIF und JUnit.

Der Bericht folgt dem Farbschema der lesenden Person, und sein eigener Text erfüllt WCAG 1.4.3 in beiden: Jede Statusfarbe hat mindestens 4,5:1 auf ihrem Chip und ihrer Kachel, und die eigenen Kontrastregeln der Engine bestehen auf dem dargestellten Bericht im hellen und im dunklen Modus.

Der Bericht bricht bei 320 CSS-Pixeln um (WCAG 1.4.10): Die Seite scrollt nie seitwärts. Eine Tabelle, die breiter als das Fenster ist, scrollt in einem eigenen Kasten, einem nach der Überschrift der Tabelle benannten Bereich, der den Tastaturfokus annimmt, sodass er sich mit den Pfeiltasten scrollen lässt.

Die Meta-Leiste unter dem Kopf enthält die Anzahl der Regeln, die Anzahl der Vorkommen, das Engine-Tag, die Schema-Version, die WCAG-Version, auf die der Scan zielte, das verwendete engineOptions.profile (falls es eines gab), die Tags der Opt-in-Regeln, die engineOptions.optInRules hinzugefügt hat (falls welche), die Bedingungen, unter denen die Seite dargestellt wurde, und die Locale, auf die der Scan aufgelöst wurde. Die Bedingungen sind der Viewport (mit dem Gerätepixelverhältnis, wenn es nicht 1 ist) und das Farbschema, dazu die Webfonts, wenn sie noch luden; ein Scan ohne Layout, in jsdom, sagt stattdessen genau das. Ein layoutabhängiger Befund kann je nach Viewport-Breite auftauchen oder verschwinden, daher nennt der Chip die Breite, die der Bericht beschreibt. Der Fallback der Locale erfolgt pro String und ist im Text selbst nicht sichtbar, daher liest sich ein Bericht, der in einer Sprache angefordert wurde, die die Engine nicht mitbringt, wie ein gewöhnlicher englischer — der Chip nennt die angeforderte Locale neben der aufgelösten, wenn sich beide unterscheiden. Siehe Locales.

Die ganze Seite ist in der Locale geschrieben, auf die der Scan aufgelöst wurde: Überschriften, Tabellenspalten, Namen von Ergebnissen und Schweregraden, die Kopfzeile, die Seitennavigation und das Datumsformat. <html lang> nennt diese Locale. Die Ergebniscodes in den Filtern für Vorkommen (fail, cantTell, …) bleiben unverändert, da es die Werte sind, nach denen man im JSON-Ergebnis sucht.

Ein Fall behält englische Beschriftungen: ein Scan in einer Sprache, die die Engine nicht mitbringt, mit einem selbst bereitgestellten Wörterbuch in engineOptions.messages. Dieses Wörterbuch ist nicht Teil des Ergebnisses, daher kann der Bericht keine Beschriftungen daraus lesen; seine Befunde werden dann mit ihrer eigenen Sprache ausgezeichnet (zum Beispiel lang="nl"), damit ein Screenreader sie mit der richtigen Stimme vorliest.

Ein kompaktes Ergebnis (engineOptions.output.detail: 'findings', siehe Ausgabeschema) wird als das vollständige Ergebnis gelesen, für das es steht, und daher genauso gemeldet.

Verwendung als Bibliothek

const { renderHtmlReport } = require('@surea11y/core/report');
const { runDomRulesInPage } = require('@surea11y/core');
 
const result = runDomRulesInPage(url, null, {}, null);
const html = renderHtmlReport(result, { title: 'My scan report' });
 
require('fs').writeFileSync('report.html', html);

renderHtmlReport(result, options) gibt einen String zurück und greift selbst nie auf das Dateisystem zu (das Schreiben übernimmt das CLI-Flag --html). Die Seite trägt das Datum aus dem timestamp des Ergebnisses (gesetzt mit engineOptions.timestamp), in UTC angezeigt, sodass dasselbe Ergebnis immer dieselbe Seite ergibt; ein Ergebnis ohne Zeitstempel erhält das Datum der Erzeugung. options.title ist optional (Standardwert ist der Titel in der Sprache des Berichts, auf Deutsch "surea11y-Scanbericht"). options.packs ist die Liste der Packs, die der Scan ausgeführt hat (engineOptions.packs), falls er welche ausgeführt hat: In Node fügt der Bericht Befunden, die eine Prüfung brauchen und ohne sie kommen, die Schritte „So prüfen Sie es“ hinzu, die einer Core-Regel und der Basisregel einer Variante immer, die eigenen Schritte einer Pack-Regel (ihr meta.review, auf Englisch) nur, wenn er die Packs erhält (siehe Packs). Im Browser (surea11y.report.js) zeigt er die Schritte, die das Ergebnis bereits mitführt.

Umfang

Das ist ein Bericht über einen einzelnen Scan — eine Momentaufnahme, kein Dashboard, das Ergebnisse über viele Scans hinweg verfolgt. Ergebnisse über viele Läufe hinweg zu verfolgen ist ein eigenes, größeres Thema und nicht Teil dieses Werkzeugs: Bewahren Sie das JSON jedes Scans auf und vergleichen Sie es selbst, oder speisen Sie SARIF in ein Dashboard ein, das bereits eine Historie führt (siehe SARIF-Bericht unten).