Tutoriais · 2026
2026 Teste de verificação de e-mail do Firebase Auth: como validar links locais?
Para desenvolvimento local e automação, use o Firebase Authentication Emulator: ele permite obter o link de verificação sem depender de uma caixa de entrada externa. No pré-lançamento, complemente essa validação com um endereço de teste dedicado para confirmar o recebimento real, o destino do link e o estado atualizado da conta.
Decisão rápida
Indicado: para desenvolvimento local e testes automatizados, use o Firebase Authentication Emulator e obtenha o link de verificação na saída do emulador. Não indicado como prova de entrega: antes de publicar, valide também o envio real com um endereço de teste dedicado. O emulador testa o fluxo de autenticação; não comprova que uma mensagem chegou a uma caixa de entrada externa.
Este guia é para você que implementa cadastro ou recuperação de acesso com Firebase Auth, verifica o fluxo como QA ou prepara um pré-lançamento e precisa separar o que o teste local prova do que ainda precisa ser validado fora dele.
O emulador valida o fluxo, não a entrega real
No teste de verificação de e-mail do Firebase Auth, o emulador é a escolha mais direta quando você quer verificar a ação de autenticação sem depender de uma caixa de entrada. O Firebase Auth Emulator registra na saída do processo o link de verificação gerado. Você pode abri-lo no navegador ou extrair seu código de ação durante um teste automatizado. A documentação oficial do emulador descreve esse fluxo.
A distinção importa porque há etapas diferentes envolvidas:
- Geração da ação: seu aplicativo pede ao Firebase que envie uma verificação para a conta.
- Processamento da ação: o usuário abre um link e o código de ação é aplicado.
- Entrega da mensagem: um serviço de envio entrega a mensagem a uma caixa de entrada real.
- Retorno ao aplicativo: o usuário chega à página correta e vê o estado atualizado.
No ambiente local, você consegue testar a geração e o processamento da ação sem depender de uma mensagem real. Mas isso não valida o serviço de envio, a aceitação pelo domínio de destino, a pasta de spam nem a navegação pública do domínio de produção. Se você tratar a saída do emulador como prova de entrega, pode descobrir tarde demais que um problema de configuração ou entrega só aparece fora do ambiente local.
Também há custos ocultos em usar sempre uma caixa real: você precisa localizar mensagens entre execuções, controlar contas criadas para testes e evitar que notificações de desenvolvimento poluam uma caixa de trabalho. Em contrapartida, trocar o emulador por uma caixa de entrada real em cada teste torna a execução dependente de um serviço externo. Quando esse serviço está lento ou indisponível, pode ficar difícil distinguir uma falha do aplicativo de uma falha de entrega.
Escolha o ambiente conforme o que precisa provar
A tabela ajuda a escolher o teste adequado. Nenhuma opção substitui as outras em todos os cenários.
| Opção | O que você consegue validar | Dependência externa | Quando escolher |
|---|---|---|---|
| Firebase Authentication Emulator | Geração do link, aplicação do código e atualização do estado da conta | Não precisa de uma caixa de entrada real para obter o link | Desenvolvimento local e testes automatizados |
| Caixa de entrada de teste no pré-lançamento | Recebimento da mensagem, acesso ao link e retorno ao aplicativo | Sim: envio real e endereço consultável | Validação do caminho de ponta a ponta antes de publicar |
| Conta pessoal ou de trabalho | Um fluxo real usando uma conta que pode ter importância fora do teste | Sim, além de riscos de privacidade e de mistura de dados | Evite como padrão; reserve apenas para um caso controlado que exija essa conta |
Essa escolha também afeta a qualidade dos dados. Contas inventadas para testes evitam inserir dados pessoais de colegas ou usuários em ambientes de desenvolvimento. Mantenha o endereço e o identificador do usuário associados à execução que os criou. Não use uma conta de outra execução como se fosse a atual: um código pode pertencer a outro usuário ou já ter sido aplicado, e isso torna o resultado difícil de interpretar.
Para avaliar o que você compartilha quando usa um endereço de teste, consulte o guia de privacidade para e-mails temporários. A decisão não é usar um endereço descartável em qualquer situação. É limitar a exposição de dados sem prejudicar a validação necessária.
No navegador, confirme a ação e depois o estado
Para uma verificação manual, percorra o fluxo completo. Não pare na frase de sucesso exibida por uma página. A mensagem pode indicar que o link foi processado, mas o aplicativo ainda pode estar mostrando dados antigos da sessão, ou pode não ter completado o retorno ao lugar esperado.
Siga este procedimento:
- Inicie o ambiente local com o Firebase Authentication Emulator conectado à aplicação. Confira se o aplicativo está apontando para o projeto e o emulador que você pretende testar.
- Crie uma conta de teste pela própria interface, usando um endereço controlado para essa execução. Anote o identificador apresentado pelo aplicativo ou disponível no ambiente de teste.
- Solicite a verificação pelo fluxo real do cadastro. Se o aplicativo mostra uma tela de confirmação, confira também se ela explica ao usuário o que fazer a seguir.
- Localize o link na saída do emulador. Abra o endereço gerado sem o substituir por um link de produção. Se não aparecer, investigue a conexão com o emulador e a chamada de envio antes de concluir que o recebimento falhou.
- Abra o link no navegador e verifique o resultado da ação. Teste também o retorno ao aplicativo caso o link contenha uma URL de continuação.
- Volte à aplicação e atualize o estado do usuário. Confirme que a interface deixou de tratar a conta como não verificada.
- Repita a verificação em uma nova conta de teste quando precisar testar um cadastro limpo. Depois, remova ou reinicialize os dados de teste conforme o procedimento da equipe.
Uma forma de detectar um falso positivo é comparar duas evidências: o resultado da página de ação e o estado que o aplicativo lê. Se apenas a primeira estiver correta, a experiência ainda não está aprovada. O SDK do Firebase expõe a operação reload para atualizar os dados do usuário e a propriedade emailVerified para consultar o estado. Confira a referência oficial do SDK JavaScript, incluindo a operação applyActionCode.
Na automação, use o código da execução atual
Para testes automatizados, você não precisa depender da busca manual no terminal. O Firebase documenta um endpoint próprio do emulador para consultar códigos de ação OOB pendentes. A referência REST de Authentication é a fonte para conferir o caminho do endpoint e os campos retornados; valide-os na documentação antes de adaptar um script, pois não é seguro inferir o formato de uma resposta a partir de outra configuração.
Um teste robusto liga o código OOB ao usuário que acabou de criar. O endereço sozinho não é uma chave suficiente se execuções puderem criar usuários com o mesmo endereço, ou se os dados do emulador sobreviverem entre testes. Na prática, a automação deve:
- Criar ou identificar o usuário de teste da execução.
- Solicitar a verificação por meio do aplicativo.
- Consultar o endpoint do emulador e localizar a ação correspondente ao endereço e ao tipo de operação esperados.
- Extrair o código OOB retornado e entregá-lo ao fluxo que o aplicativo usa para processar a ação.
- Aplicar o código e recarregar o usuário.
- Validar que o usuário correto agora aparece como verificado.
- Limpar a conta ou os dados do emulador ao final, inclusive quando o teste falha.
O exemplo abaixo mostra a sequência da validação no SDK, sem fixar um endereço de endpoint ou presumir o formato de resposta do emulador. codigoOob deve vir da consulta documentada para a execução atual; usuario deve ser o usuário criado ou identificado pelo próprio teste.
import { applyActionCode, reload } from "firebase/auth";
await applyActionCode(auth, codigoOob);
await reload(usuario);
if (!usuario.emailVerified) {
throw new Error("A conta ainda não aparece como verificada");
}
O applyActionCode aplica a operação associada ao código. O reload atualiza os dados do usuário que já está no contexto do teste. Essa combinação permite testar uma propriedade relevante para o aplicativo, em vez de deduzir que a conta foi verificada apenas porque um endpoint ou uma página respondeu sem erro. Confira o comportamento e a assinatura das funções na referência do SDK para Authentication.
A limpeza é parte da validade do teste, não apenas uma tarefa de organização. Se códigos antigos ou usuários de execuções anteriores continuarem no ambiente, o teste pode consumir a ação errada ou passar por coincidência. Em CI, prefira um ambiente de emulador isolado por execução ou um processo de inicialização que remova os dados anteriores. Registre falhas com o identificador do teste e o usuário associado; evite despejar dados pessoais ou códigos de ação em logs compartilhados.
A página de ação personalizada exige validação própria
Se você criou uma página personalizada para processar links de e-mail, valide o tratamento do endereço e os estados de erro além do fluxo padrão. A documentação oficial para páginas personalizadas de ação de e-mail descreve o uso das informações da ação. Em geral, a página precisa interpretar o modo da operação e o código recebido, aplicar a ação apropriada e tratar o endereço de continuação conforme a política do seu aplicativo.
Teste estas condições de forma separada:
- Um código válido para verificação completa a operação e apresenta uma confirmação compreensível.
- Um código inválido ou já consumido gera uma mensagem que explica o problema sem expor detalhes internos.
- Um código expirado é tratado como falha recuperável; informe ao usuário como solicitar um novo link, se o produto oferecer essa opção.
- Uma URL de continuação permitida leva ao destino esperado, sem ignorar as regras de domínio configuradas.
- Uma URL ausente ou inesperada não deixa o usuário numa página em branco nem o redireciona para um destino não confiável.
A página também deve lidar com a experiência de retorno. Se a mensagem foi aberta em outro dispositivo ou navegador, não presuma que a sessão original ainda esteja disponível. A orientação do Firebase sobre passagem de estado em ações de e-mail ajuda a conferir como associar o fluxo ao estado que o seu aplicativo precisa preservar.
A tabela resume critérios de aprovação por ambiente. Use-a para impedir que o resultado local seja descrito como uma validação de entrega real.
| Ambiente | Critério principal de aprovação | O que não fica comprovado |
|---|---|---|
| Local e CI/CD | O código OOB da execução atual é aplicado e o usuário associado apresenta emailVerified atualizado |
Entrega em uma caixa de entrada real |
| Pré-lançamento | A mensagem chega ao endereço de teste, o link abre o destino esperado e o aplicativo reflete a verificação | Comportamento de todas as caixas de entrada ou de todos os destinatários |
| Página de ação personalizada | Códigos válidos, inválidos e expirados geram estados claros; a continuação respeita as regras do aplicativo | A entrega real, se o teste usar apenas um link emitido pelo emulador |
No pré-lançamento, verifique o caminho real
O emulador não substitui o teste de entrega. No pré-lançamento, use um endereço de teste dedicado que você possa consultar e siga a mensagem recebida como faria um usuário. Isso permite encontrar problemas que uma simulação local não alcança: configuração do envio, aceitação da mensagem, conteúdo do link, acesso ao domínio e retorno ao aplicativo.
Confirme cada etapa por evidências distintas. Primeiro, observe se a mensagem foi recebida. Depois, confira se o link aponta para o domínio e o fluxo de pré-lançamento corretos. Por fim, abra o link e confirme que o usuário da conta correspondente aparece como verificado na aplicação. Se a mensagem não chegar, não marque a falha como “link inválido”: o processamento nem foi exercitado. Se o link abrir, mas o estado não mudar, investigue o código de ação, a sessão e a atualização dos dados do usuário.
Não use uma conta importante como endereço padrão de QA. Uma caixa de trabalho pode receber mensagens repetidas, misturar dados de teste e notificar colegas. Também evite incluir dados pessoais de usuários reais nas contas criadas para o pré-lançamento. Para escolher um endereço com base na exposição de dados e no uso pretendido, consulte o comparativo de privacidade de endereços temporários.
Um endereço temporário pode ser útil se você precisa receber uma mensagem de verificação durante uma validação isolada. Mas não presuma que todo serviço aceitará qualquer endereço, nem que um endereço temporário é adequado para uma conta que precisa ser recuperada no futuro. Para contas críticas, pagamentos, serviços governamentais ou qualquer fluxo que exija correspondência duradoura, prefira um endereço sob seu controle por longo prazo. Se a equipe precisa separar mensagens sem abandonar uma caixa principal, avalie também uma estratégia de encaminhamento de e-mails e confirme que ela atende às políticas do seu ambiente.
Perguntas frequentes sobre testes locais e reais
O emulador envia a mensagem para um e-mail real?
Não é isso que o fluxo local comprova. O emulador disponibiliza o link de ação na saída do processo, então você pode concluir a validação sem consultar uma caixa externa. Essa abordagem é adequada para testar a lógica do aplicativo. Para testar entrega, remetente e recebimento, faça um teste separado no pré-lançamento com um endereço dedicado.
Como encontro o link de verificação no teste local?
Solicite a verificação pelo aplicativo conectado ao Firebase Authentication Emulator e procure o link na saída do emulador. Em uma automação, consulte os códigos OOB pendentes pela interface REST documentada para o emulador. Associe o resultado à conta e à execução atuais; não reutilize um código antigo nem suponha que a resposta sempre terá campos idênticos sem consultar a referência oficial.
Como confirmo que o usuário está verificado depois de abrir o link?
A página que processa o link não basta como evidência. Aplique o código OOB com a operação adequada do SDK, atualize os dados do usuário com reload e confira emailVerified. Faça a leitura no usuário correspondente ao teste. Se a aplicação usa estado em cache, valide também se a interface atualiza ou se exige que o usuário recarregue a sessão.
Como saber se o Firebase Auth entregará a mensagem antes da publicação?
Faça uma validação no pré-lançamento com um endereço que você possa consultar. Confirme o recebimento, abra o link real, verifique o destino e confira o estado da conta na aplicação. Um teste local bem-sucedido não confirma a entrega por um serviço de e-mail externo. Também não garante que a mensagem será aceita por todas as caixas de entrada.
Use a evidência certa para cada ambiente
Para desenvolvimento local e CI/CD, priorize o Firebase Authentication Emulator, o código OOB da execução atual e o estado atualizado da conta. Para o pré-lançamento, acrescente uma caixa de entrada de teste e valide recebimento, destino do link e retorno à aplicação. Essa separação reduz dependências externas durante os testes automatizados sem deixar a entrega real fora do plano de lançamento.
Se a sua etapa de pré-lançamento exige receber uma mensagem sem expor seu endereço principal, o tmp10 pode servir como opção de caixa de entrada temporária, sem cadastro e pronta para uso. Use-o apenas para o teste que você consegue concluir com um endereço temporário; não substitua por ele uma conta que precisará de recuperação ou correspondência duradoura. Acesse o tmp10 quando precisar verificar esse recebimento real, mantendo o teste local do emulador independente dessa etapa.
Perguntas frequentes
O Firebase Authentication Emulator envia a mensagem de verificação para uma caixa de entrada real?
Não conte com isso. No fluxo do emulador, o link de verificação fica disponível na saída do processo, em vez de depender da entrega por um serviço de e-mail real. Isso permite validar a lógica de autenticação localmente, mas não demonstra que o provedor de e-mail, o domínio do remetente ou a caixa de entrada de um usuário real estão funcionando.
Como encontro o link de verificação de e-mail durante um teste local?
Depois de criar o usuário e solicitar o envio da verificação, examine a saída do Firebase Authentication Emulator. O link de ação aparece ali para você abrir manualmente. Em testes automatizados, a documentação também descreve a consulta aos códigos OOB pelo endpoint do emulador; associe o código ao usuário criado naquela execução, não a um endereço ou código reaproveitado.
Como confirmo que o e-mail do usuário foi marcado como verificado?
Não se limite à página que informa que a operação terminou. Depois de aplicar o código de ação, atualize os dados do usuário com a API do SDK e confira a propriedade emailVerified. Essa verificação testa o estado que o aplicativo realmente consulta e ajuda a detectar casos em que o link abriu, mas a interface não atualizou a sessão ou a tela.
Como testo a entrega real da verificação antes de publicar?
Use um endereço dedicado que você possa consultar e acesse a mensagem recebida fora do emulador. Confira se a mensagem chegou, se o link abre o domínio e o fluxo esperados e se, depois da ação, o aplicativo reconhece a conta como verificada. Essa etapa cobre o serviço de envio e a navegação real, que um link emitido localmente não consegue comprovar.