Intelligent geführte Tests

Der analyze-Tool kann Deques Automatisierte Intelligent geführte Tests (IGTs) auf der Seite, die er scannt, im selben Aufruf direkt nach dem Axe-Scan ausführen. Übergeben Sie das optionale igtTools-Array, in dem festgelegt wird, welche IGTs ausgeführt werden sollen:

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"]
}

Geben Sie Ihrem KI-Agenten Eingaben in natürlicher Sprache — der Agent übersetzt Ihre Absicht in den Toolaufruf:

Scan http://localhost:3000 for accessibility issues and run the keyboard IGT on it

Jedes angeforderte IGT läuft in Folge nach dem Axe-Scan, in der Reihenfolge, in der Sie sie auflisten, gegen dieselbe Seite, im selben Browser, bei derselben Viewport-Breite. Alles, was die Seite vorbereitet, wird einmal ausgeführt und gilt für den Scan und jedes IGT: before-Aktionen, Cookie-Injektion und die Viewport-Parameter.

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

Antwortstruktur

Das Setzen von igtTools ändert die Struktur von data. Ohne sie ist data das Axe-Issue-Array. Mit ihr hat data zwei Schlüssel auf derselben Ebene, axe und igt, mit einem igt-Eintrag pro angefordertes IGT:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "axe": [],
    "igt": {
      "keyboard": {
        "status": "complete",
        "issues": [],
        "igtElements": [],
        "terminatedReason": "keyboard-trap"
      },
      "modal": {
        "status": "complete",
        "issues": [],
        "igtElements": []
      }
    }
  }
}

• status — "complete" oder "error". Prüfen Sie dies, bevor Sie etwas anderes lesen: issues und igtElements sind nur bei "complete" vorhanden, und error nur bei "error". Phasenweise Auswahl fügt drei weitere Status für das Interaktive Elemente IGT hinzu.
• issues — die Barrierefreiheitsprobleme, die das IGT gefunden hat. Die Anzahl der Probleme entspricht der Länge dieses Arrays.
• igtElements — jedes-Element, das das IGT verarbeitet hat, nicht nur die mit Problemen. Einträge mit analysisFailed: true konnten von der KI nicht analysiert werden und sollten manuell überprüft werden. Jeder Eintrag ist nur auf identifizierende Felder gekürzt: vnodeId, selector, tagName, role, accessibleName, states und analysisFailed, von denen jeder nur dann vorhanden ist, wenn das Element ihn besitzt.
• terminatedReason — vorhanden nur, wenn der Lauf endete, bevor jeder Schritt abgeschlossen war, sodass die Ergebnisse möglicherweise unvollständig sind. Es ist kein Fehler. Siehe Abbruchgründe.

Abbruchgründe

Das Interaktive Elemente IGT hat keine eigenen Abbruchgründe. Eine Seite ohne interaktive Elemente gibt ein "complete" Ergebnis mit leeren Arrays zurück.

Fehler sind isoliert

An IGT that fails does nicht fail the call and never affects the Axe results or the other IGTs. The failure is reported as that IGT's own status: "error" with a message. The Axe results and every other IGT's results come back normally. This includes when your organization's machine learning setting is disabled, in which case each IGT's entry explains that machine learning is required.

Kreditauslastung

IGTs sind KI-gestützt und Teil des AI-Kreditmanagementsystem. Jeder Durchlauf verbraucht KI-Kredite aus dem monatlichen Kontingent Ihrer Organisation; der Axe-Scan selbst tut dies nicht. Fordern Sie IGTs bewusst an, anstatt sie zu jedem Scan hinzuzufügen. Für das Interactive Elements IGT, Abgrenzung oder Elemente auswählen reduziert die Anzahl der analysierten Elemente und somit die verbrauchten Kredite.

Interaktive Elemente IGT

