2026: Como testar e-mails de código de verificação de cadastro no Cypress 16?

Antes de começar: defina o que o teste precisa provar

Um teste de cadastro com e-mail pode cobrir objetivos diferentes. Se a equipe não separar esses objetivos, é fácil interpretar um resultado positivo como prova de algo que o teste nunca verificou.

• Fluxo da aplicação: o envio foi solicitado e a aplicação produziu uma mensagem de verificação com o conteúdo esperado.
• Validação do código: o código recebido foi aceito, a interface mostrou o resultado previsto e a conta passou ao estado validado.
• Entrega externa: a mensagem chegou a uma caixa de entrada fora do ambiente controlado, nas condições de entrega que interessam ao produto.

A leitura feita por uma tarefa Node ou por uma interface do ambiente de teste costuma servir aos dois primeiros objetivos, conforme a arquitetura do produto. Ela não comprova automaticamente o terceiro. Para testar entrega externa, planeje uma verificação de pré-produção com destinatário e condições conhecidos, separada da regressão rotineira.

O destino de teste deve ser controlado pela equipe e vinculado ao ambiente correto. Não use uma caixa pessoal de alguém da equipe nem uma conta de produção como destino recorrente: isso pode misturar dados reais com fixtures, expor informações pessoais em logs e encher uma caixa de trabalho com mensagens de regressão. A orientação sobre privacidade de dados ajuda a estabelecer limites para endereços e informações usadas em testes.

A escolha do destino depende do objetivo. Um serviço local de captura de e-mails ou uma interface de teste da própria aplicação pode permitir que o processo consulte mensagens sem depender de uma caixa pessoal. A FAQ oficial do Cypress é uma referência para distinguir recursos do framework de serviços externos que precisam ser integrados. Se a equipe preferir um endereço temporário para um teste próprio, avalie antes as características necessárias em um guia para escolher uma caixa de entrada de teste. O endereço precisa ser acessível pelo mecanismo de leitura que o projeto realmente usa; não presuma que qualquer caixa temporária ofereça uma API compatível com a automação.

Preparação: mantenha a execução isolada

Antes de abrir a página de cadastro, defina um contrato entre o teste no navegador e o mecanismo de leitura. Esse contrato precisa informar qual mensagem procurar e como relacioná-la à execução atual, sem passar credenciais de produção ao código do teste.

Um identificador pode ser um endereço específico de teste ou um marcador de execução que o sistema de e-mail controlado consiga encontrar. Se houver execuções paralelas, o destino ou o identificador deve evitar que duas tarefas consumam a mesma mensagem. O marcador não precisa ser um dado pessoal: prefira um identificador criado para o teste, que não contenha nome, e-mail real ou outro dado identificável.

Confira também o que os logs podem registrar. O conteúdo da mensagem pode conter o código; portanto, evite imprimir o corpo completo nos logs de CI. Registre informações de diagnóstico suficientes para localizar a falha — como ambiente, identificador da execução, assunto e etapa — e oculte o código e outros dados sensíveis sempre que possível.

Pergunta: onde esperar a mensagem durante um teste de cadastro no Cypress?
A espera deve acontecer na tarefa Node ou na interface de teste que consulta as mensagens, não em uma suposição de que o navegador consegue abrir uma caixa de entrada. A documentação de cy.task() descreve a passagem de trabalho do processo de teste para o Node. Use essa fronteira para chamar o mecanismo de leitura controlado pelo projeto.

Gatilho: envie o cadastro e marque a mensagem esperada

O Cypress deve executar as ações visíveis para a pessoa usuária: abrir o formulário, preencher os campos de teste e enviar o cadastro. Depois do envio, o teste precisa guardar o endereço de destino e o identificador de correlação escolhidos na preparação. Esses dados servem para pedir ao mecanismo de leitura a mensagem certa.

Um esqueleto de teste pode ser assim:

