Tests guidés intelligents

L'outil analyze peut exécuter les Tests guidés intelligents automatisés (IGT) de Deque sur la page qu'il analyse, dans le même appel, immédiatement après le scan Axe. Passez le tableau optionnel igtTools indiquant quels IGT exécuter :

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

Invitez votre agent AI en langage naturel — l'agent traduit votre intention en appel de l'outil :

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

Chaque IGT demandé s'exécute séquentiellement après le scan Axe, dans l'ordre que vous les listez, sur la même page, dans le même navigateur, à la même largeur d'affichage. Tout ce qui prépare la page s'exécute une fois et s'applique au scan et à chaque IGT : actions before, injection de cookies, et le paramètres d'affichage.

{
  "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" }
  ]
}

Forme de la réponse

Définir igtTools modifie la forme de data. Sans cela, data est le tableau des problèmes Axe. Avec cela, data a deux clés au même niveau, axe et igt, avec une entrée igt par IGT demandé :

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

• status — "complete" ou "error". Vérifiez cela avant de lire quoi que ce soit d'autre : issues et igtElements sont présents uniquement sur "complete", et error seulement sur "error". Sélection par étapes ajoute trois autres statuts pour l'IGT des éléments interactifs.
• issues — les problèmes d'accessibilité que l'IGT a trouvés. Le nombre de problèmes est la longueur de ce tableau.
• igtElements — l'élément chaque que l'IGT a traité, pas seulement ceux avec des problèmes. Les entrées avec analysisFailed: true n'ont pas pu être analysées par l'IA et devraient être examinées manuellement. Chaque entrée est réduite aux seuls champs d'identification : vnodeId, selector, tagName, role, accessibleName, states, et analysisFailed, présents uniquement lorsque l'élément le porte.
• terminatedReason — présent seulement lorsque l'exécution s'est terminée avant que chaque étape ne soit terminée, de sorte que les résultats peuvent être partiels. Ce n'est pas une erreur. Voir Raisons de résiliation.

Raisons de résiliation

L'IGT des éléments interactifs n'a pas ses propres raisons de résiliation. Une page sans éléments interactifs renvoie un résultat "complete" avec des tableaux vides.

Les échecs sont isolés

An IGT that fails does pas 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.

Utilisation des crédits

Les IGT sont alimentés par l'IA et font partie du Système de gestion des crédits IA. Chaque exécution consomme des crédits IA de l'allocation mensuelle de votre organisation ; le scan Axe lui-même ne le fait pas. Demandez des IGT délibérément plutôt que de les ajouter à chaque scan. Pour l'IGT des éléments interactifs, le ciblage ou le choisir des éléments réduit le nombre d'éléments analysés, et donc les crédits utilisés.

IGT des éléments interactifs

L'IGT des éléments interactifs trouve les boutons, les liens et les contrôles personnalisés sur la page et utilise l'IA pour vérifier le nom accessible, le rôle et l'état de chacun. Par défaut, il analyse chaque élément interactif qu'il trouve en un seul appel :

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

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

Chaque élément analysé consomme crédits IA, donc sur une grande page — une grille de données, un long menu de navigation, une liste de produits — l'exécution par défaut peut en utiliser beaucoup. Deux options limitent ce qui est analysé.

Ciblage avec includeSelectors

Passez includeSelectors, un tableau de sélecteurs CSS, pour analyser uniquement les éléments qui correspondent. Les éléments hors des sélecteurs ne sont pas analysés :

{
  "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 est différent du analyze de selector. selector limite la partie de la page que Scan Axe couvre, tandis que includeSelectors limite les éléments que IGT des éléments interactifs analyse. Vous pouvez utiliser l'un, l'autre, ou les deux. includeSelectors nécessite "interactive-elements" dans igtTools.

Choisir quels éléments tester

Lorsque vous ne savez pas à l'avance quels éléments importent, utilisez sélection progressive. Cela divise le test en deux appels d'outils, avec une pause entre les deux pour que vous puissiez choisir ce qui est analysé :

1. Premier appel — trouver des éléments. L'agent appelle analyze avec interactive: true. Le scan Axe s'exécute normalement, et l'IGT trouve les éléments interactifs de la page mais exécute aucune analyse IA sur eux. L'exécution s'interrompt et renvoie la liste des éléments qu'elle a trouvés, ainsi qu'un sessionID.
2. Vous choisissez. L'agent vous montre la liste — le rôle de chaque élément, son nom accessible et son état, groupés par composant ou rôle lorsque cela est possible — et vous lui dites lesquels tester.
3. Deuxième appel — analyser. L'agent appelle analyze à nouveau avec le sessionID et le selectedIDs que vous avez choisis. L'exécution en pause continue dans la même session de navigateur, sans recharger la page ni retrouver les éléments, et retourne un résultat "complete" normal uniquement pour les éléments sélectionnés.

Une invite qui le demande :

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.

Le premier appel :

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

renvoie les résultats Axe et les candidats :

{
  "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": [] }
      }
    }
  }
}

Le deuxième appel nomme les candidats choisis par vnodeId :

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

Gardez à l'esprit les éléments suivants lorsque vous utilisez la sélection progressive :