Das Interactive Elements IGT findet die Schaltflächen, Links und benutzerdefinierten Steuerelemente auf der Seite und nutzt KI, um den zugänglichen Namen, die Rolle und den Zustand jedes einzelnen zu überprüfen. Standardmäßig analysiert es jedes interaktives Element, das es in einem einzigen Aufruf findet:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"]
}

Analyze http://localhost:3000 and run the interactive elements guided test

Jedes analysierte Element verbraucht KI-Kredite, sodass auf einer großen Seite – einem Datenraster, einem langen Navigationsmenü, einer Produktliste – der Standarddurchlauf viel verbrauchen kann. Zwei Optionen begrenzen, was analysiert wird.

Abgrenzung mit includeSelectors

Übergeben Sie includeSelectors, ein Array von CSS-Selektoren, um nur die Elemente zu analysieren, die übereinstimmen. Elemente außerhalb der Selektoren werden nicht analysiert:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"],
  "includeSelectors": ["#main", "nav.primary"]
}

Analyze http://localhost:3000 and run the interactive elements guided test,
but only on the elements inside #main and nav.primary

includeSelectors unterscheidet sich von analyze's selector. selector begrenzt, welchen Teil der Seite der Axe-Scan abdeckt, während includeSelectors begrenzt, welche Elemente der Interaktive Elemente IGT analysiert. Sie können entweder einen oder beide verwenden. includeSelectors erfordert "interactive-elements" in igtTools.

Auswahl der zu testenden Elemente

Wenn Sie im Voraus nicht wissen, welche Elemente wichtig sind, verwenden Sie Phasenweise Auswahl. Es teilt den Test in zwei Tool-Aufrufe auf, mit einer Pause dazwischen, damit Sie auswählen können, was analysiert wird:

1. Erster Aufruf – Elemente finden. Der Agent ruft analyze mit interactive: true auf. Der Axe-Scan läuft wie gewohnt, und das IGT findet die interaktiven Elemente der Seite, führt jedoch keine KI-Analyse nicht darauf aus. Der Lauf pausiert und gibt die Liste der gefundenen Elemente sowie ein sessionID zurück.
2. Sie wählen aus. Der Agent zeigt Ihnen die Liste – die Rolle, den zugänglichen Namen und den Zustand jedes Elements, wo möglich nach Komponente oder Rolle gruppiert – und Sie sagen ihm, welche getestet werden sollen.
3. Zweiter Aufruf – analysieren. Der Agent ruft analyze erneut mit dem sessionID und den von Ihnen gewählten selectedIDs auf. Der pausierte Lauf wird in derselben Browsersitzung fortgesetzt, ohne die Seite erneut zu laden oder Elemente erneut zu finden, und gibt ein normales "complete"-Ergebnis nur für die ausgewählten Elemente zurück.

Eine Eingabeaufforderung, die danach fragt:

Analyze http://localhost:3000 and run the interactive elements guided test.
Show me the interactive elements it finds first and let me choose which
ones to test.

Der erste Aufruf:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"],
  "interactive": true
}

gibt die Axe-Ergebnisse und die Kandidaten zurück:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "axe": [],
    "igt": {
      "interactive-elements": {
        "status": "needs_selection",
        "sessionID": "3f9c…",
        "candidates": [
          { "vnodeId": 12, "role": "button", "name": "Add to cart" },
          { "vnodeId": 31, "role": "link", "name": "Checkout" }
        ],
        "componentGroups": { "intelligent": [], "role": [] }
      }
    }
  }
}

Der zweite Aufruf benennt die gewählten Kandidaten nach vnodeId:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"],
  "sessionID": "3f9c…",
  "selectedIDs": [12]
}

Beachten Sie Folgendes bei der phased selection:

