Falha observada: o teste de cadastro expirou enquanto esperava o e-mail de verificação.
Resposta rápida: não aumente o timeout às cegas. Primeiro confirme se a aplicação acionou o envio; depois separe a aceitação pelo serviço de envio da chegada à caixa de teste, verifique se a mensagem pertence a esta execução e identifique qual limite encerrou o teste. Corrija o ponto comprovado e use uma espera com limite definido.
Na triagem imediata, registre o identificador da execução e confira os logs da aplicação; nesta semana, transforme essa checagem em evidência repetível no fluxo de CI.
Este guia é para quem mantém testes de cadastro, códigos de confirmação ou links de verificação em um produto próprio ou ambiente autorizado. Desenvolvedores podem localizar a fronteira entre a lógica da aplicação e a cadeia de e-mail; profissionais de QA podem distinguir atraso, leitura incorreta e fluxo não acionado. Pessoas que trabalham em projetos independentes podem substituir esperas fixas por verificações controladas.
Timeout no teste E2E de verificação por e-mail não comprova falha de envio
Um timeout significa que uma condição esperada não foi satisfeita dentro do limite configurado. Por si só, não informa se o cadastro foi recebido pela aplicação, se a lógica de e-mail foi chamada, se o serviço de envio aceitou a solicitação ou se a mensagem chegou à caixa consultada pelo teste.
Para declarar a verificação aprovada, o teste precisa reunir evidências ligadas entre si:
- A solicitação de cadastro corresponde à execução em andamento.
- A aplicação acionou o comportamento de envio esperado para aquele ambiente.
- A mensagem pode ser lida na caixa de teste e corresponde àquele cadastro.
- O teste executou o código ou o link de verificação válido.
- O estado da conta corresponde ao resultado previsto pelo produto.
Esses pontos descrevem etapas diferentes. Um registro de envio no log da aplicação não substitui a observação da mensagem na caixa. Da mesma forma, encontrar uma mensagem não demonstra que o teste concluiu a verificação e atualizou o estado da conta.
No SMTP, a aceitação de uma mensagem pelo próximo servidor não significa que ela já foi entregue ao destinatário final. O RFC 5321 descreve as responsabilidades do servidor que aceita a mensagem; por isso, trate a resposta de envio como uma evidência daquela etapa, não como prova de recebimento.
Um teste que falha ao ler o e-mail e um produto que não gera o e-mail são problemas diferentes. Preserve o log e o resultado da caixa antes de repetir a execução.
Quando o teste E2E não encontra o e-mail de cadastro, comece pela aplicação
A primeira verificação é saber se a solicitação chegou à aplicação. Procure o identificador da requisição, o resultado do cadastro e os logs da regra que deveria enviar a mensagem. Se o cadastro foi recusado por validação, duplicidade ou outra condição de negócio, a ausência do e-mail pode ser o comportamento correto.
Se a solicitação foi aceita, verifique o próximo elo: a aplicação executou a lógica de envio? Em arquiteturas com fila, confirme se a tarefa foi criada e se o consumidor configurado para o ambiente de teste a processou. Se o ambiente usa um substituto de e-mail, confira se a configuração ativa corresponde à expectativa do teste. Não conclua que uma fila atrasou sem observar seu estado ou seus logs.
Também confirme se a leitura da caixa começou. Um teste pode ter parado antes de consultar o destinatário por uma falha anterior, como um seletor que não encontrou o botão de cadastro ou uma navegação interrompida. Nesse caso, aumentar o período de espera por e-mail não corrige a causa: o passo de envio talvez nem tenha sido executado.
Uma sequência útil de evidências é:
- Resultado da requisição de cadastro.
- Resultado da regra de negócio que decide enviar ou não.
- Registro da chamada ao serviço de envio ou da criação da tarefa.
- Resultado observado na caixa de teste.
- Resultado da ação de verificação e estado final da conta.
O guia de teste de cadastro e verificação pode ajudar a organizar o fluxo funcional que o teste precisa cobrir. Use-o como apoio para o produto próprio; a evidência da execução ainda deve vir dos logs e da caixa realmente consultada.
Uma resposta de envio bem-sucedida não prova que a caixa de teste recebeu a mensagem
Quando a aplicação registra uma resposta positiva do serviço de envio, confira o que essa resposta realmente representa. Ela pode indicar que uma solicitação foi aceita para processamento, mas não prova, por si só, que o endereço consultado pelo teste recebeu uma mensagem legível. A distinção é importante tanto para serviços de terceiros quanto para fluxos internos com fila.
Compare o destinatário que a aplicação tentou usar com o endereço configurado no teste. Verifique se ambos pertencem ao mesmo ambiente e à mesma execução. Confira também se a caixa consultada é a caixa associada ao cadastro; erros de variável de ambiente, configuração antiga ou endereço reutilizado podem deixar a aplicação e o teste observando destinos diferentes.
Se o endereço estiver correto, procure uma mensagem na caixa e anote o resultado real: encontrada, ausente ou ilegível. Depois verifique os registros disponíveis no lado do envio. Evite substituir essa observação por uma resposta HTTP ou por um log genérico de “enviado”. São sinais úteis, mas não provam a mesma etapa.
O artigo sobre caixa de teste e sandbox de e-mail apresenta a diferença entre observar mensagens recebidas e testar o fluxo em um ambiente controlado. Para decidir qual evidência é necessária, pergunte: o objetivo é verificar que a aplicação acionou o envio ou demonstrar que o e-mail foi recebido e pode ser lido? Um teste de integração e uma validação de recebimento podem exigir observações diferentes.
A caixa contém mensagens, mas o teste lê a errada ou não a encontra
Uma caixa com mensagens antigas, mensagens de outras execuções ou notificações diferentes do cadastro atual pode fazer o teste falhar mesmo quando a mensagem esperada chegou. Isso é comum quando a busca considera apenas o assunto, o destinatário ou uma palavra do corpo, sem distinguir de qual operação veio a mensagem.
Associe a mensagem à execução com um dado verificável. O produto pode, por exemplo, inserir um identificador de teste em um campo que já faça parte do fluxo ou usar um endereço de teste controlado por execução, se a arquitetura permitir. O ponto essencial é validar a associação usando dados observáveis pela aplicação e pelo leitor da caixa, sem depender de uma correspondência genérica.
Em seguida, revise os filtros da leitura: endereço do destinatário, assunto, remetente e conteúdo esperado. Um filtro restrito demais pode excluir uma mensagem válida após uma alteração de modelo; um filtro amplo pode selecionar uma notificação que não corresponde ao cadastro. Se o teste extrai um código ou link, confirme que está usando a mensagem encontrada, e não um valor guardado de uma tentativa anterior.
Para testes paralelos, a associação precisa ser inequívoca. Uma caixa compartilhada sem correlação entre execução e mensagem pode produzir falso positivo ou falso negativo. Trate isso como um problema de identificação e isolamento do dado de teste, não como prova de que o serviço precisa de mais tempo para entregar.
Como confirmar que o e-mail pertence a esta execução?
Use um identificador que apareça tanto no contexto do cadastro quanto nos dados disponíveis para localizar a mensagem. Depois, confira destinatário e conteúdo antes de extrair o código ou abrir o link. Se o identificador não puder ser propagado, reduza a ambiguidade com uma caixa dedicada ao teste e evite consumir mensagens de execuções anteriores. Registre qual mensagem foi selecionada para que uma falha posterior possa ser reproduzida e auditada.
O teste pode expirar antes da leitura por causa de limites diferentes
O timeout do teste, o timeout da asserção e o limite configurado pelo CI não são necessariamente o mesmo relógio. Em Playwright, as asserções têm uma configuração de timeout própria; a documentação informa que o padrão das asserções é 5 segundos. Já a documentação de timeouts do Playwright informa um padrão de 30 segundos para o teste. Esses valores são configurações documentadas, não uma recomendação de espera para qualquer sistema de e-mail. Consulte a documentação de asserções e a documentação de timeouts antes de alterar o projeto.
Identifique qual limite encerrou a execução. A asserção pode ter falhado enquanto o teste ainda tinha tempo; o teste pode ter atingido o limite global durante a espera; ou o CI pode ter encerrado o processo por um limite próprio. O objeto de configuração de testes do Playwright documenta opções que ajudam a localizar e ajustar limites do framework.
O método waitForTimeout na documentação do Playwright é descrito como inadequado para uso rotineiro em testes de produção. Uma pausa fixa pode mascarar uma condição que nunca ocorre e ainda aumentar o tempo de execução em execuções nas quais a condição já estava pronta. Prefira aguardar uma condição observável, com um limite definido e uma mensagem de falha que indique o que não foi encontrado.
No Playwright, expect.poll permite repetir uma verificação até que a condição esperada seja atendida ou que o limite aplicável seja alcançado, conforme a configuração. Isso é diferente de colocar uma pausa arbitrária antes de ler a caixa. A condição deve consultar uma fonte que represente o estado desejado, e o erro final deve ajudar a diferenciar “mensagem ausente” de “mensagem encontrada, mas inválida”.
Se a falha só some quando o timeout cresce, isso ainda não identifica a causa. A mudança pode apenas esconder uma mensagem sem associação, uma leitura que começou tarde ou um caminho de aplicação que não é executado em todas as tentativas.
Lista de triagem para escolher a próxima ação
Antes de alterar o timeout ou repetir o teste, marque o que foi comprovado. Se um item falhar, investigue aquela fronteira em vez de mudar vários parâmetros ao mesmo tempo.
- [ ] O cadastro chegou à aplicação e seu resultado ficou registrado?
- [ ] A regra de negócio deveria enviar e-mail para esse caso?
- [ ] A lógica de envio foi chamada ou a tarefa entrou na fila esperada?
- [ ] O destinatário registrado corresponde ao endereço observado pelo teste?
- [ ] A caixa foi consultada e o resultado da busca ficou registrado?
- [ ] A mensagem encontrada pode ser associada a esta execução, sem confundi-la com mensagens antigas?
- [ ] O teste extraiu o código ou link da mensagem correta?
- [ ] O estado final da conta confirma o resultado esperado?
- [ ] O erro indica se o limite veio da asserção, do teste ou do CI?
- [ ] A repetição proposta verifica uma causa específica, em vez de apenas esperar mais?
A decisão fica mais clara quando cada sinal é associado a uma ação. A tabela abaixo não presume que todo sistema use a mesma infraestrutura; ela indica que evidência procurar em cada fronteira.
| Evidência observada | Interpretação possível | Próxima ação |
|---|---|---|
| Cadastro não aparece no log da aplicação | A solicitação pode não ter chegado ou o teste pode ter parado antes do envio | Verifique a requisição e a etapa anterior à espera |
| Cadastro foi aceito, mas não há chamada de envio | Regra de negócio, configuração de ambiente ou fila pode não ter acionado o envio | Confira a decisão de negócio, a configuração e o processamento da tarefa |
| Há registro de envio, mas a caixa consultada está vazia | A aceitação pelo serviço não comprova recebimento; o endereço ou ambiente também pode divergir | Compare destinatário e ambiente; observe a caixa e os registros do lado de envio |
| Há mensagens, mas nenhuma corresponde ao cadastro atual | Busca ampla, filtro inadequado ou falta de associação entre execução e mensagem | Torne a correlação explícita e revise os critérios de leitura |
| A mensagem correta foi lida, mas a conta não foi verificada | Extração, link, código ou etapa final da aplicação pode estar falhando | Valide o conteúdo usado e confira o estado final da conta |
| O teste falha sempre no mesmo limite | A configuração que encerra a execução pode ser menor que o tempo disponível para a condição | Identifique o limite efetivo antes de ajustar qualquer valor |
Ajuste a espera com base na fronteira comprovada
Uma espera controlada é útil quando o teste consulta repetidamente uma condição observável, para após um limite definido e registra o motivo da falha. Ela não deve ser um substituto para a investigação do envio ou para a associação da mensagem. Se a condição consultada nunca muda porque a aplicação não acionou o envio, uma espera maior apenas adia o diagnóstico.
A distinção prática entre os limites pode ser resumida assim:
| Limite | O que controla | O que revisar |
|---|---|---|
| Timeout da asserção | Quanto a condição associada à asserção pode levar para ser satisfeita | Se a condição é observável e se o limite configurado é adequado ao teste |
| Timeout do teste | Quanto tempo a execução do teste pode usar | Se o teste ficou preso em uma etapa anterior ou se o fluxo excede o limite |
| Limite do CI | Quanto tempo o executor permite ao processo ou à tarefa | Logs do executor, cancelamentos e configuração do pipeline |
As opções e os valores padrão podem mudar conforme a configuração do projeto e a versão usada. Consulte a documentação oficial antes de aplicar qualquer ajuste e mantenha a alteração restrita ao limite que de fato encerrou o teste. Não existe, aqui, um tempo universal de chegada de e-mail: a conclusão deve vir da observação do ambiente real e do comportamento esperado do produto.
Repita o cenário certo e registre evidências que sobrevivam à falha
Depois de identificar a fronteira, corrija uma causa por vez. Se a aplicação não chamou o envio, repita o cenário de cadastro que deveria acionar essa regra. Se o envio foi acionado, mas o destinatário estava errado, corrija a configuração do ambiente. Se a mensagem chegou e foi confundida com outra, corrija a correlação e a consulta. Se a asserção terminou antes de uma condição válida, revise o limite correspondente e a própria condição aguardada.
Em cada repetição, registre o identificador da execução, o resultado do cadastro, a evidência de acionamento do envio, o destinatário, o resultado observado na caixa, a mensagem selecionada e o estado final da conta. Esse conjunto ajuda a comparar uma execução aprovada com uma falha intermitente sem tratar uma repetição bem-sucedida como prova de que o problema desapareceu.
Quando a finalidade é provar que uma mensagem real entrou em uma caixa e pode ser lida, inclua uma etapa de recebimento controlado. Isso é diferente de testar somente a chamada de envio ou substituir o transporte de e-mail por um simulador. Um guia sobre códigos de verificação e estado de cadastro pode ajudar a estruturar essa relação entre mensagem e conta. A verificação em um ambiente de teste demonstra o comportamento observado naquele cenário; não garante a entrega em produção para todos os destinatários.
Para esse tipo de validação, HideRelay pode ser considerado como uma opção de caixa de teste controlada. Antes de incorporá-lo ao fluxo, confira as capacidades atuais do serviço, a forma de acesso ao endereço e as condições de retenção das mensagens; não presuma que esses detalhes sejam iguais em todos os ambientes. Um endereço temporário pode ser conveniente para cadastro de teste, recebimento de código ou conferência de um link no produto próprio, mas não é adequado para contas bancárias, pagamentos, serviços públicos ou qualquer conta importante que exija recuperação e recebimento duradouro.
Envie uma notificação sintética pelo fluxo real de entrega
Defina os valores e horários esperados e envie o e-mail para um endereço temporário de teste. Primeiro, confirme que ele chegou; depois, compare cada detalhe do conteúdo. Não confunda um e-mail de demonstração com o resultado do seu teste.