Como usar uma API de e-mail temporário sem criar testes instáveis

E-mail não é uma chamada síncrona. O sistema em teste pode enfileirar uma tarefa, o provedor pode atrasar a entrega e filtros podem mudar a ordem. Um teste estável precisa modelar essas etapas em vez de usar sleep fixo.

Uma caixa por caso

Crie uma caixa isolada para cada execução ou cenário. Não compartilhe endereço entre jobs paralelos. Registre o identificador da caixa apenas no contexto temporário do teste e nunca publique chave de API ou token em logs.

Use dados sintéticos e um identificador de correlação não secreto no evento. A caixa não deve receber dados reais de cliente, senha ou documento.

Consulta com orçamento

Depois de disparar a ação, consulte a lista com intervalo crescente e limite total. Por exemplo, espere poucos segundos entre as primeiras tentativas e aumente gradualmente, respeitando o limite de requisições. Encerre com erro claro quando o orçamento acabar.

Não faça loop infinito e não crie outra caixa a cada consulta. Criação e troca consomem a quota própria; mensagens recebidas seguem contrato separado. Os valores devem vir da configuração e resposta da API, não de números espalhados no teste.

Selecione a mensagem correta

Correlacione por destinatário, tipo de evento, identificador seguro e horário posterior à solicitação. Assunto sozinho é insuficiente. Se houver duplicata, registre o comportamento esperado e não aceite arbitrariamente a primeira.

Valide texto, HTML, idioma, links e expiração sem imprimir segredos. O código de uso único pode ser comparado em memória e redigido imediatamente.

Erros e idempotência

Teste respostas 400, 401, 403, 404 e 429 conforme o contrato. Uma repetição depois de timeout não deve criar caixas indefinidamente. Use chave idempotente quando a API oferecer essa capacidade e trate limites como resultado esperado, não falha de infraestrutura.

A documentação pública deve indicar autenticação, quota e retenção antes da abertura comercial. Não construa dependência de um endpoint descrito como candidato até existir versão estável.

Limpeza determinística

Coloque a exclusão da caixa em finally, inclusive quando a asserção falhar. Defina timeout para a própria limpeza e registre somente o resultado. Artefatos de CI devem expirar e não conter corpo da mensagem.

A checklist de testes de e-mail cobre apresentação e acessibilidade; este padrão cobre orquestração. Juntos, eles tornam a falha localizável sem esconder a natureza assíncrona do transporte.

Métricas úteis

Meça tempo entre solicitação e primeira observação, número de consultas e taxa de timeout por ambiente. Não publique endereços ou conteúdo. Tendências agregadas ajudam a ajustar orçamento sem transformar uma execução lenta em espera permanente.

Contrato de configuração

Mantenha quota mensal, limite por minuto, duração e máximo de consultas em configuração versionada. O teste pode receber valores diferentes por ambiente, mas deve registrar qual contrato aplicou. Não use “ilimitado” para criações quando existe uma franquia; diferencie explicitamente operações de caixa de mensagens recebidas. Essa separação evita cobrança inesperada e asserções incompatíveis com produção.

Diagnostique a etapa, não apenas “o e-mail não chegou”

Antes de ativar o teste no CI, registre somente etapa, duração limitada, status HTTP, ID de solicitação quando existir, quantidade de candidatos e um ID de execução sem segredo. Não registre endereço, código, link, assunto, corpo, anexo, chave de API nem consulta completa.

Classifique antes de repetir: gatilho recusado pertence ao aplicativo; entrega pendente significa que nenhum candidato chegou até o prazo; em 429 ou 503, respeite Retry-After sem ampliar o orçamento; vários candidatos indicam correlação ambígua; destino controlado incorreto é falha de asserção; e falha de limpeza deve ser separada do resultado principal.

Confirme também que o provedor documenta API, autenticação, exclusão, expiração e limites. A Once Email ainda não oferece API pública de produção; estes exemplos são padrões independentes de fornecedor, não endpoints disponíveis da Once Email.

Use um SDK sem esconder o desenho do teste

O Once Email oferece candidatos SDK testados para TypeScript, Python, Java, Go, .NET, PHP e Ruby. Comece na página de SDK, escolha a linguagem já usada pelo serviço de teste e revise o diretório de código; não adicione outro runtime apenas para consultar uma caixa.

Os candidatos vêm de uma GitHub Release imutável, não de um registro. Compare o arquivo com SHA256SUMS, leia o README incluído e fixe a versão. Comandos npm, PyPI, Maven Central, NuGet, Packagist ou RubyGems não aparecem antes de essas publicações existirem.

O SDK reduz serialização HTTP, mas não decide prazo, correspondência ou limpeza. Use uma caixa, um proprietário de polling e um prazo por teste autorizado; respeite Retry-After no 429, diferencie 503 de caixa vazia, rejeite resultados ambíguos e exclua no finally. Confira também o contrato da API somente de recebimento.