"Element not found" de novo? Como testar quando seletores e localizadores falham
"Element not found"?Por que seletores e localizadores quebram (ids dinâmicos, shadow DOM, iframes, canvas) e como testar sem nenhum localizador para manter.
"Element not found" significa que seu teste procurou um elemento com um localizador e nada correspondeu a tempo.A solução raramente é um localizador melhor: é um teste que verifica o que o usuário vê.
Todo engenheiro de QA conhece essa manhã: vinte testes vermelhos e nenhum bug real.Um desenvolvedor renomeou uma classe, o time de design moveu um banner, uma atualização do framework mudou os ids.Este artigo explica por que os localizadores quebram, como corrigir o erro quando ele aparece, onde as soluções de sempre param e como testar sem um seletor para manter.
O que significa "element not found"?
Definição
Um erro "element not found" significa que o teste pediu um elemento com um localizador e nada na página correspondeu antes do tempo limite.
- Um localizador, também chamado de seletor, é o endereço que o teste usa para o elemento: um id, um seletor CSS, um XPath, um papel e um nome, um texto.
- O Selenium lança NoSuchElementException, o Playwright encerra a ação com um tempo esgotado, e cada outro framework tem seu próprio nome para isso.
No fim, a mensagem é sempre a mesma: o teste perdeu o elemento, tenha o usuário perdido ou não.
A própria página de solução de problemas do Selenium dá três causas prováveis: você procura no lugar errado, procura na hora errada, ou o localizador mudou desde que você escreveu o código.Só a última é sobre o localizador em si, e é a que cresce a cada versão.
#save-8f3a2c
Uma nova build gera outro id
.btn-primary
Um redesign renomeia a classe
text=Save
A versão francesa diz Enregistrer
//div[3]/form/button[2]
Um banner é adicionado acima do formulário
Na tela
SaveSem mudança para o usuário
Por que seletores e localizadores quebram?
Um localizador é um palpite sobre como o aplicativo é construído.Qualquer coisa que mude a construção sem mudar o que o usuário vê pode quebrá-lo.
| O que mudou | Quais localizadores quebram | O usuário percebeu? |
|---|---|---|
| Ids e nomes de classe gerados | Um id ou uma classe escritos pelo framework, diferentes a cada build ou carregamento de página | Não |
| Um redesign ou uma refatoração | Cadeias CSS e XPaths que seguem a estrutura da página | Muitas vezes não |
| Um teste A/B | Qualquer localizador da variante que seu teste não esperava | Só os usuários dessa variante |
| Uma tradução | Localizadores por texto visível ou nome acessível | Não, se a tradução estiver certa |
| Shadow DOM e iframes | Localizadores que não conseguem entrar no componente ou no frame | Não |
| Uma lista virtualizada | Localizadores de uma linha que só é desenhada quando se rola até ela | Não |
| Um canvas, um jogo ou um app sem árvore de acessibilidade | Todos os localizadores: não há nada dentro para apontar | Não |
Ids dinâmicos e nomes de classe gerados
Muitos frameworks escrevem seus próprios ids e nomes de classe, como save-8f3a2c ou css-1x7hq.Eles são únicos, o que os faz parecer localizadores perfeitos, e mudam na próxima build.Um teste gravado sobre eles passa hoje e falha depois do próximo deploy, numa página que ninguém tocou.
Redesigns, refatorações e testes A/B
Um seletor CSS como .form > div:nth-child(3) button ou um XPath como //div[3]/form/button[2] descreve um caminho pela página.Envolva o formulário num novo contêiner, adicione um banner acima dele ou troque dois campos de lugar, e o caminho leva a outro lugar.Um teste A/B faz o mesmo de propósito: metade dos visitantes recebe uma página para a qual seus localizadores não foram escritos.
A documentação do Playwright diz isso claramente: seletores XPath e CSS podem estar presos à estrutura do DOM, e podem quebrar quando ela muda.
Localização e localizadores por texto
Localizadores por texto, rótulo ou nome acessível sobrevivem a um redesign, por isso são recomendados.Eles não sobrevivem a uma tradução.Um botão encontrado pelo nome Save não é encontrado quando a versão francesa diz Enregistrer, então um produto localizado precisa de um localizador por idioma, ou de um test id.
Shadow DOM e iframes
Um iframe é uma página dentro da página, e um componente web guarda seus elementos internos em uma shadow root.O Selenium só conhece os elementos do documento de nível superior, então é preciso mandar um teste codificado entrar primeiro no frame, senão ele informa que o elemento não existe.Alguns localizadores, como XPath, não conseguem entrar em um componente de jeito nenhum.
Listas e grades virtualizadas
Uma tabela de dez mil linhas é rápida porque não desenha todas.O AG Grid, uma grade de dados muito usada, explica que só desenha o que se vê na tela, mais uma pequena reserva de linhas acima e abaixo.A linha 500 não está na página até alguém rolar até ela, então um localizador não a encontra, enquanto uma pessoa simplesmente rolaria.
Como corrigir um erro "element not found"
No Selenium, no Playwright ou no Cypress, corrigir o erro é trabalho seu, e ele volta a cada versão.No GUI Test Studio não há localizador para corrigir.
| O que deu errado | Em um framework codificado | No GUI Test Studio |
|---|---|---|
| O elemento aparece tarde | Você escreve uma espera pela condição certa | Cada asserção espera sozinha até o seu tempo limite |
| O elemento está em um frame ou em uma shadow root | Você escreve a entrada no frame ou no componente | O elemento é encontrado onde está desenhado na tela |
| Um redesign mudou os ids ou a estrutura | Você reescreve o localizador, muitas vezes em vários testes | Nada para reescrever: outro caminho, ou a imagem dele, o encontra |
| O elemento mudou de propósito | Você edita o código do teste | Um clique no relatório aceita a nova aparência |
Quando um teste do GUI Test Studio para em um elemento, estes cinco passos resolvem a questão, sem programar nada.
- 1
Abra o Relatório de confiança da execução
O relatório abre após cada execução, na primeira falha.Ele mostra a imagem esperada ao lado da tela no momento em que a asserção desistiu, para você ver se o elemento faltava, estava coberto ou estava em outro lugar.
- 2
Verifique onde a execução começou
Um teste começa na tela em que a gravação começou.Se o aplicativo estava em outra página ou tinha outros dados, deixe-o como estava e execute o teste de novo.
- 3
Amplie a área de busca se o elemento foi para longe
Quando nada é encontrado na área de busca de uma asserção, a busca já se amplia sozinha para a tela inteira.Se o elemento agora fica em outro lugar de vez, clique em Ampliar a área de busca no relatório e defina a nova área no GUI Test Studio.
- 4
Aceite uma mudança feita de propósito
Se o elemento está diferente porque o design mudou, clique em Aceitar o obtido como esperado no Relatório de confiança e salve.O teste fica atualizado, sem código para editar.
- 5
Relate o bug se o elemento sumiu de verdade
Se o elemento sumiu, o teste cumpriu seu papel.Clique em Relatório de bug para registrá-lo como PDF ou como issue do Jira, com as imagens anexadas.
CSS, XPath, papel ou test id: todo localizador tem um ponto fraco
As equipes que escrevem testes codificados escolhem um localizador para cada elemento que tocam.Cada tipo falha do seu jeito.
| Localizador | Exemplo | Quebra quando | Sobrevive a |
|---|---|---|---|
| Id ou classe gerados | #save-8f3a2c | A próxima build | Quase nada |
| Seletor CSS | .form button.primary | As classes ou a estrutura mudam | Um texto novo ou uma tradução |
| XPath | //div[3]/form/button[2] | Qualquer coisa é adicionada acima ou ao redor | Uma classe nova |
| Papel e nome acessível | role=button, name=Save | O rótulo muda ou é traduzido | Redesigns e refatorações |
| Test id | data-testid=save-order | Um desenvolvedor o remove ou renomeia | Redesigns, traduções, refatorações |
Cada estratégia desloca o risco em vez de removê-lo.
- Um papel e um nome dependem das palavras, que mudam a cada tradução e a cada ajuste de texto.
- Um test id depende de um hábito: cada desenvolvedor precisa adicioná-lo, mantê-lo e nunca reutilizá-lo, em cada componente, enquanto o produto existir.
- CSS e XPath dependem da estrutura, que é exatamente o que as refatorações mudam.
XPath ou seletor CSS é a pergunta mais feita, e ela importa menos do que parece.CSS é mais curto e mais fácil de ler; XPath consegue subir pela página e buscar texto.Os dois descrevem como a página é construída, então os dois quebram do mesmo jeito.
No GUI Test Studio ninguém escolhe um localizador.Um teste gravado guarda sozinho vários caminhos até cada elemento, como mostram as próximas seções.
A automação de testes com autocorreção resolve localizadores quebrados?
Ferramentas de autocorreção guardam detalhes extras de cada elemento enquanto um teste passa.Quando o localizador principal deixa de corresponder, elas procuram o elemento com esses detalhes e continuam.
A autocorreção é útil, com três limites que vale conhecer.
Ela ainda parte de um localizador, então precisa de um elemento na página para onde se corrigir.
Ela transforma uma mudança em aprovação, então cada correção precisa ser revisada por uma pessoa, senão uma mudança real se esconde atrás dela.
Ela não ajuda onde não há elemento nenhum: um canvas, um jogo, uma tela remota.
Onde todo localizador para: canvas, jogos e apps sem árvore de acessibilidade
Todas as estratégias acima supõem que o aplicativo descreve seus elementos.Muitos não descrevem, e não há localizador para escrever, nem bom nem ruim.
| Aplicativo | O que um localizador consegue alcançar |
|---|---|
| Um canvas, um gráfico, um mapa, uma cena WebGL | Um único elemento que contém uma imagem |
| Um jogo | Uma única janela: o jogo desenha seus próprios menus |
| Flutter na web | Nada até o app ligar sua acessibilidade: o Flutter desenha sua interface num canvas, e a acessibilidade dele é opcional na web |
| Qt, Java Swing, Delphi e outros apps de desktop desenhados sob medida | Pouco ou nada, conforme o modo como cada controle é desenhado |
| Citrix, Área de Trabalho Remota e máquinas virtuais | Uma única janela de pixels no seu computador |
Para apps de desktop Windows, Alternativas ao WinAppDriver para apps sem árvore de acessibilidade mostra quais programas se descrevem e quais não.
Se seu teste só vê o que o aplicativo descreve, um aplicativo que não descreve nada não pode ser testado.O usuário ainda vê cada botão.
Automação de testes sem seletores para manter
O GUI Test Studio, que automatiza testes de ponta a ponta no Windows, segue outro caminho: ninguém escreve nem mantém um seletor.Você grava o teste fazendo o fluxo você mesmo, ou o descreve num prompt, e cada asserção trata do que o usuário vê.
| A asserção | O que ela verifica |
|---|---|
| Asserção visual | Um elemento está na tela e tem a aparência esperada: sua imagem, encontrada e comparada |
| Asserção textual | Um texto está na tela, lido onde deve estar |
| Asserção textual dinâmica | Um valor tem o formato certo, como uma data, um valor monetário ou um número de pedido, qualquer que seja o valor |
| Asserção de layout | Os elementos estão onde devem estar em relação uns aos outros |
Para encontrar cada elemento, o GTS Engine + AI usa dois caminhos.Ele pergunta primeiro ao aplicativo: as informações de acessibilidade que um app Windows dá sobre seus controles, ou os próprios elementos de uma página web.Quando o aplicativo não diz nada, ele encontra o elemento pela visão, na tela.Como o GUI Test Studio encontra elementos na tela explica os dois caminhos em detalhe.
Numa página web: vários caminhos até um elemento
Num teste web, o GUI Test Studio guarda vários caminhos até cada elemento em que age, em ordem: seu test id, seu id, seu papel e nome, seu rótulo, seu texto de exemplo, seu texto e, por último, seu lugar na página.Um id que parece gerado por um framework vai para o fim da lista, depois de tudo o que uma pessoa consegue ler.
Os caminhos até o botão Save, tentados em ordem
- 1Seu test iddata-testid="save"Removido em uma refatoração
- 2Seu papel e nomerole=button · name=SaveEncontrado
- 3Seu textoSaveNão necessário
- 4Seu lugar na páginaform > button:nth-of-type(2)Não necessário
Assim, um test id removido ou uma classe renomeada não param o teste: o próximo caminho ainda encontra o elemento.Os mesmos caminhos alcançam elementos dentro de uma shadow root, e permitem que um teste gerado para um celular abra o menu que ali esconde um link.
É isso que permite que um único teste web gravado rode no Chrome, no Edge, no Firefox e em celulares emulados, como mostram os testes entre navegadores a partir de uma única gravação.
Num app de desktop: primeiro o controle, depois a tela
Num app Windows, uma asserção feita sobre um botão guarda o que o app disse sobre esse botão: seu nome, seu tipo, onde ele estava.A cada execução, o motor pede primeiro esse botão ao app em execução, e procura a imagem dele dentro do retângulo que o app informa.Entre vários botões idênticos, ele pega o mais próximo de onde estava o gravado.
Uma asserção textual pergunta ao app o que o elemento diz antes de ler as palavras na tela, então uma palavra difícil de ler na tela ainda é conferida com o que o app realmente diz.
Em todo o resto: pela visão
Um jogo, um canvas, uma sessão Citrix ou um programa sem árvore de acessibilidade é testado pela visão, sem nada adicionado ao aplicativo.A asserção procura a imagem do elemento na sua área de busca, e uma asserção textual lê as palavras na tela.
Um painel desenha seu gráfico de vendas num canvas, então nenhum localizador alcança uma barra ou uma legenda.Você grava um clique na barra de março e adiciona uma asserção visual da legenda.O clique é mirado pela imagem da barra, e a legenda é verificada como o usuário a vê.
O que acontece quando o elemento se move ou muda
Um teste que não depende de um só localizador ainda precisa lidar com a mudança.Veja o que o GUI Test Studio faz a cada passo.
Perguntar
O aplicativo diz onde está o elemento
Olhar
Ou a imagem dele é encontrada na sua área de busca
Ampliar
Nada ali: a tela inteira
Relatar
Onde foi encontrado, e por quê
Cada passo cobre um tipo diferente de mudança.
- Uma janela que se moveu, um layout que deslizou ou uma lista que rolou: o aplicativo diz onde o elemento está agora, ou a imagem dele é encontrada ali.
- Um elemento que saiu da sua área de busca: quando nada é encontrado ali, a busca se amplia para a tela inteira, e o Relatório de confiança diz que o elemento foi encontrado fora da sua área, com um link para ampliá-la.
- Uma palavra que o reconhecimento de texto lê mal: uma asserção textual pergunta ao aplicativo o que o elemento diz.
- Um elemento web cujo primeiro localizador quebrou: o próximo caminho o encontra, e a execução registra qual caminho mudou.
Os cliques também seguem o elemento: cada clique é mirado pela asserção que vem antes dele, então quando o botão se move, o clique se move junto.Veja as asserções visuais e as asserções textuais para saber como cada asserção é configurada.
O que ainda depende de você
Nenhuma abordagem torna toda mudança gratuita.Estes são os casos em que uma pessoa decide.
| Situação | O que fazer |
|---|---|
| A aparência de um elemento mudou de propósito | A asserção falha com a imagem esperada e a obtida lado a lado.Clique em Aceitar o obtido como esperado no Relatório de confiança e salve. |
| O tamanho da tela ou a escala diferem da gravação | Uma asserção pela visão compara imagens, então rode com o mesmo tamanho de tela e a mesma escala, ou mantenha um perfil de linha de base para cada um. |
| O app não começa onde a gravação começou | Coloque o aplicativo de volta no estado em que a gravação começou: a mesma página, os mesmos dados, as mesmas janelas abertas. |
| Um teste A/B serve outra variante | Fixe a variante no seu ambiente de teste, ou mantenha um perfil de linha de base para cada variante. |
| O elemento realmente desapareceu | Isso é um bug.O teste falha, e o relatório mostra o que era esperado e onde. |
Aceitar uma nova aparência mostra a atualização em um clique, e testes instáveis e falsos positivos explica como uma asserção distingue ruído inofensivo de uma mudança real.
Para os bugs visuais que uma asserção baseada em localizadores deixa passar sem ver, leia os bugs visuais que seus testes automatizados não pegam.
Pontos principais
- 1"Element not found" costuma ser um problema do teste, não um bug: o localizador, o momento ou o contexto estão errados com mais frequência do que o aplicativo.
- 2Localizadores quebram por motivos comuns: ids gerados, redesigns, testes A/B, traduções, shadow DOM, iframes e listas virtualizadas.
- 3Cada estratégia desloca o risco: CSS e XPath dependem da estrutura, papéis e nomes das palavras, test ids de um hábito do time, a autocorreção de uma revisão.
- 4Alguns apps não dão nada a um localizador: canvas, jogos, sessões Citrix e apps sem árvore de acessibilidade só podem ser testados pela visão.
- 5O GUI Test Studio não tem seletores nem localizadores para manter: ele pergunta primeiro ao aplicativo, encontra o elemento pela visão quando o aplicativo não diz, e verifica o que o usuário vê.
Perguntas
O que significa "element not found" na automação de testes?
Significa que o teste pediu um elemento com um localizador, como um id, um seletor CSS ou um XPath, e nada na página correspondeu a tempo.No Selenium aparece como NoSuchElementException, no Playwright como tempo esgotado.O elemento pode estar ausente, mas o mais comum é que o localizador, o momento ou o contexto estejam errados.
Por que meu teste encontra o elemento localmente, mas não na CI?
Normalmente porque a execução é diferente, não o código.Um agente de build mais lento mostra o elemento mais tarde que seu notebook, uma tela menor o esconde atrás de um menu, outros dados de teste mudam o texto dele, ou um teste A/B serve outra variante.Olhe a captura de tela ou o vídeo da execução que falhou antes de mudar o localizador.
XPath ou seletor CSS: qual é melhor?
Nenhum é seguro sozinho.Os dois descrevem como a página é construída, então os dois quebram quando a estrutura muda, como avisa a documentação do Playwright.Um papel com um nome ou um test id duram mais, mas cada um continua sendo escrito e mantido à mão.No GUI Test Studio ninguém escreve nenhum dos dois: o teste guarda os próprios caminhos até cada elemento.
Como lidar com ids dinâmicos no Selenium ou no Playwright?
Não construa um teste em cima deles: um id que muda a cada build ou a cada carregamento da página não consegue achar o mesmo elemento duas vezes.Em um teste codificado, isso significa escrever e manter outro localizador à mão.No GUI Test Studio não há nada para escrever: um teste web coloca um id que parece gerado no fim da sua lista de caminhos até o elemento, depois de tudo que uma pessoa consegue ler.
A automação de testes com autocorreção funciona?
Ajuda quando um atributo muda e o elemento continua lá.Não consegue recuperar um elemento que sumiu de verdade, e continua partindo de um localizador que alguém escreveu e precisa manter.Revise cada correção, ou ela pode esconder uma mudança real.
Como testar um app que não tem árvore de acessibilidade?
Pela visão, na tela.Jogos, canvas, gráficos, sessões Citrix e de Área de Trabalho Remota e muitos programas desenhados sob medida não expõem nada que um localizador alcance.O GUI Test Studio encontra os elementos deles pela imagem e verifica o texto lido na tela, sem mudar nada no aplicativo.
Dá para automatizar testes de ponta a ponta sem seletores nem localizadores?
Sim.No GUI Test Studio você grava um teste ou o descreve num prompt, e não há seletores nem localizadores para manter.Cada asserção é uma imagem, um texto, o formato de um valor ou uma disposição na tela, e o GTS Engine + AI encontra cada elemento perguntando primeiro ao aplicativo, e pela visão quando ele não diz.
O que acontece quando um botão muda de propósito?
A asserção falha e mostra a imagem esperada e a obtida lado a lado.Se a mudança é desejada, clique em Aceitar o obtido como esperado no Relatório de confiança e salve: o teste fica atualizado, sem código para editar.
Selenium, Playwright, Cypress, AG Grid, Flutter, Qt, Java, Delphi, Citrix, Chrome, Edge, Firefox e Windows são marcas de seus respectivos proprietários.
Continue lendo
Todos os artigos
Confiabilidade dos testes
Testes instáveis: causas, custos e como evitar falsos positivos
12 min de leitura
Testes visuais
Teste de capturas de tela pixel perfect: por que ele falha e o que pega os bugs visuais reais
12 min de leitura
Automação de testes
Teste manual vs. teste automatizado: por que o teste manual fica aquém nos testes de ponta a ponta
15 min de leitura