Prüfverfahren

Ein Scan entscheidet, was Regeln entscheiden können. Der Rest einer Bewertung ist Sache einer Person: die Fragen, die ein Scan offen lässt (cantTell), und die Teile eines Kriteriums, die gar keine Regel testet. Seit @surea11y/core 1.15.0 sagt core auch, wie dieser Teil geht: ein Prüfverfahren für jede Facette jedes WCAG-Kriteriums, das seine Regeln bewerten, und der Best Practices, mit den Schritten, den benötigten Werkzeugen und dem, was als bestanden und was als nicht bestanden gilt, auf Englisch, Französisch, Deutsch, Spanisch und Japanisch. Es ist derselbe Text, aus dem „So prüfen Sie es“ eines Befunds stammt, sodass die manuellen Prüfungen eines Teams und seine Scans gleich lauten.

Nutzen Sie sie ganz ohne Scan, für ein manuelles Audit; neben einem Scan, für das, was er einer Person überlässt; oder um ein Kriterium zu erklären, dessen Regeln nichts gefunden haben, es aber nicht vollständig abdecken. Wie die Schritte eines Befunds sind Prüfverfahren eine Anleitung, nicht Teil der Identität eines Befunds: Ihr Wortlaut kann sich in jedem Release verbessern.

Ansehen

Diese beiden Seiten sind die eigene Ausgabe von core für WCAG 2.2 Stufe A und AA, mit jedem Release, dem diese Website folgt, neu erzeugt, und öffnen sich von der Festplatte, ohne etwas von anderswo zu laden:

• Die Referenz: wie jedes Kriterium zu bewerten ist, Facette für Facette, unter den Prinzipien und Richtlinien von WCAG.
• Das Arbeitsblatt: jede Prüfung einmal, mit einem Ergebnis (Nicht geprüft, Bestanden, Nicht bestanden, Nicht anwendbar) und Notizen zum Festhalten, in Ihrem Browser gespeichert und als JSON oder CSV herunterladbar.

Beide Seiten werden an den eigenen Regeln von core gemessen, in jsdom und in Chromium, im hellen und im dunklen Modus, mit dem Profil WCAG 2.2 AA: ein Skip-Link, jeweils eine Überschriftenebene, beschriftete Bereiche, echte Listen und Fieldsets, sichtbarer Fokus, nichts allein über Farbe, ein befolgtes Design mit erzwungenen Farben, die Breite eines Smartphones und ein druckbares Layout.

Was ein Prüfverfahren ist

Ein Kriterium hat Facetten, die Prüfziele, die eine Person prüft, um es zu bewerten. Eine Facette, die eine Regel entscheidet, ist full, eine, von der Regeln einen Teil entscheiden, partial, und eine, die nur eine Person beurteilen kann, manual. Eine Facette hat ein allgemeines Prüfverfahren: Schritte, denen eine Person auf einer ganzen Seite folgt, in einem Browser mit seinen Entwicklertools, einer Tastatur und, wo es darauf ankommt, einem Screenreader; dann was sie sieht, wenn es bestanden ist und wenn nicht, mit dem Kriterium, das dann nicht erfüllt ist; und die Werkzeuge, die es außer einem Browser braucht:

• Eine Technologie-Facette ist ein Test, den eine Regel an einer Art von Element vornimmt (ein <img> hat ein alt-Attribut). Sie hat kein eigenes Prüfverfahren: coveredBy nennt die umfassendere Facette, deren Prüfverfahren sie bewertet, sodass eine Checkliste einmal aufführt, was eine Person tut.
• Eine Variante ist die engere Frage, die eine Regel zu einem Element stellt: die Schritte, die ihr offener Befund als howToCheck zeigt. Ein Befund zeigt immer seine Variante, nie den allgemeinen Text, und die beiden widersprechen sich nie. Jeder Reason-Code, den eine Regel von core als cantTell melden kann, steht unter genau einer Facette.
• Was kein Kriterium verlangt, wird getrennt gehalten, unter best-practice, sodass die Prüfverfahren eines Kriteriums nie einen Rat als Fehlschlag darstellen.

Welche Kriterien Prüfverfahren haben

