Testes Guiados Inteligentes

A ferramenta analyze pode executar os Testes Guiados Inteligentes Automatizados (IGTs) da Deque na página que escaneia, na mesma chamada, logo após a verificação Axe. Passe a matriz opcional igtTools nomeando quais IGTs executar:

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

Instrua seu agente de IA em linguagem natural — o agente traduz sua intenção para a chamada da ferramenta:

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

Cada IGT solicitado é executado em sequência após a verificação Axe, na ordem em que você os lista, na mesma página, no mesmo navegador, com a mesma largura de viewport. Qualquer coisa que prepare a página é executada uma vez e aplica-se à verificação e a cada IGT: ações before, injeção de cookies, e o parâmetros de 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" }
  ]
}

Formato da resposta

Definir igtTools altera o formato de data. Sem isso, data é o array de problemas do Axe. Com isso, data tem duas chaves no mesmo nível, axe e igt, com uma entrada igt por IGT solicitado:

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

• status — "complete" ou "error". Verifique antes de ler qualquer outra coisa: issues e igtElements estão presentes apenas em "complete", e error apenas em "error". Seleção faseada adiciona três status adicionais para o IGT de Elementos Interativos.
• issues — os problemas de acessibilidade que o IGT encontrou. A contagem de problemas é o tamanho deste array.
• igtElements — elemento cada que o IGT processou, não apenas aqueles com problemas. Entradas com analysisFailed: true não puderam ser analisadas por IA e devem ser revisadas manualmente. Cada entrada é reduzida a apenas campos identificadores: vnodeId, selector, tagName, role, accessibleName, states, e analysisFailed, cada um presente apenas quando o elemento o possui.
• terminatedReason — presente somente quando a execução terminou antes que cada etapa fosse concluída, portanto, os resultados podem ser parciais. Não é um erro. Veja Razões de término.

Razões de término

O IGT de Elementos Interativos não tem razões de término próprias. Uma página sem elementos interativos retorna um resultado "complete" com arrays vazios.

Falhas são isoladas

An IGT that fails does não 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.

Uso de créditos

Os IGTs são alimentados por IA e fazem parte do Sistema de Gerenciamento de Créditos de IA. Cada execução consome créditos de IA da alocação mensal da sua organização; a verificação do Axe em si não. Solicite IGTs intencionalmente em vez de adicioná-los a todas as verificações. Para o IGT de Elementos Interativos, definindo escopo ou escolhendo elementos reduz o número de elementos analisados, e assim os créditos usados.

IGT de Elementos Interativos

O IGT de Elementos Interativos encontra os botões, links e controles personalizados na página e usa IA para verificar cada nome acessível, função e estado. Por padrão, ele analisa cada elemento interativo que encontra em uma única chamada:

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

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

Cada elemento analisado consome créditos de IA, portanto em uma página grande - uma grade de dados, um menu de navegação longo, uma lista de produtos - a execução padrão pode usar muito. Duas opções limitam o que é analisado.

Definindo escopo com includeSelectors

Passe includeSelectors, um array de seletores CSS, para analisar apenas os elementos que correspondem. Elementos fora dos seletores não são analisados:

{
  "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 é diferente do analyze's selector. selector limita qual parte da página o verificação Axe cobre, enquanto includeSelectors limita quais elementos o IGT de Elementos Interativos analisa. Você pode usar um ou ambos. includeSelectors exige "interactive-elements" em igtTools.

Escolhendo quais elementos testar

Quando você não sabe antecipadamente quais elementos são importantes, use seleção em fases. Ele divide o teste em duas chamadas de ferramentas, com uma pausa no meio para você escolher o que será analisado:

1. Primeira chamada — encontrar elementos. O agente chama analyze com interactive: true. A verificação do Axe é executada normalmente, e o IGT encontra os elementos interativos da página mas não executa nenhuma análise de IA neles. A execução pausa e retorna a lista de elementos encontrados, além de um sessionID.
2. Você escolhe. O agente mostra a lista para você — o papel, o nome acessível e o estado de cada elemento, agrupados por componente ou papel quando possível — e você indica quais testar.
3. Segunda chamada — analisar. O agente chama analyze novamente com o sessionID e o selectedIDs que você escolheu. A execução pausada continua na mesma sessão do navegador, sem carregar a página ou encontrar elementos novamente, e retorna um resultado "complete" normal apenas para os elementos selecionados.

Um prompt solicita isso:

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.

A primeira chamada:

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

retorna os resultados do Axe e os 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": [] }
      }
    }
  }
}

A segunda chamada nomeia os candidatos escolhidos por vnodeId:

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

Mantenha o seguinte em mente ao usar a seleção em fases:

• Ele executa apenas o IGT de Elementos Interativos. igtTools deve ser exatamente ["interactive-elements"] em ambas as chamadas. Para executar os IGTs de Teclado ou Modal também, execute-os em uma chamada separada.
• A segunda chamada omite data.axe. Os resultados do Axe foram retornados na primeira chamada. Na segunda chamada, todos os parâmetros de configuração (viewportWidth, viewportHeight, cookies, before, selector, advancedRules, screenshot, chromePath) são ignorados, pois a sessão do navegador pausada é reutilizada como está. url ainda é necessário.
• includeSelectors ainda se aplica. Passe na primeira chamada para limitar quais elementos aparecem na lista.
• selectedIDs deve vir da lista. Se algum ID não estava entre os candidatos, a chamada retorna status: "invalid_selection" com os IDs desconhecidos em unknownIDs. A execução permanece pausada, para que o agente possa tentar novamente com IDs válidos.
• Execuções pausadas expiram. Uma execução que não é continuada dentro de 3 minutos é fechada e retorna status: "session_expired". No máximo 3 execuções pausadas podem estar abertas ao mesmo tempo. Ambos os limites podem ser configurados com SELECTION_SESSION_TTL_MS e MAX_SELECTION_SESSIONS. Após uma expiração, comece novamente com uma nova chamada interactive: true.

IGT de Diálogo Modal

O IGT de Diálogo Modal verifica um único diálogo modal na página. Ele verifica se o foco do teclado permanece dentro do modal enquanto está aberto e se o modal possui a semântica correta do diálogo (aria-modal e o papel do contêiner modal). Quando o teste possui o elemento que abre o modal, ele também verifica se o modal pode ser fechada e se o foco retorna a um lugar sensato depois.

O teste precisa saber qual modal verificar. Existem três maneiras de informá-lo:

Use modalTriggerSelector sempre que o modal tiver um disparador — é o único modo que verifica tudo. O teste clica no próprio disparador:

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

Use modalSelector quando não houver disparador para clicar, como um modal que abre quando a página é carregada. Se o modal só aparecer após alguma interação, use before para abri-lo primeiro:

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

Sem nenhum seletor, o teste verifica qualquer modal que estiver aberto uma vez que as etapas before terminem. Use isso para modais que nenhum elemento único abre, como um que aparece após uma sequência de pressionamentos de tecla ou um tempo limite de sessão:

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

Ambos os seletores aceitam uma string CSS para um elemento no quadro superior, ou uma matriz de seletores para alcançar um elemento dentro de um iframe (por exemplo, ["iframe#app", "#open-dialog"]), no mesmo formato que selector.

Fornecendo um seletor de modal de fallback

Se você conhece tanto o disparador quanto o elemento modal, passe ambos. O teste ainda começa a partir do disparador e ainda verifica tudo. O modalSelector é usado apenas se o teste não puder identificar o modal após clicar no disparador — normalmente porque o modal usa marcação não padrão:

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

O resultado não indica se o fallback foi usado. Uma execução que precisou dele verificou um elemento que o teste não pôde reconhecer como um modal, então trate uma lista vazia issues de uma execução com ambos os seletores como evidência mais fraca do que uma de uma execução apenas com disparador.

Não abra o modal você mesmo

Quando você passa modalTriggerSelector, o teste clica no disparador para abrir o modal. Se o modal já estiver aberto, esse clique geralmente o fecha novamente. Portanto:

• Não clique no disparador em before. Um clique before no mesmo seletor que modalTriggerSelector é rejeitado com um erro. Use before para alcançar o estado da página em que o disparador vive, como fazer login ou acessar uma visualização específica.
• Não passe um disparador para um modal que já está aberto, seja no carregamento da página ou a partir de uma etapa before. Use modalSelector sozinho em vez disso.

modalTriggerSelector e modalSelector exigem cada um "modal" em igtTools.

Executando Tudo em Uma Única Chamada

Cada IGT tem suas próprias opções, então uma chamada analyze pode executar a varredura Axe, Regras Avançadas, e cada IGT na mesma página. A página é carregada e preparada uma vez, e cada resultado é retornado sob sua própria chave.

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

O agente resolve o prompt e chama a ferramenta analyze com um payload semelhante a:

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

e recebe os resultados do Axe (incluindo achados de Regras Avançadas) sob data.axe e uma entrada por IGT sob 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": [] }
    }
  }
}

Os IGTs são executados um após o outro, na ordem listada em igtTools, e cada um relata separadamente — uma armadilha de teclado ou um modal que não pode ser encontrado não interrompe os outros. Isso funciona com todas as outras opções analyze também: passos before e cookies para uma página atrás de um login, viewportWidth para um ponto de ruptura móvel, selector para delimitar a varredura Axe, e screenshot.

A Ferramenta igt

A ferramenta igt executa a Testes Guiados Inteligentes Automatizados da Deque contra uma página da web como uma chamada autônoma. Tudo o que ela faz, analyze agora faz na mesma chamada que a varredura de acessibilidade — veja o restante desta página para uso e consumo de créditos, que são os mesmos para ambos.

O objeto de resultado por teste também é o mesmo para ambos — status, issues, igtElements, e um opcional terminatedReason, conforme descrito em Formato da resposta. Apenas o esquema é diferente: igt retorna seus resultados diretamente sob data, com a chave do nome do teste (data.keyboard), enquanto analyze os aninha sob data.igt juntamente com data.axe.