2026: Como testar e-mails agendados no Playwright? Verifique o disparo e o recebimento real

O limite do relógio do navegador

O Playwright Clock permite controlar comportamentos relacionados a tempo na página: por exemplo, código que usa a data e a hora do navegador, timers executados pelo navegador ou uma interface que muda depois de um intervalo. Isso é útil para verificar como a aplicação se comporta quando a hora exibida ou o tempo percebido pela página muda.

Esse controle não se estende automaticamente ao processo que roda fora do navegador. Se o envio depende de uma fila, de um worker, de um cron ou de outro agendador, mudar o relógio da página não avança o relógio desse serviço nem faz a tarefa pendente ser executada. O teste pode mostrar que a interface apresenta a data esperada, enquanto a tarefa do servidor continua sem rodar.

Também não basta aumentar o timeout para “esperar o e-mail”. O timeout do Playwright limita a espera do teste, mas não acelera uma fila nem garante que o servidor tenha processado o agendamento. Por isso, primeiro defina qual resultado a execução precisa provar:

• Regra de negócio: a condição para enviar a notificação foi calculada corretamente?
• Execução: o serviço agendador ou worker processou a tarefa?
• Conteúdo: destinatário, assunto e corpo correspondem à regra?
• Recebimento: a mensagem apareceu em uma caixa acessível ao teste?

Cada resposta pede uma observação diferente. Uma asserção na página não substitui um registro de execução; um registro de envio não substitui a confirmação de recebimento.

Marcos de validação por cenário

Atraso após uma condição

Para validar uma notificação que deve sair depois de uma condição — como uma etapa de fluxo concluída ou um período sem atividade — associe a preparação do teste, a tarefa e a mensagem à mesma execução. Não use apenas a hora mostrada na página como referência do disparo.

Um fluxo reproduzível pode seguir estes marcos:

1. Prepare um registro exclusivo para o teste. Crie o dado de negócio com um identificador não sensível, como um ID de execução gerado para essa rodada. Evite usar nome, e-mail pessoal ou detalhes reais de cliente.
2. Registre a condição e o horário de referência. Armazene o instante definido pela regra do produto e o estado que deve permitir o envio. Se a lógica usa uma data calculada pelo navegador, teste esse comportamento separadamente com o relógio da página.
3. Ative a execução do lado do servidor pelo mecanismo previsto no ambiente. Em um ambiente de teste, isso pode significar iniciar o worker, processar a fila ou chamar uma rotina de teste autorizada. O procedimento precisa corresponder à arquitetura do produto; o Clock não substitui essa etapa.
4. Confirme uma evidência de processamento. Consulte o registro da tarefa, o estado da fila ou um evento de execução que permita relacionar o processamento à execução de teste.
5. Verifique o resultado da regra. Confirme que a tarefa selecionou o registro esperado e respeitou as condições de elegibilidade. Uma tarefa iniciada pode terminar sem enviar nada se a regra não for satisfeita.
6. Confira o envio e, depois, a caixa de entrada. Registre o resultado observado em cada etapa, sem tratar “tarefa concluída” como sinônimo de “mensagem recebida”.

A documentação do Clock explica o controle de tempo na página. Para validar a interação com uma API do próprio produto, o Playwright também documenta testes de API. Use essa abordagem para observar ou preparar o comportamento do sistema apenas de acordo com os recursos e as permissões do ambiente de teste.

Resumo programado e período coberto

Um resumo pode ser enviado no horário certo e ainda assim estar incorreto. O problema pode estar no intervalo de dados incluído, no fuso horário usado para definir o período ou no destinatário calculado. Por isso, não limite a validação a conferir se uma data mudou na tela.

Defina a regra do resumo em termos verificáveis: qual período de atividade ele deve cobrir, quais registros entram, qual endereço recebe a mensagem e como a aplicação trata limites de calendário. Em seguida, prepare dados de teste antes, dentro e depois do intervalo esperado. O teste deve conseguir distinguir esses registros no conteúdo ou nos metadados observáveis, sem recorrer a dados pessoais reais.

Fusos horários, horário de verão e viradas de dia dependem da regra implementada pelo produto. Escolha casos reproduzíveis para a zona horária configurada e valide os limites que realmente importam à aplicação. Um resultado correto em uma zona não demonstra, por si só, que todas as demais zonas seguem a mesma regra.

Para uma aceitação clara, compare três elementos: o intervalo que a regra deveria selecionar, os registros efetivamente incluídos no resumo e o destinatário resolvido no momento do processamento. Se algum deles divergir, a falha fica localizada: cálculo do período, seleção dos dados ou endereçamento.

Repetição, retentativas e duplicidade

Uma tarefa pode ser executada mais de uma vez por uma retentativa, por uma repetição do agendador ou por uma nova execução do teste. O resultado esperado depende da regra do produto: alguns fluxos podem permitir nova mensagem; outros devem impedir duplicatas para o mesmo evento.