Jedes Kriterium, das eine Regel von core bewertet, vollständig, teilweise oder als cantTell, hat ein Prüfverfahren für jede Facette, auch für die Facetten, die keine Regel prüft, da eine Person sie braucht, um zu vollenden, was der Scan begonnen hat: 36 der 87 Kriterien von WCAG 2.2 auf den Stufen A, AA und AAA sowie 4.1.1 (in 2.2 entfernt), mit 170 Facetten, 56 eigenen Prüfverfahren und 114 Technologie-Facetten, die von einem davon abgedeckt werden. Ein solches Kriterium ist complete. Die übrigen 51 Kriterien, die keine Regel bewertet (etwa 1.2.3 Audiodeskription oder Medienalternative (aufgezeichnet)), werden mit ihren Facetten und ohne Prüfverfahren aufgeführt: Wie sie von Hand zu bewerten sind, liegt außerhalb von core. Die Best Practices haben eines für jede ihrer 13 Facetten: Landmarks, Inhalte in Landmarks, Überschriften, Tabellen-Markup, ARIA-Rollen, Fokusreihenfolge, Access Keys, Skip-Links, Namen und Beschriftungen, Zoom, wiederholte Namen, neue Fenster und Downloads sowie reduzierte Bewegung.

Sie lesen

In Node kommen sie aus @surea11y/core, das die Wörterbücher von der Festplatte liest. Code, der im Browser läuft, importiert dasselbe aus @surea11y/core/procedures, mit dem Suffix From (proceduresFrom, listProceduresFrom, procedureChecklistFrom, renderProceduresFrom, procedureLanguagesFrom), und übergibt die Wörterbücher, die er als @surea11y/core/procedures/<locale> importiert: Er braucht kein Dateisystem und erreicht keine der Regeln.

const { proceduresFor } = require('@surea11y/core');
 
proceduresFor('1.4.12', { locale: 'fr' });
// { standard: 'wcag', id: '1.4.12', title: 'Espacement du texte', level: 'AA', complete: true,
//   rules: ['avoid-inline-spacing', 'text-spacing-content-loss'], facets: [ … ] }

import { proceduresFrom } from '@surea11y/core/procedures';
import en from '@surea11y/core/procedures/en';
import fr from '@surea11y/core/procedures/fr';
 
proceduresFrom({ en, fr }, '1.4.12', { locale: 'fr' });

Jede Facette trägt ihr label, automation, die rules, die sie beanspruchen, ihre tools, ihr procedure ({ steps, passWhen, failWhen } oder null bei einer Technologie-Facette, mit coveredBy) und ihre variants, jede genau das howToCheck des Befunds dieser Regel für diesen Code. Ein Text in einer anderen Sprache als der gelesenen (der eigene Titel einer früheren WCAG-Version, etwa „Parsing“ von 2.1 für 4.1.1, oder ein Text, der einer Locale fehlt) sagt, in welcher, damit ein Tool ihn mit lang kennzeichnen kann, wie es WCAG 3.1.2 verlangt. PROCEDURES.md von core auf GitHub enthält die ganze Form.

Sie auflisten

const { listProcedures } = require('@surea11y/core');
 
listProcedures();                                         // WCAG 2.2, every level
listProcedures({ version: '2.1', levels: ['A', 'AA'] });  // WCAG 2.1 A and AA
listProcedures({ standard: 'best-practice' });
listProcedures({ levels: ['A', 'AA'], automation: ['manual', 'partial'] }); // what a scan leaves

Die Kriterien von WCAG sind die, die die Version hat, auf ihren Stufen: 2.0 und 2.1 führen 4.1.1 als Kriterium der Stufe A mit dem Titel „Syntaxanalyse“, 2.2 nicht. Bei mehreren Filtern muss eine Facette jedem entsprechen; das complete einer Anforderung bleibt ihr eigenes.

Eine Checkliste

procedureChecklist nimmt dieselben Optionen und liefert, was eine Person tut, um den Standard zu bewerten, jeweils einmal: einen Punkt pro allgemeinem Prüfverfahren, mit den Technologie-Facetten, die es ebenfalls bewertet, in covers und den Regeln dahinter in rules.

const { procedureChecklist } = require('@surea11y/core');
 
procedureChecklist({ levels: ['A', 'AA'] }).items[0];
// {
//   key: '1.1.1/text-alternative-mechanism',
//   label: 'Non-text content that conveys something has a text alternative',
//   automation: 'partial',
//   wcag: '1.1.1',
//   requirements: ['1.1.1'],
//   covers: ['img-alt-attr-present', 'role-img-text-alternative-present', …],
//   rules: ['img-alt-present', …],
//   tools: [{ id: 'devtools', label: "The browser's developer tools" }],
//   procedure: { steps: ['…'], passWhen: '…', failWhen: '… which fails WCAG 1.1.1.' }
// }

