Um agente de IA que opera interfaces clica com base na posição do elemento na tela. Quando uma dica flutuante (tooltip), um painel suspenso, um toast de notificação ou um overlay de carregamento cobre esse elemento no exato instante da ação, o clique acerta o alvo errado: o formulário recebe o texto no campo ao lado, o botão de enviar vira o de cancelar, ou nada acontece porque o overlay engoliu o evento. O elemento continua existindo no HTML e continua legível para a árvore de acessibilidade, o que engana a checagem mais simples. O problema não é o elemento, é o que está por cima dele naquele milissegundo.
A defesa prática tem quatro partes: conferir o que realmente está no ponto central antes de clicar, checar o estado dos overlays, tratar a espera como parte da ação (com timeouts curtos e novas tentativas) e confirmar o efeito depois de cada interação. Nenhuma delas exige adivinhar a intenção do site. Todas são verificáveis.
Resumo rápido
- Existir no HTML e estar “visível” na árvore de acessibilidade não significa estar alcançável no clique: um overlay pode capturar o evento.
- Antes de agir, confira qual elemento está no ponto central da tela; se não for o alvo, não clique.
- Espere o overlay sumir em vez de forçar o clique por baixo dele: forçar é a origem mais comum de ações no lugar errado.
- Prefira navegação por URL e chamadas de API quando existirem; menos tela significa menos chance de erro.
- Confirme sempre o efeito depois da ação (o dado mudou de verdade?) e trate isso como parte do teste do agente.
- Cada uma dessas verificações é testável de forma automática, com dados de tabela que têm lacunas, antes de subir para produção.
Por que a inspeção do DOM não basta
O modelo mental mais comum de quem programa um agente é: “se o elemento está no DOM e aparece na árvore de acessibilidade, ele pode ser clicado”. Esse raciocínio erra em duas frentes ao mesmo tempo.
Primeiro, a árvore de acessibilidade descreve o que um leitor de tela anuncia, não o que o ponteiro atinge. Um tooltip ou um painel flutuante posicionado por CSS por cima do botão continua anunciado como elemento separado, e o botão por baixo continua presente, com nome e papel corretos. Do ponto de vista de acessibilidade, tudo está “ali”. Do ponto de vista do clique, o que vale é qual elemento está naquele pixel, e nesse pixel está o overlay.
Segundo, “visível” costuma ser definido de forma permissiva. A documentação do Playwright define um elemento como visível quando ele tem caixa delimitadora não vazia e não tem visibility:hidden no estilo computado. Por essa definição, um elemento com opacity:0 conta como visível, e um elemento coberto por outro também. Ou seja, visível no papel não quer dizer alcançável na prática. A própria ferramenta separa esses conceitos: além de visível, o elemento precisa estar estável, habilitado e recebendo eventos (não obstruído por outros elementos).
O que muda tudo é entender que a checagem relevante não é “esse elemento existe e aparece?”, e sim “se eu clicar agora, quem recebe o clique?”. Essa segunda pergunta só se responde olhando a geometria da tela no momento da ação.
O que “receber eventos” quer dizer na prática
Ferramentas de automação modernas já embutem essa ideia. Na checagem de ação do Playwright, um elemento “recebe eventos” quando é o alvo do evento de ponteiro no ponto da ação. O exemplo é direto: ao clicar no ponto (10;10), a ferramenta verifica se algum outro elemento, normalmente um overlay, vai capturar o clique naquele ponto.
Isso é diferente de estar visível ou de estar habilitado. Um botão pode estar visível, habilitado e estável, e ainda assim falhar essa checagem, porque há algo por cima. Quando a checagem falha, a ação espera até o tempo limite; se o overlay não sair, a ação falha em vez de clicar no lugar errado.
| Checagem | O que pergunta | Pega o caso do tooltip/overlay? |
|---|---|---|
| Existe no DOM | O elemento está na página | Não. O elemento encoberto continua no DOM. |
| Visível | Tem caixa e não está com visibility:hidden |
Não. Coberto por outro elemento ainda conta como visível. |
| Habilitado | Não está desabilitado | Não. Overlay não altera o estado do botão por baixo. |
| Estável | A caixa não muda entre quadros, não está animando | Parcial. Ajuda se o overlay ainda está surgindo ou saindo. |
| Recebe eventos | É o alvo do ponteiro no ponto da ação | Sim. É a checagem que detecta o elemento encoberto. |
A lição para quem escreve o agente: a checagem “recebe eventos” é a que importa, e ela só funciona quando está ligada. Vários fluxos de automação e alguns modos de clique a desligam para “destravar” a execução. Esse atalho troca um erro visível (ação que falha e você percebe) por um erro silencioso (ação que acontece no elemento errado). Limitar o que cada agente pode fazer reduz o estrago de um clique assim; veja o guia de permissões de agentes de IA.
Como detectar o elemento encoberto antes de agir
Dá para reproduzir a checagem “recebe eventos” por conta própria, mesmo fora de uma ferramenta que já a faça, usando APIs do próprio navegador. A ideia é pegar o retângulo do alvo, calcular um ponto dentro dele e perguntar ao navegador quais elementos estão naquele ponto.
Conferir o ponto central
O método document.elementFromPoint(x, y) devolve o elemento mais acima que está naquele ponto da tela. Se o resultado não for o alvo (nem um descendente do alvo), algo está por cima e o clique iria para o lugar errado. O ponto mais simples de usar é o centro do retângulo do alvo, obtido com getBoundingClientRect().
Listar os elementos sobrepostos
O método document.elementsFromPoint(x, y) devolve a lista de todos os elementos que cobrem aquele ponto, do mais acima para o mais abaixo. Isso é mais útil que a versão de um só elemento, porque mostra a pilha inteira: você vê não só que há um overlay, mas que tipo de camada é (um painel de notificação, um modal, um cabeçalho fixo). Com a lista em mãos, dá para decidir se espera, se fecha o painel ou se contorna pelo caminho alternativo.
Checar o estado do overlay
Antes de esperar, identifique o overlay. Painéis flutuantes costumam ter papel de acessibilidade próprio, como role="tooltip" ou um contêiner de diálogo, e é possível consultar a árvore de acessibilidade para saber se estão abertos. Também vale observar propriedades de estilo que indicam bloqueio, como um fundo modal cobrindo a página, ou um elemento cujo estilo computado mostra pointer-events capturando o clique. A MDN documenta a propriedade CSS pointer-events, útil para saber se uma camada está interceptando o ponteiro. Ferramentas de automação aplicam um truque parecido por dentro: uma camada invisível que captura cliques serve justamente para detectar se alguém tentou clicar por baixo de um overlay.
Como mitigar: esperar, desviar, confirmar
1. Espere o overlay sumir, não clique por baixo
A reação instintiva ao ver a ação travada é forçar o clique (o modo force que ignora checagens). É o caminho mais direto para clicar no elemento errado, porque você está dizendo ao agente “não confira se o alvo recebe o clique, apenas clique”. Em vez disso, espere a condição desaparecer: o painel de notificação some sozinho depois de alguns segundos, o spinner de carregamento termina, o modal é fechado. Trate a espera como parte da ação e use um tempo limite curto: se o overlay não sair, é melhor falhar de forma visível e registrar o motivo do que agir no escuro.
2. Prefira navegação por URL
Muita inconstância de overlay existe porque o agente está navegando por cliques em menus e abas, onde painéis suspensos aparecem o tempo todo. Quando o endereço tem URL própria, ir direto para ela remove a tela inteira do problema. O agente deixa de depender de um menu que abre, cobre e fecha, e passa a depender só do carregamento da página.
3. Aja por API quando existir
Se o sistema expõe uma API para a operação, usar a API elimina overlay, tooltip e toast de uma vez, porque não há tela. A regra de ouro é: tudo que puder ser feito por API, faça por API; reserve a automação de interface para o que só existe na tela. Isso reduz a superfície de erro e deixa o agente mais rápido e mais previsível.
4. Confirme o efeito depois de cada ação
Um clique que “parece” ter dado certo não prova nada. Depois de cada ação com efeito, releia o estado real: o valor gravado na tela ou na API, a linha nova na listagem, a mensagem de confirmação. Essa checagem pega o caso em que o clique foi engolido por um overlay e nada mudou, ou em que a mudança foi para o campo errado. É a mesma disciplina de conferir respostas que se aplica a qualquer fluxo com IA.
Exemplo: notas em um sistema de gestão web
Imagine uma pequena distribuidora de material de construção em Contagem (MG). O financeiro usa um sistema de gestão web para lançar notas de compra. A pessoa responsável monta um agente que abre a tela de lançamento, preenche fornecedor, valor e a aba de destino, e clica em “Salvar”. O sistema, a cada salvamento, exibe um toast no canto inferior da tela com a mensagem “Salvo com sucesso”.
O que acontece em uso real: o toast aparece mais ou menos na altura dos botões de rodapé do formulário. No primeiro lançamento, o clique em “Salvar” grava tudo certo. No segundo, o clique acontece no instante em que o toast ainda está na tela e, em vez de salvar, o agente clica em “Cancelar”, que fica logo ao lado e acaba encoberto pelo próprio toast. O agente relata sucesso, porque o clique “aconteceu”, mas o lançamento se perde. O erro só aparece horas depois, quando o financeiro procura uma nota que nunca foi gravada.
A correção não muda o sistema, muda o agente. Ele passa a conferir, antes de cada clique no rodapé, qual elemento está no centro do botão alvo; se encontrar o toast por cima, espera o toast sumir (tempo limite curto) e só então clica. Depois de clicar, em vez de assumir sucesso, lê a listagem de notas e confirma que a linha nova apareceu. Quando o sistema oferece uma API de lançamento, o agente passa a usar a API para os lançamentos de rotina e reserva a interface para casos excepcionais. O resultado observado pela equipe é que os lançamentos param de se perder de forma silenciosa; os números de volume e tempo dependem do sistema de cada cliente e não são objeto deste exemplo.
Como testar isso no agente
Elemento encoberto é um caso de teste, não um detalhe de implementação. Para o desenho geral da bateria, vale seguir um roteiro de como testar um agente de IA, separando o que é comportamento de navegação do que é resultado de negócio. Vale montar uma bateria específica:
- Teste com overlay forçado: durante um fluxo automatizado, sobreponha um painel sobre o botão principal e verifique que o agente espera ou falha, em vez de clicar no alvo errado.
- Teste com toast atrasado: simule uma notificação que surge pouco antes do clique e confira se o agente detectou a cobertura pelo ponto central.
- Teste com
forceligado e desligado: rode o mesmo fluxo com a checagem de “recebe eventos” ligada e desligada, e compare quantos cliques acertam o alvo. Isso mostra na prática o custo do atalho. - Teste de confirmação de efeito: faça o clique “funcionar” sem que o dado mude e confirme que o agente percebe a divergência em vez de declarar sucesso.
- Teste de tempo limite: mantenha o overlay aberto além do tempo limite e verifique que o agente falha com mensagem clara, não que prossegue.
Para o desenho geral da bateria de testes, vale seguir um roteiro de como testar um agente de IA separando o que é comportamento de navegação do que é resultado de negócio.
Erros comuns
- Confundir visível com clicável. Achar que estar na árvore de acessibilidade garante receber o clique. São checagens distintas.
- Forçar o clique para destravar. Desligar a checagem de receber eventos troca uma falha visível por uma ação no lugar errado.
- Ignorar o toast que ainda está saindo. Um overlay em animação de saída já liberou o pixel, mas às vezes ainda o captura por um quadro. Espere o estado, não o olho.
- Assumir sucesso sem reler o estado. Clicar não é o mesmo que gravar. Sem confirmação, o agente relata êxito em ações que não aconteceram.
- Navegar por menus onde existe URL direta. Cada painel suspenso que abre é uma chance de encobertar o próximo alvo.
- Usar automação de tela onde existe API. A interface é a superfície onde overlay existe; a API não tem esses problemas.
- Timeouts longos sem motivo. Esperar minutos por um overlay que trava a ação atrasa o diagnóstico. Prefira prazos curtos e falha clara.
Perguntas frequentes
Se o elemento está na árvore de acessibilidade, não está clicável?
Não necessariamente. A árvore de acessibilidade descreve o que é anunciado por leitores de tela, não a geometria de eventos de ponteiro. Um elemento coberto pode estar corretamente presente na árvore e, ao mesmo tempo, não receber o clique porque outro elemento ocupa o pixel.
Qual é a diferença entre estar visível e receber eventos?
Visível é ter caixa delimitadora não vazia e não estar com visibility:hidden, segundo a definição das ferramentas de automação. Receber eventos é ser o alvo do ponteiro no ponto da ação. Um elemento pode ser visível e não receber eventos ao mesmo tempo.
Por que não simplesmente usar o clique forçado e seguir?
Porque o clique forçado desliga exatamente a checagem que detectaria o overlay. Você ganha velocidade e perde a garantia de acertar o alvo. É aceitável só quando você tem certeza de que a cobertura é inofensiva, o que raramente é o caso.
Como sei qual elemento está por cima sem adivinhação?
Com APIs do navegador: document.elementFromPoint(x, y) mostra o elemento mais acima no ponto, e document.elementsFromPoint(x, y) devolve a pilha inteira de elementos que cobrem o ponto. O centro do retângulo do alvo é um bom ponto para essa conferência.
Toda ação precisa de confirmação de efeito?
Ações com efeito duradouro, sim (gravações, envios, transições de estado). Para ações idempotentes e sem consequência, uma confirmação leve basta. O critério é o custo de um erro silencioso.
Isso só vale para agente que usa navegador?
Vale para qualquer automação que aja por coordenadas ou por alvo de evento, incluindo automação de interface em geral. O princípio não muda: confirmar quem recebe a ação antes de agir e conferir o efeito depois.
Leia também
Para aprofundar o tema deste artigo, veja tambem:
