Como ler e-mails do Gmail com o Playwright

Olá pessoal!

Ler e-mails em testes automatizados é um truque que você talvez precise saber fazer em muitos projetos. Veja por que e como lidar com isso…

Por que isso é importante?

Bem, se o sistema envia e-mails - você pode querer verificar se eles estão sendo enviados e se o conteúdo está correto, incluindo links clicáveis.

Então, estes são os cenários usuais quando você precisa disso:

1. Inscrever-se.

   Muitas plataformas enviam um e-mail de confirmação assim que você cria uma conta, e você precisa clicar em um link de confirmação do e-mail.

   
   

2. Faturas.

   Se o seu aplicativo fizer algum pagamento, eles geralmente enviam um cheque ou fatura por e-mail, então você também pode querer ver se o conteúdo deles está correto.

   
   

3. Resultados.

   Como resultados de exames médicos. Na minha experiência, alguns hospitais enviam um e-mail com os resultados dos testes assim que concluídos (ou pelo menos um link para uma página pessoal onde você pode visualizar o relatório).

   
   

4. …

Claro, esta não é a lista completa – estes são apenas os casos de uso que mais conheci em minha carreira.

A falha na verificação desses cenários pode fazer com que os usuários não recebam e-mails ou recebam informações erradas nos e-mails. Em um dos projetos, isso nos ajudou a encontrar antecipadamente um token SendGrind expirado.

Quais são as complicações da leitura de e-mails em testes?

Ler e-mails é algo complicado, mas não impossível.

Os primeiros clientes de e-mail usavam POP3 para buscar e-mails do servidor, mas há um pequeno problema: ele exclui os e-mails do servidor assim que são baixados.

Mais tarde, surgiu o protocolo IMAP - ele permite que você simplesmente leia e-mails do servidor.

O problema é - alguns serviços proíbem esses protocolos ou fazer você confirmar sua identidade quando você se conecta pela primeira vez (como quando você reinicia um teste automatizado).

Por outro lado, alguns serviços como o Gmail fornecem uma API REST para manipular seus e-mails, mas há outro problema - a documentação e suas bibliotecas não são tão fáceis de usar (especialmente para quem não trabalha muito com testes de e-mail).

É aqui que entra o gmail-getter - uma biblioteca npm que permite ler e-mails e até mesmo abri-los em seu navegador se você usar ferramentas de automação de navegador como Playwright .

Lendo e-mails do Gmail com Gmail-Getter

Primeira coisa: você precisa instalar o pacote em seu projeto:

 npm install gmail-getter

Crie um projeto do Console do Google Cloud e obtenha credenciais

Para fazer login na API do Gmail, você precisa obter credenciais: um ID do cliente , um segredo do cliente e um token de atualização . Essas credenciais permitem que você obtenha um token de acesso, que é necessário em solicitações posteriores (como obter uma lista de e-mails ou um único e-mail, etc.).

Passos a seguir:

1. Crie um projeto no Console do Google Cloud .

   
   

2. Crie credenciais OAuth na seção API e serviços ( de preferência, selecione Aplicativo de desktop lá se precisar para testes automatizados ) e faça o download.

   
   

3. Ative a API do Gmail .

   
   

4. Obtenha um token de atualização.

Para obter um token de atualização - basta executar um comando na raiz do projeto:

 npx gmail-getter get-refresh-token

(ou em qualquer outro lugar se você tiver o pacote instalado globalmente)

 get-refresh-token

Você deve colocar o arquivo credentials.json em um local onde executará o comando.

⚠️ o nome do arquivo de credenciais diferencia maiúsculas de minúsculas ⚠️

Obter token de acesso

Depois de concluída a configuração, você deverá obter um token de acesso em seus testes automatizados. Eu diria que o melhor lugar para isso é uma configuração global (uma função que é executada antes do início do teste).

Então, será algo assim:

 import {getToken} from 'gmail-getter' export default async function globalSetup() { process.env['ACCESS_TOKEN'] = await getToken( process.env.CLIENT_ID!, process.env.CLIENT_SECRET!, process.env.REFRESH_TOKEN! ) }

O exemplo acima usa variáveis de ambiente, para as quais você definitivamente precisará instalar o pacote dotenv também.

Mas, se quiser manter as coisas simples - você pode usar este snippet sempre que precisar que o token esteja acessível:

 const accessToken = await getToken( '<put-your-client-id-here>', '<put-your-client-secret-here>', '<put-your-refresh-token-here>' )

Obter e-mails

No momento, a API REST do Gmail usa sua própria linguagem de consulta para encontrar o e-mail que você precisa:

 const email = await checkInbox(accessToken!, 15000, 1500, 'from:squier7 subject:Test!')

O comando acima retorna um objeto de e-mail, mas você ainda precisa obter seu conteúdo ou um link. Substituir from:squier7 subject:Test! para sua própria consulta seguindo a sintaxe do link acima ☝️

Você pode analisar um link usando um regex :

 const link = parseLinkFromHtml(email!, /(https:\/\/)(\S*)(gmail-getter)([\w\/\?\=\-]*)/im)

Substitua /(https:\/\/)(\S*)(gmail-getter)([\w\/\?\=\-]*)/im pela sua própria expressão regular ☝️

OU obtenha todo o conteúdo HTML do e-mail e renderize-o em seu navegador:

 import {getToken, parseHtml} from 'gmail-getter' import {test} from '@playwright/test' test('Render an email', async ({page}) => { const accessToken = await getToken( '<put-your-client-id-here>', '<put-your-client-secret-here>', '<put-your-refresh-token-here>' ) const email = await checkInbox(accessToken!, 15000, 1500, 'from:squier7 subject:Test!') // get an email const html = parseHtml(email!) // parse HTML from the email await page.setContent(html) // render the email in the browser })

Geral

Acho que está bastante óbvio agora que trabalhar com e-mails em testes automatizados pode ser complicado! Mas conhecer esses truques torna as coisas muito mais fáceis.

Você ainda pode usar outros serviços de e-mail ou tentar o IMAP , mas garanto que não será tão fácil quanto neste guia, pois você precisará criar seu próprio auxiliar, como o gmail-getter fornecido aqui.

Você pode encontrar o exemplo do Playwright no GitHub . Exemplo de cipreste também.