Automatisierte Accessibility-Tests in der CI-Pipeline

1. Warum Barrierefreiheit in der CI-Pipeline ankommen muss

Ein einmaliges Accessibility-Audit vor dem Launch fühlt sich nach einem sauberen Abschluss an, ist aber nur eine Momentaufnahme. Jedes neue Feature, jede Layout-Anpassung und jedes aktualisierte Drittanbieter-Skript kann neue Barrieren einführen, ohne dass es in einem klassischen Review auffällt. Ohne automatisierte Kontrolle in der CI-Pipeline schleichen sich Regressionen unbemerkt ein, bis der nächste manuelle Audit sie Monate später wieder aufdeckt, oft erst nachdem sich Nutzer beschwert haben oder eine Abmahnung ins Haus steht.

Mit dem Barrierefreiheitsstärkungsgesetz (BFSG) und der europäischen Richtlinie zur Barrierefreiheit ist Accessibility für viele Onlineshops seit 2025 keine Kür mehr, sondern eine rechtliche Pflicht. Automatisierte Tests, die bei jedem Pull Request laufen, verschieben die Verantwortung von einem seltenen, teuren Audit hin zu einem kontinuierlichen Sicherheitsnetz, das genau dort ansetzt, wo Regressionen entstehen: im Code-Review, bevor er in den Main-Branch gemerged wird. Das reduziert nicht nur rechtliches Risiko, sondern auch den Aufwand, der entsteht, wenn Probleme erst spät im Entwicklungszyklus gefunden werden.

2. Was axe-core automatisiert erkennt und was nicht

axe-core ist die am weitesten verbreitete Open-Source-Engine für automatisierte Accessibility-Scans und liegt praktisch jedem gängigen Testwerkzeug zugrunde, von Lighthouse über WAVE bis zu den Browser-Plugins. Die Engine prüft das gerenderte DOM gegen Hunderte Regeln, die aus den WCAG-Erfolgskriterien abgeleitet sind: fehlende Alternativtexte, unzureichender Farbkontrast, doppelte IDs, ungültige ARIA-Attribute, fehlende Formularlabels und strukturelle Verstöße wie eine falsche Heading-Hierarchie. Diese Regeln sind deterministisch und lassen sich zuverlässig in jedem Testlauf reproduzieren.

Der entscheidende Fakt, den Teams oft unterschätzen: Automatisierte Scanner wie axe-core decken nach Angaben von Deque Systems, den Machern der Engine, realistisch nur etwa ein Drittel aller WCAG-Verstöße ab. Was axe-core syntaktisch prüfen kann, prüft es zuverlässig, aber die semantische Qualität eines Alternativtexts, die logische Reihenfolge beim Tabben oder ob eine ARIA-Live-Region tatsächlich sinnvoll angesagt wird, entzieht sich einer rein strukturellen Analyse. Ein aria-label="Klick hier" ist für axe-core technisch korrekt, für einen Screenreader-Nutzer aber wertlos.

<!-- axe-core erkennt dies zuverlässig: Button ohne zugänglichen Namen -->
<button class="icon-btn" onclick="removeItem(id)">
  <svg aria-hidden="true"><use href="#icon-trash"></use></svg>
</button>

<!-- axe-core lässt dies durch, obwohl das Label bedeutungslos ist -->
<button aria-label="Klick hier" onclick="removeItem(id)">
  <svg aria-hidden="true"><use href="#icon-trash"></use></svg>
</button>

<!-- Korrekt: zugänglicher Name beschreibt die tatsächliche Aktion -->
<button aria-label="Artikel aus Warenkorb entfernen" onclick="removeItem(id)">
  <svg aria-hidden="true"><use href="#icon-trash"></use></svg>
</button>

3. axe-core in eine bestehende E2E-Suite integrieren