Seiten und Arbeitsblätter

renderProcedures macht aus dem, was listProcedures, procedureChecklist oder proceduresFor liefert, ein Dokument, das eine Person liest oder durcharbeitet: eine eigenständige HTML-Seite, die sich ohne Server, Netzwerk, Schrift oder Script von anderswo von der Festplatte öffnet, oder Markdown. Dieselbe Eingabe und dieselben Optionen ergeben immer dieselbe Seite.

const { listProcedures, procedureChecklist, renderProcedures } = require('@surea11y/core');
const fs = require('node:fs');
 
// A reference: how to assess every WCAG 2.2 A and AA criterion.
fs.writeFileSync('wcag-22-aa.html', renderProcedures(listProcedures({ levels: ['A', 'AA'] })));
 
// A worksheet: each check once, with a result and notes to record.
fs.writeFileSync('wcag-22-aa-checklist.html', renderProcedures(procedureChecklist({ levels: ['A', 'AA'] })));
 
// The same in Markdown, for a repository or a wiki.
fs.writeFileSync('wcag-22-aa.md', renderProcedures(listProcedures({ levels: ['A', 'AA'] }), { format: 'markdown' }));

Die Seite einer Liste ist eine Referenz für den Standard: sein Titel und Umfang, was seine Ergebnisse bedeuten (die Best Practices zählen gegen keine Konformität, Stufe AAA ist eine Empfehlung), „Bevor Sie beginnen“, ein Inhaltsverzeichnis und jede Anforderung mit ihren Facetten: was jede prüft, wie viel davon Regeln entscheiden, die Werkzeuge, die Schritte, was als bestanden und was als nicht bestanden gilt, und die Regeln, die sie testen.

Die Seite einer Checkliste ist ein Arbeitsblatt. Unter jedem Punkt hält eine Person ein Ergebnis und Notizen fest; die Seite zählt die Ergebnisse in einer Statusmeldung, die ein Screenreader ansagt, speichert sie im Browser (localStorage, nach Standard, Version und Titel geschlüsselt) und lädt sie als JSON herunter, mit dem Ergebnis jeder Anforderung aus ihren Punkten zusammengefasst, oder als CSV, das eine Tabellenkalkulation mit seinen Akzenten öffnet. Eine Anforderung ist nicht bestanden, wo einer ihrer Punkte nicht bestanden ist, open, wo einer noch nicht geprüft ist, notApplicable, wo keiner zutrifft, und sonst bestanden.

{
  "title": "WCAG 2.2: manual checklist",
  "standard": "wcag",
  "version": "2.2",
  "items": [
    {
      "key": "1.1.1/text-alternative-mechanism",
      "requirements": ["1.1.1"],
      "outcome": "fail",
      "notes": "The logo has no alt."
    }
  ],
  "requirements": [{ "id": "1.1.1", "outcome": "fail" }]
}

Die eigenen Wörter einer Seite gibt es in jeder Sprache, die core mitliefert, ebenso die Prüfverfahren, die Bezeichnungen der Facetten und die Prinzipien, Richtlinien und Kriterien von WCAG, mit den Namen, wie sie die veröffentlichte Übersetzung von WCAG in jeder Sprache angibt. Was in einer anderen Sprache als der der Seite steht, ist mit dieser gekennzeichnet, sodass ein Screenreader jeden Teil in seiner Sprache vorliest. fragment: true liefert nur den Inhalt, in einem <div class="surea11y-procedures"> mit Überschriften ab h1, für eine Dokumentationswebsite, die eigene Styles mitbringt.

Aus der CLI

@surea11y/cli 1.5.0 schreibt dieselben Seiten ohne Code: surea11y procedures ohne Scan und --manual-checks neben einem Scan, für die Prüfungen, die er einer Person überlässt.

# How to assess every WCAG 2.2 A and AA criterion, or a worksheet for a manual audit
$ surea11y procedures --wcag-level AA -o wcag-22-aa.html
$ surea11y procedures --wcag-level AA --checklist --title "Audit: example.com" -o audit.html
# The checks a scan leaves to a person, as a worksheet next to its report
$ surea11y scan https://example.com/ --wcag 2.2 --html report.html --manual-checks manual-checks.html

Im HTML-Bericht

