Was ist Axe DevTools mit Cypress?
Axe DevTools bezeichnet eine Familie von Barrierefreiheits-Werkzeugen des US-Unternehmens Deque Systems. Das Herzstück bildet die Open-Source-Engine axe-core, die Webseiten automatisiert gegen die WCAG-Richtlinien (Web Content Accessibility Guidelines) prüft. Über das Community-Plugin cypress-axe lässt sich diese Engine direkt in das End-to-End-Testframework Cypress einbinden, sodass Accessibility-Prüfungen bei jedem Testlauf automatisch mitlaufen.
Was diese Kombination besonders macht: Cypress führt Tests in einem echten Browser aus. Statt nur den statischen HTML-Quellcode zu analysieren, prüft axe-core die tatsächlich gerenderte Seite inklusive CSS, JavaScript-Interaktionen und dynamisch nachgeladener Inhalte. Das Ergebnis sind zuverlässigere Testergebnisse als bei rein statischen Analysetools. Deque garantiert dabei Zero False Positives. Jeder gemeldete Verstoß ist ein echtes Problem, das behoben werden sollte.
Seit der Veröffentlichung hat axe-core laut npm über 3 Milliarden Downloads erreicht und wird unter anderem auch von Google Lighthouse als Prüfengine verwendet. Die aktuelle Version von cypress-axe (1.7.0) unterstützt Cypress ab Version 10 und prüft gegen WCAG 2.0, 2.1 sowie 2.2 auf den Konformitätsstufen A, AA und AAA. Für Teams, die bereits mit Google Lighthouse Accessibility Audits arbeiten, ist cypress-axe der logische nächste Schritt: weg von manuellen Einzelprüfungen, hin zu automatisierten Tests in jeder CI/CD-Pipeline.
Erreichen Sie unsere Spezialisten zu barrierefreien Webdesign
Wir sind hier, um Ihnen zu helfen. Gemeinsam meistern wir Ihre digitalen Herausforderungen und fördern die Inklusion im Internet. Lassen Sie uns Ihre Projekte mit barrierefreiem Webdesign erfolgreich machen.
Die axe-core Engine im Detail
Axe-core ist eine regelbasierte JavaScript-Bibliothek, die den DOM (Document Object Model) einer Webseite systematisch gegen vordefinierte Accessibility-Regeln prüft. Jede dieser Regeln bildet ein oder mehrere WCAG-Erfolgskriterien ab. Nach der Analyse liefert die Engine für jedes geprüfte Element eines von vier Ergebnissen:
- Pass (bestanden): Das Element erfüllt die Regel vollständig
- Fail (Verstoß): Ein konkretes Barrierefreiheitsproblem wurde erkannt
- Incomplete (unvollständig): Die Regel konnte nicht automatisch entschieden werden und erfordert manuelle Überprüfung
- Inapplicable (nicht zutreffend): Die Regel ist für das Element nicht relevant
Deque Systems beziffert die automatisierte Erkennungsrate auf durchschnittlich 57 Prozent aller WCAG-Verstöße. Dieser Wert liegt über dem Branchendurchschnitt, hat aber eine natürliche Grenze. Kriterien wie die inhaltliche Qualität von Alternativtexten, eine sinnvolle Tab-Reihenfolge oder die Verständlichkeit von Linktexten erfordern menschliches Urteilsvermögen. Kein automatisiertes Werkzeug kann diese Aspekte vollständig bewerten.
Die Engine deckt unter anderem folgende Prüfbereiche ab:
- Farbkontraste nach WCAG 1.4.3 und 1.4.6: Verhältnis zwischen Text- und Hintergrundfarbe
- ARIA-Validierung: Korrekte Verwendung von Rollen, States und Properties für Screenreader
- Dokumentstruktur: Heading-Hierarchie, Landmark-Regionen und semantisches Markup
- Formularanbindung: Verknüpfung zwischen Eingabefeldern und beschreibenden Labels
- Bildalternativen: Vorhandensein und Korrektheit von alt-Attributen
- Tastaturzugänglichkeit: Fokus-Indikatoren, tabindex-Probleme und Tastaturfallen
Ein besonders praktischer Aspekt: Axe-core erkennt automatisch, welche Regeln für den aktuellen Seitenkontext relevant sind. Enthält eine Seite keine Formulare, werden formularspezifische Regeln übersprungen. Das beschleunigt den Scan und reduziert überflüssige Meldungen erheblich.
cypress-axe installieren und konfigurieren
Die Einrichtung von cypress-axe gelingt in wenigen Minuten. Das Plugin fungiert als Brücke zwischen der axe-core-Engine und dem Cypress-Testrunner. Drei npm-Pakete werden benötigt: axe-core als Prüfengine, cypress als Testframework und cypress-axe als Verbindungsstück.
npm install --save-dev axe-core cypress cypress-axe
Im nächsten Schritt wird cypress-axe in der Cypress-Support-Datei registriert. Ab Cypress 10 befindet sich diese unter cypress/support/e2e.js (oder e2e.ts bei TypeScript-Projekten):
import 'cypress-axe'
Damit stellt cypress-axe zwei zentrale Befehle bereit. cy.injectAxe() lädt die axe-core-Bibliothek in den DOM der getesteten Seite. cy.checkA11y() startet den eigentlichen Accessibility-Scan. Der einfachste Test prüft eine komplette Seite auf Barrierefreiheit:
describe('Barrierefreiheit der Startseite', () => {
beforeEach(() => {
cy.visit('/');
cy.injectAxe();
});
it('erkennt keine Accessibility-Verstoesse', () => {
cy.checkA11y();
});
});
Die Reihenfolge ist entscheidend: cy.injectAxe() muss immer nach cy.visit() stehen, da die Engine in den geladenen DOM injiziert wird. Weil Cypress jeden Test in einem frischen Browserkontext ausführt, gehört der Aufruf in den beforeEach-Block. Findet der Scan Verstöße, schlägt der Test mit einem AssertionError fehl. Im Cypress-Testrunner erscheint dann ein rot markierter Eintrag A11Y ERROR! für jeden gefundenen Verstoßtyp.
TypeScript-Projekte benötigen zusätzlich die Typdeklaration in der tsconfig.json:
{
"compilerOptions": {
"types": ["cypress", "cypress-axe"]
}
}
Prüfungen gezielt steuern und filtern
Die wahre Stärke von cypress-axe zeigt sich in den Konfigurationsmöglichkeiten. Der Befehl cy.checkA11y() akzeptiert drei Parameter: den Prüfbereich (CSS-Selektor oder null für die gesamte Seite), ein Options-Objekt für die axe-core-Konfiguration und eine Callback-Funktion für benutzerdefinierte Ausgaben.
Seitenbereich eingrenzen: Nicht immer soll die komplette Seite gescannt werden. Third-Party-Widgets oder Cookie-Banner lassen sich gezielt ausschließen:
// Nur den Hauptbereich pruefen
cy.checkA11y('#main-content');
// Cookie-Banner und externe Widgets ignorieren
cy.checkA11y(null, {
exclude: ['.cookie-consent', '.external-widget']
});
WCAG-Level einschränken: Standardmäßig prüft axe-core alle verfügbaren Regeln. Über den Parameter runOnly lässt sich der Scan auf bestimmte WCAG-Versionen oder Konformitätsstufen begrenzen:
// Nur WCAG 2.1 Level AA
cy.checkA11y(null, {
runOnly: {
type: 'tag',
values: ['wcag21aa', 'wcag2aa']
}
});
Nach Schweregrad filtern: Axe-core klassifiziert jeden Verstoß in eine von vier Impact-Stufen: critical (Inhalte nicht wahrnehmbar oder bedienbar), serious (erhebliche Einschränkung), moderate (Workaround vorhanden) und minor (geringfügige Beeinträchtigung). Bei Legacy-Projekten mit vielen bestehenden Problemen empfiehlt sich ein gestufter Ansatz:
// Phase 1: Nur kritische Verstoesse blockieren
cy.checkA11y(null, {
includedImpacts: ['critical', 'serious']
});
Strukturierte Terminal-Ausgabe: In CI/CD-Umgebungen ohne Browser-UI hilft ein Custom Callback, die Ergebnisse tabellarisch im Terminal anzuzeigen:
function logViolations(violations) {
cy.task(
'log',
violations.length + ' Verstoesse gefunden'
);
const data = violations.map(
({ id, impact, description, nodes }) => ({
id,
impact,
description,
betroffene_elemente: nodes.length
})
);
cy.task('table', data);
}
cy.checkA11y(null, null, logViolations);
Der Parameter skipFailures verdient besondere Erwähnung. Setzt man ihn auf true, protokolliert cypress-axe Verstöße zwar in der Konsole, lässt den Test aber bestehen. Das eignet sich als temporäre Maßnahme bei der schrittweisen Einführung in ein bestehendes Projekt. Langfristig sollte skipFailures immer auf false stehen, damit jeder Verstoß den Build blockiert.
Integration in CI/CD-Pipelines
Accessibility-Tests entfalten ihren größten Nutzen, wenn sie bei jedem Commit automatisch laufen. So werden Regressionen erkannt, bevor sie in die Produktion gelangen. Die Integration in bestehende Pipelines ist unkompliziert, weil cypress-axe als regulärer Cypress-Test ausgeführt wird.
Ein GitHub-Actions-Workflow für automatisierte Barrierefreiheitstests:
name: Accessibility Tests
on: [push, pull_request]
jobs:
a11y:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm start &
- run: npx wait-on http://localhost:3000
- run: npx cypress run --spec 'cypress/e2e/a11y/**'
Quality Gates schrittweise verschärfen: Für Legacy-Projekte bewährt sich ein inkrementeller Ansatz. Im ersten Sprint blockieren nur critical-Verstöße den Build. Mit jedem weiteren Sprint wird der Schwellenwert gesenkt, bis schließlich alle Impact-Stufen den Build brechen:
- Phase 1 (Sprint 1 bis 2): Nur critical blockiert den Build
- Phase 2 (Sprint 3 bis 4): critical und serious als Fehler
- Phase 3 (Sprint 5 bis 8): Alle vier Impact-Stufen aktivieren
- Phase 4 (fortlaufend): Zusätzliche WCAG AAA-Regeln einbeziehen
Dieser Stufenplan verhindert, dass ein Team am ersten Tag von hunderten Fehlermeldungen überwältigt wird. Stattdessen werden die kritischsten Probleme zuerst adressiert, während das Team parallel lernt, barrierefreien Code zu schreiben.
Alternativ zur Open-Source-Lösung bietet Cypress seit 2024 die kostenpflichtige Cypress Accessibility Cloud an. Diese analysiert alle Seitenzustände, die während regulärer E2E-Tests durchlaufen werden, serverseitig auf Verstöße. Der Vorteil: kein zusätzlicher Code nötig, keine Verlangsamung der Tests. Die Ergebnisse erscheinen als interaktive Reports mit DOM-Snapshots direkt in der Cypress Cloud. Seit 2025 unterstützt die Cloud-Lösung auch Branch-Review, das automatisch neue Verstöße erkennt, die durch einen Pull Request eingeführt wurden.
cypress-axe, Cypress Accessibility Cloud und axe Watcher im Vergleich
| Kosten | Open Source (kostenlos) | Kostenpflichtig (Cloud-Abo bzw. Deque-Lizenz) |
| Setup-Aufwand | npm install, Support-Datei anpassen | Kein Code nötig (Cloud) bzw. minimale Konfiguration (Watcher) |
| Performance-Impact | Leichte Testverlangsamung | Kein Impact (serverseitig) bzw. minimaler Overhead |
| Reporting | Terminal-Output und Cypress UI | Interaktive Cloud-Reports mit DOM-Snapshots bzw. Developer Hub |
| CI/CD-Anbindung | Jede Pipeline, volle Kontrolle | Cypress Cloud API bzw. GitHub Actions und REST-API |
| Konfigurierbarkeit | Volle Kontrolle über Regeln und Bereiche | Profile und Run-Tags (Cloud) bzw. Deque-Konfiguration |
| Ideal für | Open-Source-Projekte mit voller Kontrolle | Enterprise-Teams mit Cloud-Abo oder Deque-Ökosystem |
Axe DevTools Browser Extension und das Deque-Ökosystem
Neben der programmatischen Integration über cypress-axe bietet Deque Systems die Axe DevTools Browser Extension als ergänzendes Werkzeug an. Die Extension steht für Chrome, Firefox und Edge bereit und verzeichnet laut Deque über 800.000 Installationen allein im Chrome Web Store. Sie eignet sich besonders für die explorative Prüfung während der Entwicklung: Einzelne Seiten lassen sich per Klick scannen, gefundene Verstöße werden direkt in den Browser DevTools angezeigt.
Per Klick auf einen Verstoß springt die Ansicht zum betroffenen DOM-Element. Jedes Issue enthält eine Beschreibung, den Impact-Level, die verletzte WCAG-Regel und einen konkreten Lösungsvorschlag mit Verweis auf die Deque University Dokumentation.
Die kostenpflichtige Pro-Version erweitert den Funktionsumfang um Intelligent Guided Tests (IGTs). Dabei handelt es sich um KI-gestützte Prüfabläufe, die Entwickler durch gezielte Fragen zum Seiteninhalt führen. Aus den Antworten generiert das Tool einen Bericht über Accessibility-Probleme, die reine Automatisierung nicht erkennen kann. Deque gibt an, dass IGTs den Zeitaufwand für manuelle Tests von rund einer Stunde auf zwei bis drei Minuten reduzieren.
Seit 2025 bietet Deque zusätzlich den Axe MCP Server an, der Accessibility Testing direkt in die IDE bringt. Entwickler erhalten Code-Level-Vorschläge für Fixes und können diese mit einem Klick übernehmen. In Kombination mit der Browser Extension für die Entwicklung und cypress-axe für die Pipeline entsteht eine lückenlose Accessibility-Testing-Kette vom ersten Codeentwurf bis zum Deployment.
Darüber hinaus haben Community-Entwickler weitere Plugins auf Basis von cypress-axe geschaffen. Erwähnenswert sind wick-a11y (automatische HTML-Reports mit Screenshots) und cypress-a11y-report (erweiterte Berichtsformate). Auch der IBM Equal Access Checker bietet eine Cypress-Integration als Alternative zu axe-core. Die Firefox Accessibility Testing Tools ergänzen dieses Setup um browserspezifische Features wie den Farbsehschwächen-Simulator.
No automated scan can prove that the interface is fully accessible and works well for users with disabilities. It is always necessary to understand the limitations and expected coverage provided by the library you choose, and then make a plan to cover the gaps with manual testing.
Fazit: Barrierefreiheit als fester Bestandteil der Qualitätssicherung
Die Kombination aus Cypress und axe-core verwandelt Accessibility Testing von einer optionalen Zusatzaufgabe in einen integrierten Bestandteil der Qualitätssicherung. cypress-axe ist in wenigen Minuten eingerichtet, Open Source und flexibel genug für jede Projektgröße. Die Zero-False-Positive-Garantie von Deque stellt sicher, dass jede Meldung ein reales Problem darstellt, das Aufmerksamkeit verdient.
Der größte Mehrwert liegt in der Automatisierung: Kein fehlerhaftes Kontrastverhalten, kein vergessenes Label und kein defektes ARIA-Attribut gelangt unbemerkt in die Produktion. Gleichzeitig ist es wichtig, die Grenzen realistisch einzuschätzen. Die 57 Prozent automatisiert erkennbarer Probleme bilden ein starkes Fundament, ersetzen aber nicht die manuelle Prüfung mit Screenreadern, Tastaturnavigation und echtem Nutzerfeedback.
Seit dem Barrierefreiheitsstärkungsgesetz (BFSG) ist automatisiertes Accessibility Testing für viele Unternehmen keine Kür mehr, sondern Pflicht. cypress-axe bietet den pragmatischsten Einstieg: kein Lizenzkosten-Risiko, volle Kontrolle über die Konfiguration und eine aktive Community mit über 50 abhängigen Projekten auf npm.
Sie möchten Accessibility Testing systematisch in Ihre Entwicklungspipeline einführen? Never Code Alone unterstützt bei der Einrichtung von cypress-axe, der Definition von Quality Gates und der Schulung Ihres Teams. Von der ersten Pipeline-Konfiguration bis zur nachhaltigen Barrierefreiheitskompetenz. Vereinbaren Sie eine kostenlose Erstberatung unter roland@nevercodealone.de oder telefonisch unter +49 176 24747727.
Häufig gestellte Fragen (FAQ)
Die folgenden Fragen beantworten die wichtigsten Aspekte rund um Axe DevTools, das cypress-axe Plugin und automatisiertes Accessibility Testing mit Cypress. Von der Installation über die Konfiguration bis zur strategischen Einführung in bestehende Projekte.
Was ist cypress-axe und warum ist es 2026 so verbreitet?
cypress-axe ist ein Open-Source-Plugin, das die axe-core Accessibility Engine von Deque Systems in das Cypress Testframework integriert. Mit über 3 Milliarden axe-core Downloads und der aktuellen cypress-axe Version 1.7.0 ist es 2026 der De-facto-Standard für automatisiertes Barrierefreiheitstesting im JavaScript-Ökosystem.
Welche WCAG-Regeln prüft axe-core mit Cypress 2026?
Axe-core prüft gegen WCAG 2.0, 2.1 und 2.2 auf den Konformitätsstufen A, AA und AAA. Die Engine deckt Bereiche wie Farbkontraste, ARIA-Validierung, Formular-Labels, Alternativtexte und Tastaturzugänglichkeit ab. Durchschnittlich erkennt sie 57 Prozent aller WCAG-Verstöße automatisiert.
Wie installiert man cypress-axe in einem Projekt 2026?
Die Installation erfolgt über npm mit dem Befehl npm install --save-dev axe-core cypress cypress-axe. Anschließend wird in der Datei cypress/support/e2e.js der Import import 'cypress-axe' ergänzt. Danach stehen cy.injectAxe() und cy.checkA11y() als Testbefehle zur Verfügung.
Ist cypress-axe 2026 BFSG-konform einsetzbar?
cypress-axe prüft gegen dieselben WCAG-Kriterien, die das Barrierefreiheitsstärkungsgesetz (BFSG) als Mindeststandard verlangt. Automatisierte Tests allein reichen für vollständige BFSG-Konformität nicht aus, bilden aber eine solide Grundlage, die durch manuelle Prüfungen ergänzt werden sollte.
Welche Alternativen zu cypress-axe gibt es 2026?
Die kostenpflichtige Cypress Accessibility Cloud analysiert Seitenzustände serverseitig ohne zusätzlichen Code. Axe Watcher von Deque bietet Git-aware Reporting und Developer Hub Integration. Community-Plugins wie wick-a11y erweitern cypress-axe um HTML-Reports mit Screenshots.
Wie unterscheidet sich cypress-axe von Google Lighthouse?
Google Lighthouse nutzt axe-core als eine von mehreren Prüfquellen und liefert einen Gesamtscore. cypress-axe ermöglicht dagegen gezielte Tests einzelner Seitenbereiche, lässt sich in CI/CD-Pipelines automatisieren und bietet feingranulare Kontrolle über Regeln, Impact-Level und Ausschlüsse.
Kann cypress-axe auch Single Page Applications testen?
Ja. Da Cypress in einem echten Browser läuft und cypress-axe den gerenderten DOM analysiert, werden auch dynamisch nachgeladene Inhalte und JavaScript-basierte UI-Änderungen erfasst. Nach Navigation oder State-Wechsel genügt ein erneuter Aufruf von cy.checkA11y().
Was bedeutet Zero False Positives bei axe-core?
Deque Systems garantiert, dass jeder von axe-core gemeldete Verstoß ein tatsächliches Accessibility-Problem darstellt. Im Gegensatz zu vielen anderen Tools gibt es keine fälschlichen Alarme. Elemente, die nicht eindeutig bewertet werden können, erhalten den Status Incomplete statt Fail.
Wie lässt sich cypress-axe in Legacy-Projekte einführen?
Der empfohlene Ansatz ist ein stufenweises Vorgehen. Zunächst nur critical-Verstöße als Build-Fehler werten und den Parameter includedImpacts entsprechend konfigurieren. Mit jedem Sprint den Schwellenwert senken. Der skipFailures Parameter erlaubt anfangs reines Logging ohne Test-Abbruch.
Welche Rolle spielen Intelligent Guided Tests (IGTs)?
IGTs sind KI-gestützte Prüfabläufe in der kostenpflichtigen Axe DevTools Pro Extension. Sie führen Entwickler durch gezielte Fragen und erkennen dabei Accessibility-Probleme, die reine Automatisierung übersieht. Laut Deque reduzieren IGTs die Dauer manueller Tests von einer Stunde auf wenige Minuten.
Unterstützt cypress-axe Component Testing?
Ja, cypress-axe funktioniert sowohl mit End-to-End-Tests als auch mit Cypress Component Tests. Bei Component Tests werden seitenweite Regeln wie Heading-Hierarchie oder Landmark-Regionen automatisch übersprungen, da Komponenten als Fragmente ohne vollständige Seitenstruktur gemountet werden.
Wie hilft Never Code Alone bei der Einführung von Accessibility Testing?
Never Code Alone unterstützt bei der kompletten Einführung: von der initialen cypress-axe Konfiguration über die Definition von Quality Gates bis zur Schulung des Entwicklungsteams. Das Ziel ist nachhaltige Barrierefreiheitskompetenz, nicht einmalige Compliance. Kostenlose Erstberatung unter roland@nevercodealone.de.