Automação Confiável da API de Caixa de Entrada Temporária

A versão não confiável de um teste de e‑mail é curta: criar um endereço, aguardar cinco segundos, ler a primeira mensagem e esperar que ela pertença a esta execução.

A versão confiável ainda é simples, mas trata a entrega como assíncrona. Ela cria um endereço único, registra um horário de início, faz sondagens dentro de um prazo, corresponde à mensagem desejada, valida a ação do produto e relata contexto suficiente quando algo falha.

Mantenha a chave da API fora da URL

Envie a chave do GPTMail no cabeçalho X-API-Key. Não a coloque nos parâmetros de consulta ?api_key=. URLs são rotineiramente armazenadas no histórico do navegador, logs de acesso, sistemas de monitoramento e dados de referência.

X-API-Key: YOUR_API_KEY

Armazene a chave no gerenciador de segredos do seu CI e oculte-a nos logs. Uma chave pública diária é conveniente para exploração; suítes automatizadas controladas devem usar uma chave cuja cota e uso você possa rastrear.

Os endpoints atuais e exemplos de resposta são mantidos na página de documentação da API do GPTMail.

Um endereço por execução

Gere um novo endereço para cada teste executável de forma independente. Não baseie a correção em uma caixa de entrada compartilhada por toda a suíte de testes.

Registre o endereço, ID do cenário, ambiente e horário de início do teste. Esses valores permitem rejeitar mensagens obsoletas e diagnosticar colisões sem registrar segredos das mensagens.

Sondar até um prazo, não um tempo de espera fixo

O tempo de entrega de e‑mail varia. Uma espera fixa de cinco segundos é desperdiçada quando a entrega é rápida e instável quando é lenta.

Use um loop limitado:

deadline = now + 90 seconds
delay = 2 seconds

while now < deadline:
  messages = list inbox
  candidate = newest message matching sender, subject, and start time
  if candidate exists:
    read candidate and continue the product test
  wait delay with a small random jitter
  delay = min(delay * 1.5, 10 seconds)

O prazo faz parte do contrato do teste. Um fluxo de redefinição de senha pode precisar de um limite diferente de uma pré‑visualização de newsletter em massa. Mantenha o limite explícito para que uma dependência lenta não prolongue silenciosamente todo o job de CI.

Corresponda com precisão

“Primeira mensagem na caixa de entrada” não é um seletor útil. Corresponda a vários sinais:

• destinatário igual ao endereço criado para esta execução;
• horário de criação posterior ao horário de disparo;
• remetente pertence ao serviço esperado;
• assunto ou tipo de mensagem corresponde ao fluxo;
• o ID da mensagem ainda não foi consumido.

Quando o remetente pode emitir vários códigos, selecione a mensagem correspondente mais recente. Preserve seu ID na saída do teste para que tentativas de repetição não a reutilizem acidentalmente.

Leia somente após uma correspondência na lista

Listar a caixa de entrada deve ser a etapa de descoberta barata. Busque a mensagem completa apenas para o candidato selecionado. Isso reduz trabalho desnecessário e evita analisar e‑mails promocionais não relacionados.

Valide o resultado de negócio, não apenas a presença de uma sequência de seis dígitos. Envie o código ou abra o link esperado, então verifique se a conta atinge o estado correto.

Trate limites de taxa como um sinal

Se a API retornar uma resposta de cota ou limite de taxa, interrompa a tentativa atual e exponha as informações de redefinição. Retries agressivos transformam um sinal claro de capacidade em ruído e podem atrasar testes não relacionados.

Limite a concorrência no executor de testes, especialmente quando uma suíte cria muitos endereços de uma vez. Um pequeno pool de workers é mais fácil de depurar do que centenas de loops de sondagem simultâneos.

Limpeza sem ocultar falhas

A limpeza deve ser executada após a captura de evidências. Em caso de sucesso, remova as mensagens ou deixe que a retenção curta as trate. Em caso de falha, mantenha o endereço e o ID da mensagem em artefatos de CI protegidos tempo suficiente para investigação, então exclua-os.

Nunca imprima códigos de verificação, links privados ou corpos HTML completos nos logs de build públicos.

Torne as tentativas de repetição idempotentes

Reexecute o teste como uma nova execução com um novo endereço. Não presuma que repetir a mesma solicitação contra a mesma conta e caixa de entrada começa a partir de um estado limpo. O remetente pode invalidar códigos antigos, limitar solicitações repetidas ou rejeitar convites duplicados.

Se uma solicitação de rede expirar, distinga “nenhuma resposta recebida” de “operação não ocorreu”. Verifique o estado observável antes de emitir uma tentativa de repetição destrutiva.

Relate o ponto de falha

Uma falha de automação útil identifica um destes estágios:

1. falha na geração do endereço;
2. ação do produto falhou antes de enfileirar o e‑mail;
3. nenhuma mensagem correspondente chegou antes do prazo;
4. mensagem chegou, mas o conteúdo não correspondeu;
5. ação de verificação falhou;
6. limpeza falhou.

Essa classificação transforma um “teste de e‑mail falhou” intermitente em um trabalho que a equipe pode assumir.

Para a matriz de testes maior, leia Um Plano Real de Teste de E‑mail. Para diagnóstico de entrega, use E‑mail de Verificação Não Chegando: Encontre a Etapa Quebrada.