Der HTML-Bericht hat einen Abschnitt „Was ein Mensch noch prüfen muss“: jede Anforderung des gescannten Standards mit einer Prüfung, die keine Regel vollständig entscheidet, ihr Ergebnis im Scan daneben und, darunter eingeklappt, diese Prüfungen mit ihren Schritten. Eine Anforderung, deren Regeln alle pass ergeben, ist erst erfüllt, wenn auch ihre Prüfungen bestanden sind, und der Bericht sagt das. renderHtmlReport(result, { manualChecks: false }) lässt den Abschnitt weg.

Anwendungen

Ein manuelles Audit, ohne Scan. Eine prüfende Person arbeitet das Arbeitsblatt des Standards durch, gegen den das Audit läuft, hält jedes Ergebnis und jede Notiz fest und lädt das JSON für den Bericht herunter:

const checklist = procedureChecklist({ version: '2.2', levels: ['A', 'AA'] });
fs.writeFileSync('audit-worksheet.html', renderProcedures(checklist, { title: 'Accessibility audit: example.com' }));

Der Anhang eines Testlaufs. Ein Playwright-Test, der eine Seite scannt, kann die Prüfungen anhängen, die seine Regeln nicht entscheiden, sodass sie im Testbericht neben dem Scan stehen:

test('home page', async ({ page }, testInfo) => {
  // ... scan the page ...
  const left = procedureChecklist({ levels: ['A', 'AA'], automation: ['manual', 'partial'] });
  await testInfo.attach('manual-checks.html', {
    body: renderProcedures(left, { record: false }),
    contentType: 'text/html'
  });
});

Eine Sitzung mit einer Person, die einen Screenreader nutzt. Nur das, was einen Screenreader braucht, für eine Sitzung mit einer Person, die täglich einen nutzt:

const sr = listProcedures({ levels: ['A', 'AA'], tools: 'screen-reader' });
fs.writeFileSync('screen-reader-session.html', renderProcedures(sr, { title: 'Screen reader session' }));

Dokumentation. Eine Markdown-Datei pro Standard in einer Dokumentationswebsite oder einem Repository, neu erzeugt, wenn core aktualisiert wird, sodass ein Team dieselben Prüfverfahren liest, die seine Werkzeuge verwenden. Ein Kriterium, wo es gebraucht wird: Ein Tool, das einen Befund zeigt, kann zeigen, wie sein ganzes Kriterium zu bewerten ist, mit renderProcedures(proceduresFor('1.4.12', { locale: 'de' }), { fragment: true }).

Der Standard eines Packs

Der Standard eines Packs kann sagen, wie eine Person seine eigenen Anforderungen bewertet, und jede der obigen Funktionen liest ihn, wenn sie die Packs erhält: nach seinen eigenen Nummern und Gruppen, in seiner eigenen Sprache, wo er eine angibt. Eine Anforderung, die ein WCAG-Kriterium wiedergibt, übernimmt dessen Prüfverfahren, gelesen als die Anforderung („which fails EN 301 549 9.1.4.3“). Seit core 1.16.0 listet eine Facette auch die Regeln von core auf, die die Zuordnung des Standards dem zuweist, was sie bewertet (mappedRules, und im mappedRules eines Checklistenpunkts), sodass eine Anforderung oder ein Test, den nur Regeln von core prüfen, nicht ungeprüft aussieht.

const en301549 = require('@surea11y/pack-en301549');
 
proceduresFor('9.1.4.3', { packs: [en301549], standard: 'en301549', version: 'V4.1.1', locale: 'fr' });
relatedRequirements('1.4.3', { packs: [en301549] });
// [{ standard: 'EN 301 549', id: '9.1.4.3', version: 'V4.1.1', relation: 'restates', … }]
 
const options = { packs: [en301549], standard: 'en301549', version: 'V4.1.1', locale: 'fr' };
fs.writeFileSync('en-301-549.html', renderProcedures(procedureChecklist(options), { packs: [en301549] }));

Das EN-301-549-Pack 1.2.0 liefert Prüfverfahren für jede Klausel von Kapitel 9, deren Kriterium eine Regel von core bewertet, in fünf Sprachen, und das WAI-ARIA-Pack liefert eine Checkliste für jede seiner Anforderungen, mit den gültigen Rollen, Zuständen und Werten vollständig aufgeführt. Ein Pack, das keine Prüfverfahren mitbringt, ändert nichts: Die von WCAG sind mit ihm dieselben wie ohne es.