Como validar o e-mail de login Magic Link do Auth.js em 2026?

A documentação do Email Provider do Auth.js descreve a solicitação do link e sua validação quando ele é aberto como partes diferentes do fluxo. Por isso, um teste do e-mail de login Magic Link no Auth.js só deve ser aprovado quando você comprovar o recebimento da mensagem, o funcionamento do link e a criação da sessão. Um envio aceito pelo serviço, sozinho, não prova que o usuário conseguiu entrar.

Adequado: você está testando a sua aplicação ou um ambiente para o qual tem autorização e consegue ler a caixa de entrada. Inadequado: você quer testar contas de terceiros ou concluir que a entrega em produção está garantida a partir de uma única caixa de teste.

Este guia é para você que implementa o Auth.js Email Provider e precisa validar o login da própria aplicação. Também atende QA que verifica mensagens e falhas de autenticação, além de equipes pequenas que querem evitar enviar testes para caixas pessoais ou de trabalho.

Antes do teste: que resultado você precisa comprovar?

Comece separando três resultados que costumam ser confundidos:

Solicitação de envio: a aplicação aceitou o pedido de login e acionou o fluxo de e-mail. Isso comprova que a etapa foi iniciada, não que alguém recebeu uma mensagem.
Recebimento: a mensagem apareceu na caixa de entrada que você controla, com o destinatário e o conteúdo esperados. Esse é o sinal de que a mensagem chegou àquela caixa específica.
Login concluído: o link levou ao ambiente correto, o callback foi processado e a aplicação reconheceu a sessão do usuário esperado.

Essa separação reduz falsos positivos. Por exemplo, um log de envio sem erro pode coexistir com endereço incorreto, mensagem filtrada ou link apontando para outro ambiente. Da mesma forma, uma página que carrega depois do clique pode ser pública e não demonstrar que a sessão foi criada.

Defina também o que significa “aprovado” antes de começar. Anote o ambiente usado, a página que deve abrir após o login e a identidade ou o estado de conta esperado. Se o objetivo é testar uma conta nova, registre o resultado esperado para essa conta; se é testar um usuário existente, não misture o caso com a criação inicial de dados.

O guia de instalação do Auth.js trata da configuração do projeto e de suas rotas. Use a configuração real da sua aplicação como referência: não presuma que uma rota, uma variável de ambiente ou um endereço-base terá o mesmo valor em todo projeto.

Primeira etapa: prepare a caixa e associe o teste

Escolha uma caixa de teste que você consiga abrir durante toda a execução. A mensagem precisa estar acessível para conferir o conteúdo e copiar o link; um endereço que apenas receba notificações sem permitir leitura não atende a esse objetivo. Para escolher entre uma caixa descartável e uma alternativa mais duradoura, considere se você precisará repetir o teste, consultar o histórico ou recuperar a conta depois. A comparação entre e-mail mascarado e endereço descartável ajuda a avaliar essa diferença sem tratar as opções como equivalentes.

Antes de disparar o pedido:

Use um endereço reservado para testes da sua aplicação ou um endereço cuja utilização tenha sido autorizada.
Confirme que você consegue abrir a caixa e identificar mensagens recentes.
Anote se o teste ocorre em desenvolvimento, pré-produção ou produção. Não misture resultados de ambientes diferentes.
Escolha uma identificação da execução, como o identificador já presente no seu sistema de testes ou uma anotação no registro de QA. Evite colocar dados pessoais desnecessários no assunto, no endereço ou nos logs.
Defina o resultado esperado: endereço da página após o login, estado da conta e recurso protegido que deverá reconhecer o usuário.

Associe cada mensagem à execução que a gerou. Quando você dispara várias tentativas sem registrar o ambiente ou o horário, fica mais difícil saber qual link pertence a qual pedido. Se o projeto já registra eventos de autenticação, use esses registros para correlação; não acrescente tokens completos ou links secretos aos logs apenas para facilitar a depuração.

Essa preparação também protege os dados de teste. Endereços pessoais e dados reais de colegas podem acabar em logs, capturas de tela ou sistemas de terceiros. Uma caixa dedicada à validação reduz essa exposição, mas não elimina a necessidade de limitar acesso e retenção. Para aprofundar esse ponto, consulte as práticas de privacidade em testes e uso de e-mail.

Segunda etapa: faça a solicitação e confirme a mensagem

Acesse a tela de login da sua aplicação e solicite o Magic Link usando o endereço de teste. Faça a operação pelo caminho normal do usuário, em vez de fabricar uma mensagem ou inserir manualmente um link. Assim, você verifica a integração entre a interface, o fluxo do Auth.js e a configuração de envio realmente usada pelo ambiente.