• Es führt nur das Interactive Elements IGT aus. igtTools muss bei beiden Aufrufen genau ["interactive-elements"] sein. Um auch die Keyboard- oder Modal-IGTs auszuführen, führen Sie diese in einem separaten Aufruf durch.
• Der zweite Aufruf lässt data.axe aus. Die Axe-Ergebnisse kamen beim ersten Aufruf zurück. Beim zweiten Aufruf werden alle Setup-Parameter (viewportWidth, viewportHeight, cookies, before, selector, advancedRules, screenshot, chromePath) ignoriert, da die pausierte Browsersitzung unverändert wiederverwendet wird. url ist weiterhin erforderlich.
• includeSelectors gilt weiterhin. Übergeben Sie es beim ersten Aufruf, um zu begrenzen, welche Elemente in der Liste erscheinen.
• selectedIDs muss aus der Liste stammen. Wenn eine ID nicht bei den Kandidaten war, gibt der Aufruf status: "invalid_selection" mit den unbekannten IDs in unknownIDs zurück. Der Lauf bleibt pausiert, sodass der Agent es mit gültigen IDs erneut versuchen kann.
• Pausierte Läufe verfallen. Ein Lauf, der nicht innerhalb von 3 Minuten fortgesetzt wird, wird geschlossen und gibt status: "session_expired" zurück. Maximal 3 pausierte Läufe können gleichzeitig offen sein. Beide Limits sind mit SELECTION_SESSION_TTL_MS und MAX_SELECTION_SESSIONS konfigurierbar. Nach einem Ablauf beginnen Sie mit einem neuen interactive: true-Aufruf von vorne.

Modales Dialogfeld IGT

Der Modal Dialog IGT überprüft einen einzelnen modalen Dialog auf der Seite. Es wird überprüft, dass der Tastaturfokus im modalen Dialog bleibt, solange er geöffnet ist, und dass der Dialog über die korrekten Semantiken verfügt (aria-modal und die Rolle des modal-Containers). Wenn der Test das Element hat, das den modalen Dialog öffnet, wird auch überprüft, dass der modale Dialog kann geschlossen werden und dass der Fokus kehrt an einen sinnvollen Ort zurück danach.

Der Test muss wissen, welcher modale Dialog geprüft werden soll. Es gibt drei Möglichkeiten, dies anzugeben:

Verwenden Sie modalTriggerSelector, wann immer der modale Dialog einen Auslöser hat — es ist der einzige Modus, der alles prüft. Der Test klickt selbst auf den Auslöser:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "modalTriggerSelector": "#open-dialog"
}

Analyze http://localhost:3000 and run the modal guided test on the dialog
opened by #open-dialog

Verwenden Sie modalSelector, wenn es keinen Auslöser zum Klicken gibt, wie z. B. einen modalen Dialog, der beim Laden der Seite geöffnet wird. Wenn der modale Dialog nur nach einer Interaktion erscheint, verwenden Sie before, um ihn zuerst zu öffnen:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "modalSelector": "#newsletter-dialog"
}

Ohne Selektor überprüft der Test jeden offenen modalen Dialog, sobald die before-Schritte abgeschlossen sind. Verwenden Sie dies für modale Dialoge, die kein einzelnes Element öffnet, wie solche, die nach einer Tastensequenz oder einem Sitzungstimeout erscheinen:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "before": [
    { "action": "click", "selector": "#settings" },
    { "action": "click", "selector": "#delete-account" }
  ]
}

Beide Selektoren akzeptieren einen CSS-String für ein Element im oberen Frame oder ein Array von Selektoren, um ein Element in einem iframe zu erreichen (zum Beispiel ["iframe#app", "#open-dialog"]), im selben Format wie selector.

Bereitstellung eines Ersatz-Selektors für modalen Dialog

Wenn Sie sowohl den Auslöser als auch das modale Element kennen, übergeben Sie beide. Der Test beginnt trotzdem mit dem Auslöser und überprüft dennoch alles. Der modalSelector wird nur verwendet, wenn der Test den modalen Dialog nach Klicken auf den Auslöser nicht identifizieren kann — normalerweise, weil der modale Dialog nicht standardmäßiges Markup verwendet:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "modalTriggerSelector": "#open-dialog",
  "modalSelector": "#custom-dialog"
}