Der pragmatischste Einstieg ist nicht der Aufbau einer separaten Accessibility-Testsuite, sondern die Erweiterung der ohnehin vorhandenen End-to-End-Tests. Wer bereits mit Playwright oder Cypress Checkout-Flows, Produktseiten und das Login testet, kann in genau diesen Tests einen zusätzlichen axe-core-Scan anhängen, nachdem die Seite geladen und interaktiv ist. Das Paket @axe-core/playwright stellt dafür einen AxeBuilder bereit, der den kompletten sichtbaren DOM-Baum gegen die gewünschten WCAG-Level scannt und eine strukturierte Liste von Verstößen zurückgibt.

Wichtig ist, den Scan gezielt zu platzieren: erst nachdem Alpine.js-Komponenten initialisiert sind und dynamische Inhalte wie Warenkorb-Zähler oder Ladeanimationen fertig gerendert haben, sonst prüft axe-core einen unvollständigen Zwischenzustand. Mit .withTags() lässt sich der Regelsatz auf die relevanten WCAG-Konformitätsstufen einschränken, und mit .exclude() können bekannte Drittanbieter-Widgets, die man nicht selbst pflegt, gezielt aus dem Scan herausgenommen werden, ohne die gesamte Prüfung zu deaktivieren.

// tests/accessibility/checkout.spec.js
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('Accessibility: checkout flow', () => {
  test('cart page has no new axe violations', async ({ page }) => {
    await page.goto('/checkout/cart');

    // Reuse the same page object as the functional E2E suite
    await page.waitForSelector('[data-testid="cart-summary"]');

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
      .exclude('#hyva-cookie-banner') // known third-party widget, tracked separately
      .analyze();

    expect(results.violations).toEqual([]);
  });
});

4. Baseline-Strategie: neue Verstöße blocken, nicht bestrafen

Der häufigste Grund, warum Teams automatisierte Accessibility-Tests nach wenigen Wochen wieder abschalten: Beim ersten Scan eines gewachsenen Shops meldet axe-core sofort Dutzende oder Hunderte Verstöße, der Build ist rot, und niemand kann realistisch alle Altlasten in einem Pull Request beheben. Die Lösung ist keine Ausnahmeregel pro Test, sondern eine Baseline-Datei: ein versioniertes JSON-Dokument, das den aktuellen Ist-Zustand bekannter Verstöße mit Ticket-Referenz und Begründung festhält.

Jeder CI-Lauf vergleicht die aktuellen Scan-Ergebnisse gegen diese Baseline. Verstöße, die bereits dokumentiert sind, lassen den Build grün bleiben, aber jeder neue, bisher unbekannte Verstoß führt zum Abbruch. So verhindert man zwei Extreme gleichzeitig: einen dauerhaft roten Build, den niemand mehr ernst nimmt, und eine Pipeline, die stillschweigend neue Barrieren durchwinkt. Die Baseline selbst wird nur bewusst aktualisiert, wenn ein bekannter Fehler behoben wurde, idealerweise über denselben Pull-Request-Review-Prozess wie jede andere Codeänderung.

{
  "baseline": {
    "generatedAt": "2026-06-01T09:00:00Z",
    "url": "/checkout/cart",
    "knownViolations": [
      {
        "id": "color-contrast",
        "impact": "serious",
        "nodes": 2,
        "ticket": "A11Y-142",
        "note": "Legacy price badge, fix scheduled for Q3"
      },
      {
        "id": "aria-required-children",
        "impact": "critical",
        "nodes": 1,
        "ticket": "A11Y-118",
        "note": "Third-party review widget markup"
      }
    ]
  }
}

5. Praxisbeispiel: CI-Pipeline für Accessibility-Checks

In der Praxis läuft der Accessibility-Job als eigenständiger Schritt neben den funktionalen E2E-Tests, meist bei jedem Pull Request gegen den Main-Branch. Der Job installiert Abhängigkeiten, startet Playwright mit Chromium, führt die Accessibility-Suite gegen eine Staging-Umgebung aus und schreibt die Rohergebnisse als JSON-Report weg. Ein separates Skript vergleicht diesen Report anschließend gegen die Baseline-Datei aus dem vorherigen Abschnitt und entscheidet über Erfolg oder Abbruch des Jobs.

Entscheidend für die Akzeptanz im Team ist, dass der Report als Artefakt hochgeladen wird, unabhängig davon, ob der Job erfolgreich war. So kann jeder Entwickler die konkreten Verstöße inklusive betroffener DOM-Knoten direkt aus der Pipeline-Ausgabe nachvollziehen, statt den Test lokal erneut ausführen zu müssen. Die GitHub-Actions-Annotation-Syntax ::error:: sorgt zusätzlich dafür, dass neue Verstöße direkt als Inline-Kommentar im Pull Request sichtbar werden.

# .github/workflows/accessibility.yml
name: Accessibility Tests
on:
  pull_request:
    branches: [main]

jobs:
  axe-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - name: Run accessibility suite against staging
        run: npx playwright test tests/accessibility --reporter=json > axe-results.json
      - name: Diff against known baseline
        run: node scripts/diff-axe-baseline.js axe-results.json baseline/accessibility.json
        # Exits non-zero only when NEW violations are found
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: axe-report
          path: axe-results.json

6. Was manuelle Prüfung weiterhin leisten muss

Automatisierte Scans ersetzen keine Tastaturbedienung von Hand. Nur ein Mensch, der konsequent mit Tab durch eine Seite navigiert, bemerkt zuverlässig, ob der Fokus in einer logischen Reihenfolge wandert, ob ein Modal den Fokus korrekt einfängt und beim Schließen wieder freigibt, oder ob ein Dropdown eine Tastaturfalle ist, aus der man nicht mehr herauskommt. axe-core kann prüfen, ob ein Element fokussierbar ist, aber nicht, ob die Fokus-Reihenfolge inhaltlich Sinn ergibt.

Genauso unverzichtbar bleibt der Test mit einem echten Screenreader wie NVDA, JAWS oder VoiceOver: Wird eine Fehlermeldung im Formular tatsächlich angesagt, sobald sie erscheint? Ist die Reihenfolge, in der Inhalte vorgelesen werden, für den Kontext sinnvoll? Ergänzend braucht es kognitive und motorische Perspektiven, etwa ob Zeitlimits verlängerbar sind oder ob Klickflächen für Menschen mit eingeschränkter Feinmotorik groß genug sind. Ein realistischer Testplan kombiniert deshalb automatisierte CI-Checks mit einem festen manuellen Prüfzyklus, etwa vor jedem größeren Release.

7. Besonderheiten bei Magento- und Hyvä-Shops

Hyvä-Shops rendern große Teile der Interaktivität clientseitig über Alpine.js: Minicart, Filter-Overlays, Quantity-Selectoren und Checkout-Schritte bauen sich erst nach dem initialen HTML-Response weiter auf. Ein axe-core-Scan, der zu früh ausgeführt wird, prüft einen unvollständigen Zustand mit x-cloak-Elementen, die eigentlich sichtbar sein sollten, oder Komponenten, die ihre finalen ARIA-Attribute erst nach der Alpine-Initialisierung setzen. In Playwright-Tests hilft es, gezielt auf ein Attribut oder eine CSS-Klasse zu warten, die erst nach vollständiger Hydration gesetzt wird, statt sich auf feste Timeouts zu verlassen.

Eine zweite Besonderheit sind Drittanbieter-Komponenten, die in Magento-Shops häufig eingebunden werden: Payment-Widgets, Cookie-Banner, Review-Plugins oder Chat-Widgets liefern oft eigenes Markup, das man nicht kontrolliert und dessen Verstöße man nicht sofort beheben kann. Diese Bereiche gehören konsequent per .exclude() aus dem automatisierten Scan herausgenommen und stattdessen über einen separaten Prozess mit dem jeweiligen Anbieter adressiert, damit die eigene Baseline nicht mit fremden Problemen aufgebläht wird.

8. Reporting, Ownership und Team-Workflow