Em seguida, registre o resultado da solicitação. Se a interface informa que o pedido foi iniciado, anote isso como evidência da primeira etapa, não como confirmação de entrega. Consulte os registros da aplicação e do serviço de envio disponíveis no seu ambiente, mas interprete cada um com cuidado: uma resposta positiva do serviço não comprova que a mensagem apareceu na caixa de entrada de destino.

Abra a caixa controlada e procure a mensagem correspondente à solicitação. Confira o destinatário, o remetente exibido, o assunto e o conteúdo. Se a mensagem não aparecer, verifique primeiro se o endereço foi digitado corretamente e se você está consultando a caixa certa. Depois, examine os registros disponíveis para localizar em que ponto o processo parou. Não marque o teste como aprovado apenas porque o log indica uma tentativa de envio.

O Auth.js documenta o processo do provedor e a configuração que pode depender do adaptador utilizado. Se o projeto usa Drizzle, compare a implementação com o guia oficial do adaptador Drizzle; para outros casos, consulte a documentação do adaptador correspondente e a referência de adaptadores. Isso ajuda a evitar que você atribua ao provedor um comportamento que, na verdade, depende da persistência ou da configuração do projeto.

Terceira etapa: valide o endereço do link antes de abri-lo

Quando a mensagem chegar, examine o link sem editá-lo. Confira se o endereço aponta para o ambiente em que você iniciou o teste e se a rota de retorno corresponde à configuração da aplicação. O endereço correto deve ser consequência da configuração do seu projeto; não existe motivo para presumir um host ou uma rota universal apenas por estar usando Auth.js.

Se o link levar ao ambiente errado, comece por estas verificações:

Compare o endereço-base configurado no processo que enviou a mensagem com o ambiente que você pretendia testar.
Confira a rota de callback e as rotas registradas pela aplicação. Verifique se a implantação atual usa as rotas esperadas.
Leia o modelo de e-mail e confirme como ele monta ou recebe a URL. Não substitua o link recebido por um endereço corrigido à mão.
Verifique se o pedido foi iniciado na aplicação correta e se a mensagem observada pertence à execução que você registrou.
Repita o teste depois da correção e guarde a nova mensagem como evidência. A mensagem antiga não serve para provar que a configuração corrigida funciona.

Atenção: abrir um link corrigido manualmente pode demonstrar que uma rota responde, mas não valida o link que a aplicação enviou. Registre o defeito original e repita o fluxo completo depois de ajustar a configuração.

A referência do Email Provider do Auth.js é o lugar adequado para confirmar os detalhes da API do provedor. Use-a junto com a configuração do seu próprio projeto: não infira valores padrão, duração de validade ou comportamento de implantação a partir de exemplos que não correspondem à sua versão e ao seu ambiente.

Quarta etapa: clique e confirme a sessão, não só a navegação

Abra o link recebido no mesmo ambiente ao qual ele se destina. Observe se a aplicação processa o callback sem erro e se chega à página prevista. Em seguida, confirme o estado de autenticação: por exemplo, acesse uma área que exige login ou confira um indicador de sessão que a própria aplicação disponibiliza.

Um redirecionamento, por si só, não prova que o login terminou. A rota pode enviar o usuário para uma página pública mesmo quando a validação falhou. Também é possível que uma tela carregue antes de a aplicação atualizar o estado de sessão. Por isso, valide uma ação protegida e confirme que o usuário reconhecido corresponde ao endereço de teste usado no pedido.

A orientação do Auth.js sobre proteção de recursos pode ajudar a identificar um ponto da aplicação que dependa de uma sessão válida. Escolha um recurso não destrutivo e apropriado para QA. Não use uma operação que altere dados importantes como prova de autenticação quando uma página protegida ou um estado de sessão basta.

Separe os registros: mensagem recebida, link aberto, callback observado e sessão reconhecida. Se o clique falhar, essa separação permite localizar o problema sem concluir que a entrega foi ruim quando o defeito está no callback, ou vice-versa. Evite armazenar o link completo em relatórios compartilhados, pois ele pode conter material de autenticação; registre o resultado e remova ou proteja qualquer dado sensível.

Quinta etapa: reenvie e teste links antigos com cautela

Depois do caso normal, repita a solicitação pela interface da sua aplicação. Confira se a nova mensagem chega e se o link recebido leva ao ambiente esperado. Não suponha que um pedido novo invalida automaticamente uma mensagem anterior. A validade do link, a política de reutilização e o tratamento de links antigos dependem da implementação e da configuração adotadas.

