Analyse-Werkzeug

Das analyze-Werkzeug führt eine umfassende Barrierefreiheitsanalyse von Webseiten durch, indem es einen Scan über die Axe DevTools Browser-Erweiterung in einer realen Browserumgebung ausführt. Es funktioniert nahtlos mit sowohl lokalen Entwicklungs-URLs (z.B. localhost:3000) als auch mit entfernten Produktions-URLs.

Was es macht

1. Authentifizierung - Validiert die Anmeldedaten des Benutzers (entweder einen API-Schlüssel oder ein OAuth 2.0-Zugriffstoken), um autorisierten Zugriff sicherzustellen
2. Konfigurationsabruf - Ruft die organisationsspezifischen Axe-Konfiguration-Einstellungen des Benutzers ab, einschließlich:
   • Barrierefreiheitstest-Standard (z.B. WCAG 2.2 AA)
   • axe-core Version
   • Überprüfungsbedarf / bewährte Praktiken
   • Erweiterte Regeln Voreinstellung
3. Browserbasierte Analyse - Startet im Hintergrund eine Browser-Instanz mit eingebauter Axe DevTools-Erweiterung
4. Seitennavigation - Navigiert zur vom Benutzer in seiner Eingabe an den KI-Agenten angegebenen URL
5. Barrierefreiheits-Scan - Führt eine vollständige Barrierefreiheitsanalyse der gerendert-Seite mit der Axe DevTools Browser-Erweiterung durch, um sicherzustellen, dass die tatsächliche Benutzererfahrung getestet wird (nicht nur statisches HTML)
6. Ergebnisübermittlung - Gibt umfassende Analyseergebnisse in einem strukturierten Format an den Agenten zurück

Responsives Testen

Das analyze-Werkzeug unterstützt optionale viewportWidth- und viewportHeight-Parameter, die es Ihnen ermöglichen, Seiten bei bestimmten Ansichtsfensterabmessungen zu testen. Dies ist nützlich, um Barrierefreiheitsprobleme zu erkennen, die nur bei bestimmten Bildschirmgrößen auftreten, wie etwa bei mobilen oder Tablet-Breakpoints.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

Wenn beide Parameter weggelassen werden, wird der Scan bei 1000×1080 ausgeführt. Bei alleiniger Übergabe von viewportWidth wird die Höhe auf 1080 voreingestellt; viewportHeight erfordert die Festlegung von viewportWidth. Jede Dimension kann bis zu 7680 Pixel betragen.

Teilschritte scannen

Standardmäßig scannt das analyze-Werkzeug die gesamte Seite. Um den Scan auf einen bestimmten Bereich zu beschränken, übergeben Sie den optionalen selector-Parameter – nützlich, um sich auf eine einzelne Komponente zu konzentrieren oder laute, nicht relevante Teile der Seite von den Ergebnissen auszuschließen.

• Ein einzelner CSS-Selektor-String-Zielt auf ein Element im oberen Rahmen:

  {
    "url": "http://localhost:3000",
    "selector": "#main"
  }

• Ein Array von CSS-Selektoren durchschreitet iframe- oder Schatten-DOM-Grenzen – jedes Segment wählt den Host für den nächsten. Verwenden Sie ein Array nur, wenn sich das Ziel in einem iframe oder Schattenroot befindet:

  {
    "url": "http://localhost:3000",
    "selector": ["iframe#checkout", "#payment-form"]
  }

Ein Array unterstützt bis zu 10 Segmente. Wenn der Selektor kein Element auf der Seite findet, gibt der Scan einen Fehler zurück. Wenn selector weggelassen wird, wird die ganze Seite gescannt.

Fordern Sie Ihren KI-Agenten in natürlicher Sprache auf – der Agent übersetzt Ihre Absicht in den Werkzeugsaufruf:

Scan only the #main region of http://localhost:3000 for accessibility issues

Browserinteraktionen vor dem Scannen

Das analyze-Werkzeug unterstützt ein optionales before-Array von Interaktionsschritten, die nachdem die Seite geladen ist, aber bevor der Barrierefreiheits-Scan ausgeführt werden. Dies eröffnet mehrere reale Testszenarien:

• Login-geschützte Seiten – Anmeldedaten ausfüllen und absenden, bevor die Seite nach der Anmeldung gescannt wird
• Cookie/Einwilligungsbanner – Banner schließen, die ansonsten den Seiteninhalt überlappen oder verdecken würden
• Dynamische Inhalte – Warten, bis clientseitig gerenderte Inhalte (Routenänderungen, spät injizierte DOM) erscheinen, bevor gescannt wird

Die Schritte werden in der gleiche Browserkontext wie der Scan ausgeführt, sodass Cookies, localStorage und alle durch click oder fill ausgelösten Routenänderungen in den Scan fortbestehen.

Das before-Array unterstützt bis zu 20 Schritte. Jeder Schritt erhält sein eigenes Timeout von BROWSER_TIMEOUT_MS (Standard 30000 ms); es gibt keine pro-Schritt-Überschreibung.

Unterstützte Aktionen

