Pruebas Guiadas Inteligentes

La herramienta analyze puede ejecutar las Pruebas Guiadas Inteligentes Automatizadas (IGT) de Deque en la página que escanea, en la misma llamada, justo después del escaneo Axe. Pase la matriz opcional igtTools nombrando qué IGT ejecutar:

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

Instruya a su agente de IA en lenguaje natural: el agente traduce su intención en la llamada de herramienta:

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

Cada IGT solicitado se ejecuta en secuencia después del escaneo Axe, en el orden que los enumere, contra la misma página, en el mismo navegador, con el mismo ancho de vista. Cualquier cosa que prepare la página se ejecuta una vez y se aplica al escaneo y a cada IGT: acciones before, inyección de cookies, y el parámetros del viewport.

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

Forma de respuesta

Configurar igtTools cambia la forma de data. Sin ello, data es la matriz de problemas Axe. Con ello, data tiene dos claves al mismo nivel, axe y igt, con una entrada igt por cada IGT solicitado:

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

• status — "complete" o "error". Verifíquelo antes de leer cualquier otra cosa: issues y igtElements están presentes solo en "complete", y error solo en "error". Selección por fases agrega tres estados más para el IGT de Elementos Interactivos.
• issues — los problemas de accesibilidad que encontró el IGT. El conteo de problemas es la longitud de esta matriz.
• igtElements — cada elemento que el IGT procesó, no solo los que tienen problemas. Las entradas con analysisFailed: true no pudieron ser analizadas por IA y deben revisarse manualmente. Cada entrada se reduce solo a campos de identificación: vnodeId, selector, tagName, role, accessibleName, states, y analysisFailed, cada uno presente solo cuando el elemento lo contiene.
• terminatedReason — presente solo cuando la ejecución finalizó antes de que todos los pasos concluyeran, por lo que los resultados pueden ser parciales. No es un error. Consulte Razones de terminación.

Razones de terminación

El IGT de Elementos Interactivos no tiene razones de terminación propias. Una página sin elementos interactivos devuelve un resultado "complete" con matrices vacías.

Las fallas están aisladas

Un IGT que falla no no la llamada y nunca afecta los resultados de Axe ni los otros IGT. La falla se reporta como un status: "error" del propio IGT con un mensaje. Los resultados de Axe y de cada otro IGT regresan normalmente. Esto incluye cuando la configuración de aprendizaje automático de su organización está desactivada, en cuyo caso cada entrada del IGT explica que el aprendizaje automático es necesario.

Uso de créditos

Los IGT están potenciados por IA y forman parte del Sistema de Gestión de Créditos de IA. Cada ejecución consume créditos de IA de la asignación mensual de su organización; el escaneo de Axe en sí no lo hace. Solicite IGT de manera deliberada en lugar de agregarlos a cada escaneo. Para el IGT de Elementos Interactivos, alcance o elección de elementos reduce la cantidad de elementos analizados y, por lo tanto, los créditos utilizados.

IGT de Elementos Interactivos

The Interactive Elements IGT finds the buttons, links, and custom controls on the page and uses AI to check each one's accessible name, role, and state. By default it analyzes cada interactive element it finds in a single call:

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

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

Cada elemento analizado consume créditos de IA, por lo que en una página grande —una cuadrícula de datos, un menú de navegación largo, una lista de productos— la ejecución predeterminada puede usar muchos créditos. Hay dos opciones que limitan lo que se analiza.

Definir el alcance con includeSelectors

Pase includeSelectors, un arreglo de selectores CSS, para analizar solo los elementos que coincidan. Los elementos fuera de los selectores no se analizan:

{
  "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 es diferente del selector de analyze. selector limita qué parte de la página cubre el escaneo de Axe, mientras que includeSelectors limita qué elementos analiza el IGT de Elementos Interactivos. Puede usar uno o ambos. includeSelectors requiere "interactive-elements" en igtTools.

Elegir qué elementos probar

Cuando no sabe de antemano qué elementos son importantes, use selección por fases. Divide la prueba en dos llamadas de herramientas, con una pausa entre ellas para que pueda elegir qué se analiza:

1. Primera llamada: encontrar elementos. El agente llama a analyze con interactive: true. El escaneo de Axe se ejecuta como de costumbre, y el IGT encuentra los elementos interactivos de la página pero no realiza sin análisis de IA en ellos. La ejecución se pausa y devuelve la lista de elementos que encontró, más un sessionID.
2. Usted elige. El agente le muestra la lista: el rol de cada elemento, su nombre accesible y estado, agrupados por componente o rol cuando sea posible, y usted le indica cuáles prueba.
3. Segunda llamada: analizar. El agente llama a analyze nuevamente con los sessionID y los selectedIDs que eligió. La ejecución pausada continúa en la misma sesión del navegador, sin cargar la página ni encontrar elementos de nuevo, y devuelve un resultado normal de "complete" solo para los elementos seleccionados.

Una solicitud que lo pide:

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.

La primera llamada:

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

devuelve los resultados de Axe y los candidatos:

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

La segunda llamada nombra a los candidatos elegidos por vnodeId:

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

Tenga en cuenta lo siguiente al usar la selección por fases:

• Solo corre el IGT de Elementos Interactivos. igtTools debe ser exactamente ["interactive-elements"] en ambas llamadas. Para ejecutar los IGT de Teclado o Modal también, ejecútelos en una llamada separada.
• La segunda llamada omite data.axe. Los resultados de Axe fueron devueltos en la primera llamada. En la segunda llamada, todos los parámetros de configuración (viewportWidth, viewportHeight, cookies, before, selector, advancedRules, screenshot, chromePath) se ignoran, porque la sesión del navegador pausada se reutiliza tal cual. url sigue siendo necesario.
• includeSelectors sigue aplicando. Páselo en la primera llamada para limitar qué elementos aparecen en la lista.
• selectedIDs debe provenir de la lista. Si algún ID no estaba en los candidatos, la llamada devuelve status: "invalid_selection" con los IDs desconocidos en unknownIDs. La ejecución permanece pausada, para que el agente pueda intentar nuevamente con IDs válidos.
• Las ejecuciones pausadas expiran. Una ejecución que no se continúa dentro de 3 minutos se cierra y devuelve status: "session_expired". A lo sumo 3 ejecuciones pausadas pueden estar abiertas a la vez. Ambos límites son configurables con SELECTION_SESSION_TTL_MS y MAX_SELECTION_SESSIONS. Después de una expiración, comience de nuevo con una nueva llamada de interactive: true.

IGT de Diálogo Modal

El IGT de Diálogo Modal verifica un único diálogo modal en la página. Comprueba que el enfoque del teclado permanezca dentro del modal mientras esté abierto y que el modal tenga la semántica correcta de diálogo (aria-modal y el rol del contenedor modal). Cuando la prueba tiene el elemento que abre el modal, también verifica que el modal puede cerrarse y que el enfoque regresa a un lugar sensato posteriormente.

La prueba necesita saber qué modal verificar. Hay tres maneras de indicarlo:

Usa modalTriggerSelector siempre que el modal tenga un disparador — es el único modo que verifica todo. La prueba hace clic en el disparador en sí:

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

Usa modalSelector cuando no haya un disparador en el cual hacer clic, como un modal que esté abierto cuando se carga la página. Si el modal solo aparece después de alguna interacción, utiliza before para abrirlo primero:

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

Sin ninguno de los selectores, la prueba verifica cualquier modal que esté abierto una vez que los pasos de before terminen. Usa esto para modales que no abre un solo elemento, como uno que aparece tras una secuencia de pulsaciones de teclas o un cierre de sesión por tiempo de espera:

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

Ambos selectores aceptan una cadena CSS para un elemento en el marco superior, o un arreglo de selectores para alcanzar un elemento dentro de un iframe (por ejemplo, ["iframe#app", "#open-dialog"]), el mismo formato que selector.

Proporcionar un selector modal de respaldo

Si conoces ambos, el disparador y el elemento modal, pásalos ambos. La prueba aún comienza desde el disparador y aún verifica todo. El modalSelector se utiliza solo si la prueba no puede identificar el modal después de hacer clic en el disparador, típicamente porque el modal utiliza un marcado no estándar:

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

El resultado no dice si se utilizó el respaldo. Una ejecución que lo necesitó verificó un elemento que la prueba no pudo reconocer como un modal, así que trata una lista issues vacía de una ejecución con ambos selectores como evidencia más débil que una de solo con disparador.

No abras el modal tú mismo

Cuando pasas modalTriggerSelector, la prueba hace clic en el disparador para abrir el modal. Si el modal ya está abierto, ese clic usualmente lo vuelve a cerrar. Entonces:

• No hagas clic en el disparador en before. Un clic before en el mismo selector que modalTriggerSelector es rechazado con un error. Usa before para alcanzar el estado de la página en el que el disparador se encuentra, como iniciar sesión o ir a una vista particular.
• No pases un disparador para un modal que ya está abierto, ya sea en la carga de la página o desde un paso before. Usa modalSelector por sí solo en su lugar.

modalTriggerSelector y modalSelector cada uno requiere "modal" en igtTools.

Ejecutando todo en una sola llamada

Cada IGT tiene sus propias opciones, por lo que una sola llamada analyze puede ejecutar el escaneo de Axe, Reglas avanzadas, y cada IGT en la misma página. La página se carga y prepara una vez, y cada resultado se devuelve bajo su propia clave.

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

El agente resuelve el indicador y llama a la herramienta analyze con una carga parecida a:

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

y recibe los resultados de Axe (incluyendo hallazgos de Reglas Avanzadas) bajo data.axe y una entrada por IGT bajo 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": [] }
    }
  }
}

Los IGT se ejecutan uno tras otro, en el orden listado en igtTools, y cada uno reporta por separado: un bloqueo de teclado o un modal que no se puede encontrar no detiene a los demás. Esto funciona también con cada otra analyze opción: pasos before y cookies para una página detrás de un inicio de sesión, viewportWidth para un punto de interrupción móvil, selector para delimitar el escaneo de Axe, y screenshot.

La herramienta igt

La herramienta igt ejecuta el Pruebas Guiadas Inteligentes Automatizadas de Deque contra una página web como una llamada independiente. Todo lo que hace, analyze ahora lo hace en la misma llamada que el escaneo de accesibilidad — consulta el resto de esta página para el uso y el consumo de créditos, que son iguales para ambos.

El objeto de resultado por prueba también es el mismo para ambos — status, issues, igtElements, y un opcional terminatedReason, como se describe en Forma de respuesta. Solo el envoltorio difiere: igt devuelve sus resultados directamente bajo data, indexados por nombre de prueba (data.keyboard), mientras que analyze los anida bajo data.igt junto a data.axe.