Das Ergebnis sagt nicht aus, ob der Ersatz verwendet wurde. Ein Durchlauf, der ihn benötigte, hat ein Element geprüft, das der Test nicht als modalen Dialog erkennen konnte, deshalb betrachten Sie eine leere issues-Liste aus einem Durchlauf mit beiden Selektoren als schwächere Evidenz als eine aus einem Durchlauf mit nur einem Auslöser.

Öffnen Sie den modalen Dialog nicht selbst

Wenn Sie modalTriggerSelector übergeben, klickt der Test auf den Auslöser, um den modalen Dialog zu öffnen. Wenn der modale Dialog bereits geöffnet ist, schließt dieser Klick ihn normalerweise wieder. Also:

• Klicken Sie nicht auf den Auslöser in before. Ein before-Klick auf denselben Selektor wie modalTriggerSelector wird mit einem Fehler abgelehnt. Verwenden Sie before, um den Seitenzustand zu erreichen, in dem der Auslöser sich befindet, wie z. B. eine Anmeldung oder das Aufrufen einer bestimmten Ansicht.
• Übergeben Sie keinen Auslöser für einen bereits geöffneten modalen Dialog, entweder beim Laden der Seite oder von einem before-Schritt. Verwenden Sie stattdessen ausschließlich modalSelector.

modalTriggerSelector und modalSelector erfordern jeweils "modal" in igtTools.

Alles in einem Aufruf ausführen

Jeder IGT hat seine eigenen Optionen, sodass ein analyze-Aufruf den Axe-Scan, Erweiterte Regeln und jeden IGT auf derselben Seite ausführen kann. Die Seite wird einmal geladen und vorbereitet, und jedes Ergebnis wird unter seinem eigenen Schlüssel zurückgegeben.

Analyze http://localhost:3000 for accessibility issues with thorough
advanced rules. Also run the keyboard, interactive elements, and modal
guided tests (test the modal triggered by button#open-dialog).

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

{
  "url": "http://localhost:3000",
  "advancedRules": "thorough",
  "igtTools": ["keyboard", "interactive-elements", "modal"],
  "modalTriggerSelector": "button#open-dialog"
}

und erhält die Axe-Ergebnisse (einschließlich der Ergebnisse der Erweiterten Regeln) unter data.axe und einen Eintrag pro IGT unter data.igt:

{
  "pageUrl": "http://localhost:3000",
  "advancedRules": { "value": "thorough", "source": "tool_arg" },
  "data": {
    "axe": [],
    "igt": {
      "keyboard": { "status": "complete", "issues": [], "igtElements": [] },
      "interactive-elements": {
        "status": "complete",
        "issues": [],
        "igtElements": []
      },
      "modal": { "status": "complete", "issues": [], "igtElements": [] }
    }
  }
}

Die IGTs laufen nacheinander, in der Reihenfolge, die in igtTools aufgeführt ist, und jedes berichtet separat — eine Tastaturfalle oder ein nicht auffindbarer modaler Dialog stoppt die anderen nicht. Dies funktioniert auch mit jeder anderen analyze-Option: before-Schritte und cookies für eine Seite hinter einem Login, viewportWidth für einen mobilen Breakpoint, selector um den Axe-Scan einzuschränken, und screenshot.

Das igt-Werkzeug

Das igt-Werkzeug führt Deques Automatisierte Intelligent Guided Tests gegen eine Webseite als eigenständigen Aufruf aus. Alles, was es tut, macht analyze jetzt im selben Aufruf wie der Barrierefreiheits-Scan — siehe den Rest dieser Seite für Nutzung und Kreditverbrauch, die für beide gleich sind.

Das Ergebnisobjekt pro Test ist auch für beide gleich — status, issues, igtElements und ein optionales terminatedReason, wie in Antwortstruktur beschrieben. Nur der Umschlag unterscheidet sich: igt gibt seine Ergebnisse direkt unter data zurück, nach Testnamen geordnet (data.keyboard), während analyze sie unter data.igt neben data.axe verschachtelt.