Teste a abertura repetida do mesmo link em um ambiente controlado. Registre se a aplicação aceita, recusa ou apresenta outro resultado, e compare com o comportamento que o seu produto pretende oferecer. Faça o mesmo com uma mensagem anterior depois de uma nova solicitação, se esse cenário for relevante para os usuários do seu sistema. Não transforme um resultado particular em regra geral do Auth.js.

Inclua também um caso de link inválido ou alterado, sem expor credenciais reais. O objetivo é verificar se a aplicação responde de forma compreensível e segura, sem revelar detalhes internos desnecessários. Se o sistema exibe uma mensagem de erro, confirme se ela orienta o usuário sobre o próximo passo sem afirmar que a sessão foi criada.

Para evitar interpretações erradas, anote a configuração vigente quando executar esses testes e repita-os após mudanças no provedor, adaptador ou fluxo de callback. O que vale para a implementação atual não deve ser apresentado como garantia para outras versões ou ambientes.

Checklist de aceite antes de fechar o chamado

Marque cada item apenas quando houver evidência observável. Se algum ponto falhar, registre qual etapa falhou e evite resumir tudo como “o e-mail não funciona”.

[ ] O teste foi feito na aplicação própria ou em um ambiente autorizado.
[ ] O ambiente e a conta esperados foram registrados antes da solicitação.
[ ] A aplicação iniciou o pedido de Magic Link e o resultado foi anotado separadamente do recebimento.
[ ] A mensagem apareceu em uma caixa que você consegue ler, e o destinatário corresponde ao teste.
[ ] O link recebido aponta para o ambiente e a rota esperados, sem correção manual.
[ ] O callback terminou e uma área protegida reconheceu a sessão da conta correta.
[ ] Reenvio, abertura repetida e link inválido foram avaliados conforme o escopo do teste, sem presumir uma política universal.
[ ] O registro de QA não expõe o link completo nem dados pessoais desnecessários.

O aceite também deve dizer o que ficou fora do escopo. Uma caixa controlada comprova que aquela mensagem chegou àquele destino no teste realizado; não comprova que todos os provedores, filtros ou usuários finais receberão mensagens da mesma forma. Se a validação ocorreu em desenvolvimento, registre que o comportamento de pré-produção ou produção ainda exige verificação no ambiente correspondente.

Dúvidas frequentes sobre o teste

Como comprovar que o endereço de teste recebeu a mensagem?

Use uma caixa de entrada controlada que permita abrir a mensagem e conferir o destinatário, o horário e o link recebido. Registre essa evidência separadamente do resultado do serviço de envio: a aceitação de uma solicitação de envio não comprova que a mensagem chegou à caixa, nem que o link funciona.

O que devo verificar depois de abrir o link de login?

Não trate o redirecionamento como prova suficiente. Confirme que a aplicação concluiu o callback esperado, que a conta corresponde ao endereço de teste e que uma página ou recurso protegido reconhece a sessão. Se possível, registre também o estado exibido pela própria aplicação, sem copiar tokens para logs.

Como avaliar um link aberto mais de uma vez?

Teste o mesmo link novamente no ambiente controlado e observe a resposta da aplicação, sem pressupor que todo projeto invalide o link da mesma forma. Confira também uma solicitação nova e um link antigo. A validade e a reutilização dependem da implementação e da configuração; documente o comportamento observado.

O link leva ao ambiente errado. O que devo conferir primeiro?

Compare o endereço-base usado pelo projeto, a rota de callback, o ambiente que gerou a mensagem e o conteúdo do modelo de e-mail. Depois, verifique se a URL recebida aponta para o host esperado antes de abri-la. Não corrija o link manualmente para considerar o teste aprovado: isso esconderia uma falha de configuração.

Se você precisa ler a mensagem e abrir o link, uma caixa temporária pode separar a validação da sua caixa pessoal ou de trabalho. Antes de escolher esse caminho, confirme na própria interface do serviço se a caixa permite consultar o conteúdo e copiar o link pelo tempo necessário para o seu teste; se a sua equipe precisar manter histórico ou recuperar a conta mais tarde, prefira um endereço controlado de uso contínuo. Quando uma caixa temporária atender a esse cenário, você pode avaliar o recebimento disponível no TMPFox como uma opção para testar o fluxo da sua própria aplicação, sem confundir esse teste isolado com uma garantia de entrega em produção.