Antes de escrever a asserção, defina a unidade de idempotência. Pode ser o evento de negócio, a janela do resumo ou a combinação entre destinatário e notificação. Depois, provoque a repetição em um ambiente controlado e confira se a aplicação se comporta conforme essa regra. Não presuma que uma retentativa do runner seja equivalente a uma retentativa do worker: são camadas distintas. A documentação do Playwright sobre retentativas explica como o runner pode repetir testes; isso não define como a fila da aplicação lida com tarefas repetidas.

Associe a execução a um identificador que não contenha informação pessoal e registre-o junto aos eventos relevantes. Esse vínculo ajuda a separar mensagens da execução atual de resíduos de rodadas anteriores. Em paralelo, use as asserções com espera automática do Playwright para condições de interface que podem se estabilizar com o tempo; elas não substituem a verificação do estado da fila ou da caixa de entrada.

Recebimento real em endereço controlado

Para confirmar que a mensagem entrou em uma caixa de teste, use um endereço autorizado para testar o próprio produto e que possa ser consultado durante a execução. Verifique a mensagem no destino, não apenas o resultado retornado pelo processo de envio. Registre um vínculo entre a mensagem e a execução, por meio de um identificador não sensível no assunto, no conteúdo ou em metadados disponíveis.

Separe os resultados em evidências distintas:

• Agendamento: a aplicação criou ou disponibilizou a tarefa conforme a regra.
• Processamento: o worker ou mecanismo responsável executou a tarefa.
• Envio: a aplicação registrou uma tentativa ou um resultado de envio.
• Recebimento: o teste encontrou e leu a mensagem na caixa controlada.

Essa separação evita duas conclusões equivocadas: que uma resposta positiva do componente de envio garante recebimento, ou que uma falha de leitura prova que a tarefa nunca executou. Cada ponto ajuda a direcionar a investigação para a camada correta.

Uma caixa de teste também tem limites. Ela demonstra o comportamento observado naquele endereço e naquele ambiente; não garante a entrega em caixas de outros provedores, nem representa automaticamente a configuração de produção. Para manter os dados de QA afastados de informações pessoais, consulte também as orientações de privacidade no uso do serviço e aplique a mesma cautela aos dados preparados pela própria equipe.

Comparação das evidências

Roteiro de aceitação por marcos

Uma sequência simples torna o resultado mais fácil de auditar. Antes de executar, confira se o ambiente é de teste ou foi explicitamente autorizado. Em seguida, documente a regra do produto e a evidência que cada etapa deve produzir.

Marco de preparação: crie um registro de negócio isolado, selecione um destino de teste e gere um identificador de execução sem dados pessoais. Se o teste usa endereço temporário, valide antes se ele pode ser consultado no fluxo e no momento necessários. A comparação de opções de caixa de entrada pode ajudar a avaliar o tipo de destino conforme a necessidade de leitura e retenção; confirme as características atuais do serviço antes de depender delas.

Marco de regra: teste a condição e a hora de referência. Use o Clock apenas para o comportamento que acontece na página. Quando a decisão de envio pertence ao servidor, verifique a regra no componente responsável ou por meio de um fluxo de teste autorizado.

Marco de execução: acione o processamento do agendador ou da fila conforme a implementação do produto. Guarde a evidência que associa a tarefa ao identificador da execução. Se não houver registro, não conclua que o relógio do navegador resolveu a ausência de execução.

Marco de conteúdo: compare o período do resumo, o destinatário e os elementos essenciais do corpo com os dados preparados. Para notificações, confirme também que a mensagem se refere ao evento correto, não apenas que chegou uma mensagem qualquer.

Marco de recebimento: consulte a caixa controlada, localize a mensagem associada à execução e registre se foi possível abri-la e verificar o conteúdo. Se ela não aparecer, investigue primeiro a camada sem evidência: processamento, envio ou recebimento.

Marco de repetição: execute o caso de novo de acordo com a política de retentativa e confira a regra de duplicidade. Preserve os registros necessários para diferenciar uma repetição legítima de uma mensagem residual de outra rodada.

Registro do resultado por cenário

Ao concluir, escreva o resultado por camada, por exemplo: “regra validada; tarefa processada; conteúdo conferido; mensagem encontrada no destino controlado”. Se uma etapa falhar, registre-a como pendente ou reprovada sem promover a evidência de outra camada a substituta. Esse formato é mais útil para depuração do que um único status genérico de “e-mail aprovado”.

Para o recebimento, um endereço temporário pode ser conveniente quando o teste só precisa de uma caixa separada para uma rodada do próprio produto. O HourInbox pode ser considerado como uma opção de recebimento; antes de incluí-lo no fluxo, confira na página do serviço se a forma de acesso e os recursos disponíveis atendem ao teste. Não trate um recebimento observado como garantia de entrega em produção: ele confirma somente o resultado daquele cenário e daquele destino.