Was ist der Accessibility Tree?
Erfahren Sie, wie Browser den Accessibility Tree erstellen, Rollen und Namen bestimmen, ihn in DevTools prüfen und Bedienelemente mit Playwright testen.
Der Accessibility Tree ist eine zweite Repräsentation einer Webseite, die der Browser für assistive Technologien aus dem DOM erzeugt. Er übernimmt für jedes bedeutungstragende Element dessen Rolle, Accessible Name, Zustand und Wert, während die meisten rein layoutbezogenen Wrapper wegfallen.
Sie begegnen ihm, wenn ein Audit „button has no accessible name“ meldet, wenn ein Linter ein klickbares div beanstandet oder wenn Playwrights getByRole ein Element nicht findet, das Sie auf dem Bildschirm sehen. Alle drei beziehen sich auf dieselbe Struktur. Dieser Artikel erklärt, wie der Browser diesen Baum aufbaut, was jeder Knoten enthält, wie Sie ihn inspizieren und wie Sie dagegen testen.
Die wichtigsten Punkte
- Browser erzeugen den Accessibility Tree aus dem DOM, der nativen HTML-Semantik und ARIA-Attributen. Reine Styling-Elemente wie
divundspanerhalten in der Regel keinen eigenen Knoten. - Inhalte, die mit
display: none,visibility: hidden, demhidden-Attribut oderaria-hidden="true"ausgeblendet sind, werden aus dem Accessibility Tree ausgeschlossen, obwohl sie im DOM verbleiben. - Vereinfacht gesagt stammt der Accessible Name eines Elements zuerst aus
aria-labelledby, dann ausaria-label, dann aus nativer Beschriftung (<label>,alt), dann aus dem Textinhalt und schließlich austitle. - Ein
<div>mit Click-Handler hat im Baum keine Button-Rolle. Screenreader kündigen es daher nicht als Bedienelement an, und Tastaturnutzer können es nicht erreichen. - Playwrights
getByRole-Locator und ARIA-Snapshots arbeiten mit Rollen und Accessible Names. Damit geschriebene Tests schlagen also bei genau den Fehlern fehl, die auch Nutzer assistiver Technologien blockieren.
Wie der Browser den Accessibility Tree aufbaut
Browser erzeugen den Accessibility Tree aus drei Quellen: dem DOM, der eingebauten Semantik von HTML-Elementen und etwaigen ARIA-Attributen. HTML-AAM legt fest, wie jedes HTML-Element auf eine zugängliche Rolle abgebildet wird, und Core-AAM 1.2 definiert, wie ARIA-Rollen, -Zustände und -Eigenschaften auf die Accessibility-APIs der Plattform abgebildet werden.
Die Abbildung vom DOM auf den Accessibility Tree ist keine 1:1-Zuordnung. Ein <div> oder <span>, das nur für Flexbox oder Styling existiert, wird in der Regel weggeglättet. Umgekehrt schreibt HTML-AAM vor, dass ein <video> mit dem controls-Attribut seine eingebauten Steuerelemente wie Wiedergabe und Lautstärke als Kindknoten bereitstellt, die auf Rollen wie button und slider abgebildet werden. Keines dieser Steuerelemente taucht im DOM der Seite auf.
Auch ausgeblendete Inhalte werden entfernt. WAI-ARIA 1.2 schließt Elemente aus dem Baum aus, wenn sie nicht dargestellt werden (display: none, visibility: hidden, das HTML-Attribut hidden) oder aria-hidden="true" tragen. Eine CSS-Klasse für „visuell versteckte“ Inhalte bzw. sr-only ist ein anderer Fall: Sie verschiebt Inhalte aus dem sichtbaren Bereich, sodass sie im Baum erhalten bleiben.
Was enthält ein zugänglicher Knoten?
Jeder Knoten im Accessibility Tree stellt bis zu vier Dinge bereit: eine Rolle (was er ist), einen Namen (wie er heißt), Zustände (sein aktueller Status) und bei manchen Bedienelementen einen Wert. Hier eine beschriftete Checkbox:
<label><input type="checkbox" checked> Email me product updates</label>
Im ARIA-Snapshot-Format von Playwright sieht der resultierende Knoten so aus (zur Veranschaulichung):
- checkbox "Email me product updates" [checked]
Die Rolle ist checkbox, das <label> liefert den Namen, und [checked] ist der Zustand. Eine Checkbox vermittelt ihre Information über ihren Checked-Zustand. Ein Wert gilt für Bedienelemente wie Textfelder und Schieberegler; das Snapshot-Format setzt ihn hinter einen Doppelpunkt:
- textbox "Email": ada@example.com
Wie einzelne Rollen bestimmt werden und wann Sie selbst ARIA-Rollen ergänzen sollten, erfahren Sie in Understanding Accessibility Roles in HTML.
Wie wird der Accessible Name berechnet?
Vereinfacht gesagt übernimmt ein Browser den Accessible Name eines Elements aus der ersten Quelle, die einen liefert:
aria-labelledby, das auf den Text anderer Elemente verweistaria-label- Native Beschriftung: ein
<label>-Element oder deralt-Text eines Bildes - Der eigene Textinhalt des Elements, bei Rollen, die eine Benennung aus dem Inhalt erlauben (Buttons, Links)
- Das
title-Attribut als letzte Möglichkeit
ARIA hat Vorrang vor nativer Beschriftung. Hat ein Button den sichtbaren Text „Send“ und aria-label="Submit form", kündigt ein Screenreader „Submit form“ an, und ein Nutzer von Sprachsteuerung, der „click Send“ sagt, erhält womöglich keinen Treffer. Der vollständige Algorithmus einschließlich eingebetteter Bedienelemente und Rekursion ist in Accessible Name and Description Computation 1.2 spezifiziert.
Wie nutzen Screenreader den Accessibility Tree?
Screenreader lesen nicht das DOM. Sie lesen den Accessibility Tree über die Accessibility-API des Betriebssystems, die der Browser implementiert. Die Mapping-Tabellen von Core-AAM decken MSAA mit IAccessible2 sowie UI Automation unter Windows, die AX API (NSAccessibility) unter macOS und ATK/AT-SPI unter Linux ab. Der Screenreader fragt diese Objekte nach Rolle, Name und Zustand ab und reagiert auf Ereignisse wie Fokuswechsel. Erreicht eine Eigenschaft den Baum nie, bekommt der Nutzer sie auch nie zu hören.
So inspizieren Sie den Accessibility Tree
Sowohl die Chrome DevTools als auch die Firefox DevTools zeigen den Accessibility Tree direkt an: Chrome über den Accessibility-Tab im Elements-Panel, Firefox über seinen Accessibility Inspector.
Chrome: Öffnen Sie das Panel Elements, wählen Sie einen Knoten aus und öffnen Sie den Tab Accessibility (er verbirgt sich möglicherweise hinter der Schaltfläche „More Tabs“ »). Dort sehen Sie die berechnete Rolle, den Namen und die Eigenschaften sowie die Herkunft des Namens. Aktivieren Sie Show accessibility tree, um den DOM-Baum im Elements-Panel durch den Accessibility Tree der gesamten Seite zu ersetzen. Beides ist in der Accessibility-Referenz der Chrome DevTools dokumentiert. Zusätzlich bietet Chrome die interne Seite chrome://accessibility für das Debugging auf Browserebene.
Firefox: Der Accessibility Inspector lässt sich über das Kontextmenü der Seite (Inspect Accessibility Properties) öffnen oder per Rechtsklick auf einen Knoten im HTML-Bereich des Inspektors und Auswahl von Show Accessibility Properties. Der Inspektor zeigt Geckos eigenen Accessibility Tree statt Informationen aus der Accessibility-Schicht der Plattform und liefert daher auf jedem Betriebssystem dieselbe Ausgabe.
Zwei Fehler, die der Accessibility Tree offenlegt
Der Accessibility Tree macht zwei häufige Komponentenfehler offensichtlich: ein klickbares div ohne Button-Rolle und einen Icon-Button ohne Accessible Name. Jedes dieser Probleme zeigt sich als fehlende Rolle bzw. fehlender Name. Vue- und Angular-Templates erzeugen dieselbe Ausgabe, denn der Baum sieht nur das gerenderte DOM.
Ein klickbares Div ohne Button-Rolle
// Before
<div className="btn" onClick={save}>Save</div>
// After
<button type="button" onClick={save}>Save</button>
# Before (illustrative)
- text: Save
# After
- button "Save"
Ein <div> mit Click-Handler hat im Accessibility Tree keine Button-Rolle. Ein Screenreader kündigt es nicht als Bedienelement an, und Tastaturnutzer können es weder per Tab erreichen noch mit Enter oder Leertaste auslösen. Session-Replays dieses Fehlers machen die Lücke deutlich: Mausnutzer klicken das Bedienelement problemlos an, während Tastaturnutzer per Tab direkt an etwas vorbeispringen, das wie ein Button aussieht, im Baum aber nicht als solcher existiert.
Ein Icon-Button ohne Namen
// Before
<button onClick={close}><svg aria-hidden="true">{/* icon */}</svg></button>
// After
<button aria-label="Close dialog" onClick={close}>
<svg aria-hidden="true">{/* icon */}</svg>
</button>
# Before (illustrative)
- button
# After
- button "Close dialog"
Ein reiner Icon-Button ohne Text und ohne aria-label erscheint als Button mit leerem Namen. Ein Screenreader kann daher nichts weiter ansagen als „button“.
Den Accessibility Tree mit Playwright testen
Playwrights getByRole-Locator findet Elemente anhand von ARIA-Rolle, ARIA-Attributen und Accessible Name gemäß den W3C-Spezifikationen und berücksichtigt standardmäßig nur nicht ausgeblendete Elemente. Ein Test, der ein Bedienelement über Rolle und Namen findet, prüft damit zugleich, dass das Element diese Rolle und diesen Namen bereitstellt. ARIA-Snapshots gehen noch einen Schritt weiter: locator.ariaSnapshot() und page.ariaSnapshot() liefern eine YAML-Ansicht des Accessibility Tree, und expect(locator).toMatchAriaSnapshot() führt Assertions dagegen aus.
import { test, expect } from '@playwright/test';
test('save control is a real button', async ({ page }) => {
await page.goto('/settings');
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Save"`);
await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Close dialog"`);
});
Führen Sie diesen Test gegen das „Before“-Markup aus, schlägt der getByRole-Aufruf fehl – aus demselben Grund, aus dem ein Screenreader-Nutzer hängen bleibt. Ein Template muss nur einem Teil des Baums entsprechen, und ein Template mit einem einzelnen Knoten wie diese hier passt auf jeder Ebene. Listet ein Template mehrere Knoten auf oberster Ebene auf, müssen diese denselben Elternknoten haben und in derselben Reihenfolge wie im Baum erscheinen. Schlägt ein Locator fehl, geben Sie await page.ariaSnapshot() aus, um zu sehen, was der Baum tatsächlich enthält. Die genannten Namen gelten für JavaScript; die anderen Sprachbindungen bieten Entsprechungen. Die Playwright-Dokumentation weist außerdem darauf hin, dass rollenbasierte Locators keine Accessibility-Audits und Konformitätstests ersetzen. Betrachten Sie sie daher als frühes Feedback.
Rollen- und Namensdaten sind auch über Test-Runner hinaus relevant. Manche KI-gestützten Automatisierungswerkzeuge lesen die semantische Struktur einer Seite – einer der Gründe, warum agentische Browser mit semantischem Markup am besten funktionieren.
Fazit
Der Accessibility Tree ist die Version Ihrer UI, die assistive Technologien tatsächlich erhalten. Eine fehlende Rolle oder ein leerer Name darin bedeutet, dass das Bedienelement für diese Nutzer nicht funktioniert. Öffnen Sie den Accessibility-Tab für Ihre meistgenutzte eigene Komponente, prüfen Sie Rolle und Namen und machen Sie aus dieser Prüfung eine getByRole-Assertion, damit der Fehler dauerhaft behoben bleibt.
FAQs
Behebt role='button' auf einem div das Problem im Accessibility Tree?
Nur teilweise. Mit role='button' erhält das div einen Button-Knoten im Accessibility Tree, sodass Screenreader es als Button ankündigen. Es bekommt dadurch aber kein Button-Verhalten. Das div benötigt weiterhin tabindex='0', um in die Tab-Reihenfolge aufgenommen zu werden, sowie einen keydown-Handler, der die Aktion bei Enter und Leertaste ausführt. Ein natives button-Element bringt Fokussierbarkeit und Tastaturbedienung bereits standardmäßig mit.
Verhindert aria-hidden='true', dass Tastaturnutzer ein Element fokussieren?
Nein. aria-hidden='true' entfernt ein Element samt seinen Nachfahren aus dem Accessibility Tree, wirkt sich aber nicht auf den Tastaturfokus aus. Ein Link, Button oder Eingabefeld innerhalb eines Containers mit aria-hidden kann weiterhin per Tab fokussiert werden. Tastaturnutzer landen dann auf einem Bedienelement, das assistive Technologien nicht benennen können. Ein aria-hidden='false' auf einem Kindelement macht es nicht wieder sichtbar. Um interaktive Inhalte für alle auszublenden, verwenden Sie display: none oder das hidden-Attribut.
Wie kann ich in automatisierten Tests die berechnete Rolle und den Accessible Name eines Elements auslesen?
Verwenden Sie Automatisierungsbefehle statt Seitenskripten. Die W3C-WebDriver-Spezifikation definiert die Befehle Get Computed Role und Get Computed Label, die ChromeDriver implementiert und WebdriverIO als getComputedRole() und getComputedLabel() bereitstellt. Playwright bietet die Assertions toHaveRole() und toHaveAccessibleName() für einzelne Elemente sowie ariaSnapshot() für eine YAML-Ansicht eines ganzen Teilbaums. All diese Werkzeuge liefern die Rolle und den Namen, die assistive Technologien erhalten.
Warum haben sich die Namenstreffer von getByRole nach dem Upgrade auf Playwright 1.65 geändert?
Seit Playwright 1.65 wird Text, den der Browser nicht rendert, nicht mehr in Accessible Names und ARIA-Snapshots einbezogen. Text, der keinem Slot zugewiesen ist oder direkt in einem geschlossenen details-Element steht, zählt nicht mehr. Das kann die Ergebnisse von getByRole() mit name-Option, die Ausgabe von ariaSnapshot() und toMatchAriaSnapshot()-Assertions verändern. Erwartete Namen dürfen daher nur den Text enthalten, den der Browser tatsächlich rendert.
Gain control over your UX
See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.
Star on GitHub12k