• Elle exécute uniquement l'IGT Éléments interactifs. igtTools doit être exactement ["interactive-elements"] sur les deux appels. Pour exécuter également les IGT Clavier ou Modal, exécutez-les dans un appel distinct.
• Le deuxième appel omet data.axe. Les résultats Axe sont revenus lors du premier appel. Lors du deuxième appel, tous les paramètres de configuration (viewportWidth, viewportHeight, cookies, before, selector, advancedRules, screenshot, chromePath) sont ignorés, car la session de navigateur en pause est réutilisée tel quel. url est toujours requis.
• includeSelectors s'applique toujours. Passez-le lors du premier appel pour limiter les éléments qui apparaissent dans la liste.
• selectedIDs doit provenir de la liste. Si un identifiant ne figurait pas parmi les candidats, l'appel renvoie status: "invalid_selection" avec les identifiants inconnus dans unknownIDs. L'exécution reste en pause, afin que l'agent puisse réessayer avec des identifiants valides.
• Les exécutions en pause expirent. Une exécution qui n'est pas continuée dans les 3 minutes est fermée et renvoie status: "session_expired". Au maximum, 3 exécutions en pause peuvent être ouvertes en même temps. Les deux limites sont configurables avec SELECTION_SESSION_TTL_MS et MAX_SELECTION_SESSIONS. Après une expiration, recommencez avec un nouvel appel interactive: true.

IGT de dialogue modal

Le test de la boîte de dialogue modale IGT vérifie une seule boîte de dialogue modale sur la page. Il vérifie que le focus clavier reste à l'intérieur de la modale lorsqu'elle est ouverte et que la modale dispose des bonnes sémantiques de dialogue (aria-modal et le rôle du conteneur modale). Lorsque le test dispose de l'élément qui ouvre la modale, il vérifie également que la modale peut être fermé et que le focus revient à un endroit logique ensuite.

Le test doit savoir quelle modale vérifier. Il y a trois façons de le lui indiquer :

Utilisez modalTriggerSelector chaque fois que la modale a un déclencheur — c'est le seul mode qui vérifie tout. Le test clique lui-même sur le déclencheur :

{
  "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

Utilisez modalSelector lorsqu'il n'y a pas de déclencheur sur lequel cliquer, comme une modale qui s'ouvre lorsque la page se charge. Si la modale n'apparaît qu'après une interaction, utilisez before pour l'ouvrir d'abord :

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

Sans sélecteur, le test vérifie la modale ouverte une fois les étapes before terminées. Utilisez cela pour des modales qu'aucun élément unique n'ouvre, comme celle qui apparaît après une séquence de frappes au clavier ou un délai d'inactivité :

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

Les deux sélecteurs acceptent une chaîne CSS pour un élément dans le cadre supérieur, ou un tableau de sélecteurs pour atteindre un élément à l'intérieur d'un iframe (par exemple, ["iframe#app", "#open-dialog"]), au même format que selector.

Fournir un sélecteur de repli pour la modale

Si vous connaissez à la fois le déclencheur et l'élément modale, passez les deux. Le test démarre toujours à partir du déclencheur et vérifie tout. Le modalSelector n'est utilisé que si le test ne peut pas identifier la modale après avoir cliqué sur le déclencheur — généralement parce que la modale utilise un balisage non standard :

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

Le résultat ne dit pas si le repli a été utilisé. Une exécution qui en a eu besoin a vérifié un élément que le test ne pouvait pas reconnaître comme une modale, donc traitez une liste vide issues d'une exécution avec les deux sélecteurs comme preuve plus faible qu'une exécution uniquement par déclencheur.

Ne pas ouvrir la modale vous-même

Lorsque vous passez modalTriggerSelector, le test clique sur le déclencheur pour ouvrir la modale. Si la modale est déjà ouverte, ce clic la referme généralement. Donc :

• Ne cliquez pas sur le déclencheur dans before. Un clic before sur le même sélecteur que modalTriggerSelector est rejeté avec une erreur. Utilisez before pour atteindre l'état de la page où vit le déclencheur, comme se connecter ou accéder à une vue particulière.
• Ne pas passer un déclencheur pour une modale déjà ouverte, soit au chargement de la page, soit à partir d'une étape before. Utilisez modalSelector seul à la place.

modalTriggerSelector et modalSelector nécessitent chacun "modal" dans igtTools.

Tout exécuter en un appel

Chaque IGT a ses propres options, donc un seul appel analyze peut exécuter l'analyse Axe, Règles avancées, et chaque IGT sur la même page. La page est chargée et préparée une fois, et chaque résultat revient sous sa propre clé.

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).

L'agent résout l'invite et appelle l'outil analyze avec une charge utile similaire à :

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

et reçoit les résultats Axe (y compris les découvertes de Règles avancées) sous data.axe et une entrée par IGT sous 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": [] }
    }
  }
}

Les IGT s'exécutent l'un après l'autre, dans l'ordre listé dans igtTools, et chacun fait un rapport séparément — un piège à clavier ou une modale introuvable n'arrête pas les autres. Cela fonctionne également avec toute autre option analyze : étapes before et cookies pour une page derrière une connexion, viewportWidth pour un point de rupture mobile, selector pour délimiter l'analyse Axe, et screenshot.

L'outil igt

L'outil igt exécute les Tests guidés intelligents automatisés de Deque sur une page web comme un appel autonome. Tout ce qu'il fait, analyze le fait maintenant dans le même appel que l'analyse d'accessibilité — consultez le reste de cette page pour l'utilisation et la consommation de crédit, qui sont les mêmes pour les deux.

L'objet de résultat par test est également le même pour les deux — status, issues, igtElements, et un terminatedReason facultatif, comme décrit dans Forme de la réponse. Seul l'enveloppe diffère : igt retourne ses résultats directement sous data, indexés par nom de test (data.keyboard), tandis que analyze les imbrique sous data.igt avec data.axe.