Beispiel: Anmelden vor dem Scannen

Fordern Sie Ihren KI-Agenten in natürlicher Sprache auf – der Agent übersetzt Ihre Absicht in den Werkzeugsaufruf:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

Der Agent löst die Eingabeaufforderung auf und ruft das analyze-Tool mit einem ähnlichen Payload auf:

{
  "url": "http://localhost:3000",
  "before": [
    {
      "action": "fill",
      "selector": "#username",
      "value": "<resolved-from-.env.local>"
    },
    {
      "action": "fill",
      "selector": "#password",
      "value": "<resolved-from-.env.local>"
    },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Cookie-Injektion

Das analyze-Tool unterstützt ein optionales cookies-Array, das Cookies auf dem Browser-Kontext vor der Navigation setzt — so werden sie mit der allerersten Anfrage zur Seite gesendet. Dies ist von before Aktionen zu unterscheiden, die nach der Navigation laufen und daher nicht beeinflussen können, wie die anfängliche Anfrage geroutet wird. Zwei häufige Verwendungen:

• Umgebungsrouting — setzen Sie ein Cookie mit einem Staging- oder Feature-Branch-Selektor, das von einer Edge- oder CDN-Schicht gelesen wird, um zu entscheiden, welche Version der Website bereitgestellt werden soll.
• Vor-authentifizierte Sitzungen — injizieren Sie ein gültiges Sitzungs-Cookie, damit der Scan bereits eingeloggt startet, ohne ein Anmeldeformular über before auszuführen.

Das cookies-Array unterstützt bis zu 20 Cookies.

Cookie-Felder

Beispiel: Auf einer vor-authentifizierten Seite landen

Fordern Sie Ihren KI-Agenten in natürlicher Sprache auf – der Agent übersetzt Ihre Absicht in den Werkzeugsaufruf:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

Der Agent löst den Cookie-Wert auf und ruft das analyze-Tool mit einer Nutzlast auf, die so aussieht:

{
  "url": "https://app.example.com",
  "cookies": [
    {
      "name": "session",
      "value": "<resolved-from-.env.local>",
      "domain": "app.example.com"
    }
  ]
}

Screenshots

Das analyze-Tool kann einen Screenshot der Seite mit dem Verstoßbericht zurückgeben, damit Sie sehen können, was gescannt wurde. Übergeben Sie den optionalen screenshot-Parameter, um sich anzumelden — ein leeres Objekt genügt:

{
  "url": "http://localhost:3000",
  "screenshot": {}
}

PNG ist die Standardeinstellung. Setzen Sie format auf "jpeg" für ein kleineres Bild auf fotolastigen Seiten:

{
  "url": "http://localhost:3000",
  "screenshot": { "format": "jpeg" }
}

Das Bild wird als Standard-MCP-Bildblock nach dem Verstoßbericht zurückgegeben.

Was der Screenshot zeigt

• Der sichtbare Viewport, nicht die gesamte Seite. Inhalte unterhalb der Falz werden nicht einbezogen. Um mehr von der Seite zu erfassen, übergeben Sie eine große viewportHeight (z.B. 4096), damit der sichtbare Bereich das abdeckt, was Sie sehen möchten.
• Die Seite, wie sie unmittelbar vor dem Scan gestartet wurde. Die Aufnahme erfolgt direkt vor axe.run(), sodass DOM-Änderungen, die während des Scans auftreten — SPA-Neuladevorgänge, useEffect-Updates, Animationen, laufende Anfragen — nicht erfasst werden. Bei Single-Page-Apps ist diese Verzerrung häufig.

Kosten und Client-Unterstützung

Ob das Bild inline gerendert wird, hängt von Ihrem MCP-Client ab. Der Server gibt immer einen spezifikationsvaliden Bildblock zurück, aber einige Clients kollabieren Tool-Ergebnisse oder lassen Bildvorschauen weg — VS Code mit Copilot zeigt sie an, während Cursor und Claude Desktop dies möglicherweise nicht tun. Eine fehlende Vorschau ist eine clientseitige Anzeigebeschränkung, kein fehlgeschlagener Capture.

Screenshots auf Festplatte speichern

Der Screenshot kann auch in eine Datei geschrieben werden, was der zuverlässige Weg ist, um eine Aufnahme in einem Client zu sehen, der keine Inline-Bilder rendert. Setzen Sie saveTo auf einen absoluten Pfad:

{
  "url": "http://localhost:3000",
  "screenshot": { "saveTo": "/Users/me/Desktop/home.png" }
}

Oder setzen Sie save: true, damit der Server den Dateinamen auswählt:

{
  "url": "http://localhost:3000",
  "screenshot": { "save": true }
}

Der absolute Pfad, der geschrieben wurde, kommt in der messages-Array der Antwort zurück, damit Ihr Agent Ihnen sagen kann, wo Sie die Datei finden.

Das Speichern gilt für nur erfolgreiche Scans. Wenn der Scan nach der Aufnahme des Screenshots fehlschlägt, wird das Bild zusammen mit dem Fehler direkt eingebunden zurückgegeben, unabhängig von inline, und nie auf die Festplatte geschrieben.

Wenn die Aufnahme fehlschlägt

Das Aufnehmen von Screenshots ist ein Best-Effort-Dienst und führt niemals zum Fehlschlagen eines Scans. Wenn die Aufnahme in einen Timeout läuft, liefert der Scan dennoch seine Ergebnisse zusammen mit einer Notiz im messages-Array der Antwort zurück:

Screenshot capture failed: <reason>

Wenn der Scan selbst nach der Aufnahme des Screenshots fehlschlägt, wird das Bild dennoch mit der Fehlermeldung zurückgegeben – der visuelle Zustand der Seite im Moment des Fehlers ist normalerweise das nützlichste Debugging-Material, das Sie haben.

Erweiterte Regeln

Über den Standard-Regelsatz von axe-core hinaus kann das analyze-Tool Erweiterte Regeln ausführen – automatisierte Tests, die Screenshots, Computer Vision und große Sprachmodelle nutzen, um Probleme zu identifizieren, die allein mit axe-core nicht erkannt werden können, wie z.B. Überschriften, die nur wie Überschriften aussehen, oder informative Bilder mit wenig hilfreichem Alternativtext.

Welches Preset ausgeführt wird, wird durch die Axe-Konfiguration Ihrer Organisation bestimmt und kann – wenn es der Administrator erlaubt – auf dem Server mit AXE_ADVANCED_RULES oder beim Scan mit dem advancedRules-Argument überschrieben werden:

{
  "url": "http://localhost:3000",
  "advancedRules": "thorough"
}

Jede Antwort berichtet das tatsächlich ausgeführte Preset und dessen Ursprung:

{
  "advancedRules": {
    "value": "thorough",
    "source": "tool_arg"
  }
}

Erweiterte Regeln sind in Ihrem Axe DevTools for Web-Abonnement enthalten – dasselbe Abonnement, mit dem Sie den Axe MCP Server erhalten. Sie verlängern einen Scan um etwa 15–20 Sekunden, verbrauchen AI-Credits und sind der einzige Fall, in dem analyze Seitendaten (einen Vollbild-Screenshot plus Seitenstruktur) zur Auswertung an Deque sendet. Siehe Erweiterte Regeln für Presets, Prioritäten, Verschlechterungsmeldungen und Datenschutzdetails.

Wesentliche Vorteile

• Echte Browser-Tests - Testet die tatsächlich gerenderte Seite, nicht nur den Quellcode, um genaue Ergebnisse zu gewährleisten
• Organisationsstandards - Respektiert die Axe-Konfigurationseinstellungen Ihres Teams für konsistente Tests über alle Benutzer hinweg
• Umfassende Abdeckung - Nutzt die branchenführende Axe-Plattform
• Responsives Testen - Testen bei spezifischen Ansichtsfenster-Dimensionen, um zugriffsspezifische Probleme bei Breakpoints zu erfassen
• Gezielte Scans - Begrenzen Sie einen Scan auf eine bestimmte Region, ein iframe oder eine Shadow-Root mit dem selector-Parameter
• Authentifizierte & Interaktive Seiten - Scannen Sie Seiten hinter einer Anmeldung, schließen Sie Cookie-Banner oder warten Sie auf dynamischen Inhalt mit before-Aktionen
• Sitzungs- & Umgebungscookies - Landen Sie bereits authentifiziert oder leiten Sie in eine bestimmte Umgebung, indem Sie vor der Navigation Cookies mit dem cookies-Parameter injizieren
• Visueller Kontext - Geben Sie einen Screenshot der Seite zusammen mit dem Bericht mit dem screenshot-Parameter zurück, auch wenn ein Scan fehlschlägt
• Erweiterte Regeln - Erfassen Sie Probleme, die visuelles oder kontextuelles Denken erfordern, bei einem von Ihrer Organisation kontrollierten Vertrauensniveau
• Intelligent geführte Tests - Führen Sie die IGTs für Tastatur, interaktive Elemente und modale Dialoge auf derselben Seite in demselben Aufruf mit dem igtTools-Parameter aus

Ausgabe

Das Tool liefert eine strukturierte JSON-Antwort mit:

• Alle gefundenen Zugriffsverletzungen
• Schweregrade der Verstöße (kritisch, ernst, moderat, gering)
• Spezifische Elementselektoren und Quellcode
• Regel-IDs und Beschreibungen
• Ein advancedRules-Block, der über das Erweiterte Regeln-Preset berichtet, das ausgeführt wurde, und dessen Herkunft
• Ein messages-Array, das Anmerkungen über den Durchlauf enthält (z. B. eine fehlgeschlagene Bildschirmaufnahme, eine verschlechterte Ausführung der erweiterten Regeln oder den Pfad, zu dem ein Screenshot gespeichert wurde)

Wenn screenshot gesetzt ist, folgt ein Bildinhaltsblock dem Bericht. Wenn igtTools gesetzt ist, werden IGT-Ergebnisse zusammen mit den Axe-Ergebnissen zurückgegeben, gekennzeichnet nach IGT-Namen.