it('valida o cadastro pelo código recebido', () => {
  const runId = Cypress.env('RUN_ID');
  const email = makeTestAddress(runId);

  cy.visit('/cadastro');
  cy.get('[name="email"]').type(email);
  cy.get('[name="password"]').type(Cypress.env('TEST_PASSWORD'));
  cy.get('form').submit();

  cy.contains('Confira seu e-mail').should('be.visible');

  cy.task('mail:waitForVerification', { email, runId })
    .then(({ code, messageId }) => {
      cy.get('[name="verificationCode"]').type(code);
      cy.get('button[type="submit"]').click();
      cy.contains('E-mail confirmado').should('be.visible');

      return cy.task('account:getVerificationState', { email, runId })
        .then((state) => {
          expect(state.verified).to.equal(true);
          expect(messageId).to.be.a('string');
        });
    });
});

Os seletores, os nomes das tarefas e a forma de criar um endereço são exemplos estruturais, não APIs prontas do Cypress nem uma integração de caixa de entrada. Adapte-os às rotas e aos elementos do seu produto. A tarefa mail:waitForVerification precisa chamar o mecanismo real de leitura disponível no ambiente. A tarefa account:getVerificationState também precisa consultar uma fonte de estado de teste autorizada, em vez de inferir que a conta foi validada somente porque a página mostrou uma mensagem de sucesso.

Não use uma conta de outra plataforma ou um fluxo de cadastro alheio como alvo. O teste deve exercitar uma aplicação que a equipe controla, com dados criados para esse ambiente. Essa fronteira evita transformar um teste de produto em automação de cadastros de terceiros.

Recebimento: aguarde uma mensagem correspondente, não um intervalo fixo

Pergunta: como evitar que o teste leia um e-mail de uma execução anterior?
Faça a consulta exigir critérios associados à execução atual: destinatário, marcador, tipo de mensagem e, quando disponível, um identificador ou horário registrado pelo mecanismo de captura. Não selecione simplesmente “a mensagem mais recente” se a caixa for compartilhada por vários testes; uma mensagem nova de outro caso pode ser a mais recente e ainda assim ser a mensagem errada.

A tarefa no Node pode expor uma operação com esta forma:

on('task', {
  async 'mail:waitForVerification'({ email, runId }) {
    const message = await mailReader.findMatchingMessage({
      recipient: email,
      runId,
      template: 'verification',
    });

    if (!message) {
      throw new Error(`Mensagem de verificação não encontrada para ${runId}`);
    }

    return {
      code: extractVerificationCode(message.text),
      messageId: message.id,
    };
  },
});

mailReader e extractVerificationCode são abstrações a implementar com a ferramenta escolhida. A busca deve esperar até encontrar uma mensagem que corresponda aos critérios ou atingir um limite explícito de timeout. Um cy.wait() fixo pode mascarar uma corrida: se o e-mail chegar antes, o teste perde tempo; se chegar depois, o teste falha sem explicar se houve atraso, erro de envio ou consulta ao destino errado.

A documentação de cy.task() informa que taskTimeout tem valor padrão de 60 segundos. Esse limite se refere à execução da tarefa, não é uma recomendação para dormir por esse período antes de procurar uma mensagem. Ajuste o limite de acordo com o ambiente e com a operação realizada, e implemente a busca com tentativas limitadas e critérios claros. Se a tarefa não encontra o e-mail, devolva um erro que identifique o ambiente e a correlação da execução, sem revelar o código. Veja o comportamento documentado de cy.task() e taskTimeout.

A tarefa precisa resolver com um resultado serializável ou falhar de forma explícita. Se não houver mensagem, não devolva um valor indefinido que deixe o teste seguir com um estado ambíguo. Uma falha com contexto é mais útil do que uma asserção posterior de código vazio, porque aponta a etapa que não foi concluída.

Pergunta: como fazer o teste E2E de e-mail de cadastro no Cypress sem acoplar o navegador ao provedor?
Mantenha a consulta atrás de uma tarefa Node ou de um endpoint do ambiente de teste. Assim, a parte de navegador trata da interface, enquanto a integração de e-mail trata da busca e da extração. Essa separação também permite trocar o mecanismo de captura sem reescrever cada interação do formulário.

Validação: use o código e confira o estado persistido

Depois de receber a mensagem correspondente, extraia o código usando uma regra coerente com o formato criado pelo próprio produto. Se o código aparece como texto simples, uma expressão regular pode bastar; se o template muda conforme o idioma ou o canal, prefira identificar o conteúdo por uma estrutura estável ou por uma função testada separadamente.