Ein CI-Job, der nur "rot" oder "grün" meldet, hilft im Alltag wenig, wenn niemand weiß, wer für welchen Verstoß zuständig ist. Sinnvoll ist ein Diff-Skript, das für jeden neuen Verstoß eine strukturierte Meldung mit Regel-ID, Schweregrad und betroffenen DOM-Knoten ausgibt und den Build gezielt nur dann fehlschlagen lässt, wenn wirklich neue Probleme auftauchen. axe-core klassifiziert jeden Verstoß automatisch mit einem impact-Wert von minor bis critical, was sich direkt für eine Priorisierung im Ticketsystem nutzen lässt.

In der Praxis bewährt sich, kritische und schwerwiegende Verstöße automatisch als Ticket zu erstellen und dem verantwortlichen Team zuzuweisen, während kleinere Verstöße gesammelt in einem wöchentlichen Review besprochen werden. Ein Trend-Dashboard, das die Anzahl offener Verstöße über Zeit visualisiert, macht Fortschritt sichtbar und verhindert, dass sich neue Altlasten unbemerkt in der Baseline ansammeln, weil jede Baseline-Erweiterung bewusst und mit Begründung erfolgen sollte.

// scripts/diff-axe-baseline.js
import fs from 'node:fs';

const [, , resultsPath, baselinePath] = process.argv;
const results = JSON.parse(fs.readFileSync(resultsPath, 'utf8'));
const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));

const knownIds = new Set(baseline.baseline.knownViolations.map(v => v.id));
const newViolations = results.violations.filter(v => !knownIds.has(v.id));

if (newViolations.length > 0) {
  for (const v of newViolations) {
    console.log(`::error::New a11y violation "${v.id}" (${v.impact}) on ${v.nodes.length} node(s)`);
  }
  process.exit(1); // fail the build only for regressions
}

console.log(`OK: ${results.violations.length} known violations unchanged, no regressions.`);
process.exit(0);

9. Werkzeuge und Ansätze im Vergleich

Für automatisierte Accessibility-Tests gibt es mehrere etablierte Werkzeuge, die sich in Tiefe, Integrationsaufwand und Fokus unterscheiden. axe-core bildet dabei meist das Fundament, auf dem andere Tools aufsetzen, während manuelle Verfahren gezielt die Lücken abdecken, die kein automatisierter Scanner schließen kann. Die folgende Übersicht stellt typische Aufgaben den unsicheren und den empfohlenen Vorgehensweisen gegenüber.

Kein einzelnes Werkzeug deckt die gesamte Bandbreite an WCAG-Kriterien ab, weshalb sich die Kombination aus automatisiertem Scan in der CI-Pipeline und einem festen manuellen Prüfzyklus in der Praxis durchgesetzt hat. Wer nur auf axe-core setzt, bekommt ein falsches Sicherheitsgefühl, wer nur manuell testet, verliert die kontinuierliche Regressionsabsicherung bei jedem Commit.

10. Zusammenfassung

Die wichtigsten Bausteine für automatisierte Accessibility-Tests in der CI-Pipeline lösen ein wiederkehrendes Problem: einmalige Audits veralten, sobald der nächste Commit gemerged wird. axe-core, integriert in die ohnehin vorhandene E2E-Suite mit Playwright oder Cypress, prüft bei jedem Pull Request automatisch gegen die WCAG-Erfolgskriterien und deckt dabei realistisch rund ein Drittel aller Verstöße ab. Eine Baseline-Strategie sorgt dafür, dass der Build nur bei neuen, bisher unbekannten Verstößen fehlschlägt, während dokumentierte Altlasten kontrolliert abgebaut werden, statt die Pipeline dauerhaft rot zu blockieren.

Der entscheidende Punkt bleibt: Automatisierung ist ein Sicherheitsnetz gegen Regressionen, kein Ersatz für manuelle Prüfung. Tastaturnavigation, Screenreader-Tests und die semantische Qualität von Beschreibungstexten erfordern weiterhin menschliches Urteilsvermögen. Wer beide Ebenen kombiniert, kontinuierliche CI-Checks und einen festen manuellen Prüfzyklus, baut Barrierefreiheit als festen Bestandteil des Entwicklungsprozesses auf, statt sie als jährliches Compliance-Projekt zu behandeln.

11. FAQ: Automatisierte Accessibility-Tests in der CI-Pipeline