Evite uma expressão que pegue qualquer sequência numérica do e-mail. A mensagem pode incluir datas, identificadores ou números de suporte. Se a extração produzir zero ou mais de um candidato, falhe com uma mensagem diagnóstica: a equipe precisa distinguir “o e-mail não chegou” de “chegou, mas o formato não corresponde ao esperado”. Não inclua o código integral no relatório de CI.

A submissão do código deve ocorrer pelo próprio fluxo da aplicação. Em seguida, verifique duas camadas:

• Resposta visível: confirmação, navegação ou estado de interface previsto para um cadastro validado.
• Estado da conta: consulta autorizada ao banco de teste, API interna ou mecanismo equivalente, verificando que o registro foi marcado como validado.

A segunda asserção evita que uma tela de sucesso esconda um defeito de persistência. A primeira evita que a aplicação atualize o estado interno sem fornecer a resposta esperada na interface. Para não criar dependência entre testes, use uma conta nova ou reinicialize o estado conforme as regras do ambiente; não reutilize um cadastro já validado como se fosse um fluxo limpo.

Repetição e falhas: preserve evidências úteis

Inclua cenários que correspondam às regras reais do produto. A validade do código, a possibilidade de reenviar e o tratamento de códigos anteriores variam conforme a implementação; não existe uma política universal que o teste possa presumir. Documente a regra do próprio sistema e escreva as asserções a partir dela.

Considere cobrir estas falhas:

• Nenhuma mensagem correspondente: o teste deve falhar na etapa de recebimento e registrar destinatário de teste, identificador da execução e ambiente.
• Código extraído não aceito: preserve o identificador da mensagem e confirme se a extração encontrou o conteúdo correto, sem expor o código nos logs.
• Código incorreto: confirme a mensagem de erro e que a conta permanece no estado não validado.
• Reenvio do cadastro ou da mensagem: confira se o sistema aplica a regra esperada e se a tarefa não seleciona uma mensagem antiga.
• Validação incompleta: garanta que a conta continua não validada quando a pessoa não conclui o fluxo.

Uma falha deve dizer em qual etapa o fluxo parou. Isso reduz o tempo gasto tentando descobrir se o problema está no formulário, no envio, na captura, na extração ou na persistência. Para um registro de diagnóstico seguro, guarde identificadores e metadados mínimos; não armazene o conteúdo integral da caixa de entrada como artefato de CI.

Decisão para CI: automação de fluxo ou validação de entrega?

Use esta lista de condições antes de escolher o destino de e-mail:

• Se o objetivo é testar interface, conteúdo e estado da conta, use uma caixa ou interface controlada pelo ambiente de teste e faça a leitura pela tarefa Node.
• Se as execuções paralelas podem compartilhar mensagens, isole o destinatário ou inclua um identificador por execução e exija a correspondência antes de aceitar o e-mail.
• Se o objetivo inclui provar a entrega fora do ambiente, não trate a captura interna como evidência suficiente; faça uma validação separada em pré-produção com condições de recebimento documentadas.
• Se o fluxo precisa receber respostas ou manter histórico de longo prazo, não escolha um endereço temporário sem confirmar que ele atende a essas necessidades. Use um endereço de teste persistente, alias ou caixa controlada pela equipe.

Essa decisão evita misturar duas medições distintas: “a aplicação produziu uma mensagem que o ambiente de teste consegue consultar” e “um serviço externo entregou a mensagem como esperado”. A primeira é adequada para muitas regressões automatizadas; a segunda exige observar o caminho externo e registrar as condições do ensaio.

Na prática, o fluxo mais estável separa as responsabilidades: Cypress conduz o navegador, a tarefa Node consulta a mensagem e o ambiente de teste confirma o estado da conta. Um endereço temporário pode ser uma opção para cadastro de teste próprio quando o mecanismo de leitura for compatível e a necessidade for pontual. Para esse caso, o HourInbox oferece uma forma de usar uma caixa temporária sem cadastro e sem expor o endereço principal; ainda assim, a equipe deve confirmar que o destino escolhido funciona com a integração e a política de retenção de seu ambiente. Para um teste recorrente que exige histórico, resposta ou recuperação posterior, uma caixa persistente controlada pelo projeto é a escolha mais segura.