Como adicionar testes do Playwright à CI do seu pull request com GitHub Actions

Se você é como eu, provavelmente valoriza muito uma etapa de testes automatizados na CI do seu pull request (PR), pois ela traz mais segurança antes de mesclar o código. Vou mostrar como adicionar testes do Playwright aos seus PRs e integrar tudo em um fluxo de trabalho de CI com GitHub Actions.

Se você ainda não conhece o Playwright, o framework de automação de testes Playwright teve sua primeira versão lançada em 2017, mas ganhou popularidade recentemente como mais uma ferramenta para desenvolvedores da Microsoft, além do Visual Studio Code e de outras.

O framework de automação de testes Playwright é uma ótima opção para escrever testes de ponta a ponta (E2E) com facilidade e também verificar a compatibilidade entre navegadores. Já usei Selenium e Cypress e, se você teve experiências parecidas, o Playwright certamente vai lembrar o segundo. É fácil começar, escrever testes e conta com mecanismos integrados para evitar testes instáveis.

Neste artigo, você vai aprender:

• O básico sobre como escrever testes de ponta a ponta com Playwright

• Como executar testes do Playwright na CI do GitHub Actions

• Como executar testes do Playwright nas URLs de preview do Netlify após o deploy

• Como preservar rastros de depuração do Playwright e disponibilizá-los como artefatos de build na CI do GitHub Actions

Uma observação antes de começar: este tutorial sobre Playwright é focado em JavaScript, mas você pode aplicá-lo facilmente a outros projetos, como um projeto em Python com Playwright. O foco é ensinar a integração com a CI, não a escrever testes avançados com Playwright. Se você desenvolve em Java, há também um SDK do Playwright para Java.

Adicione o Playwright ao projeto e faça testes

Vamos adicionar o Playwright a um projeto JavaScript existente. Para isso, precisamos:

1. Instalar o pacote npm do Playwright: npm install @playwright/test --dev

2. Adicionar um hook do ciclo de vida do npm específico para os testes de ponta a ponta do Playwright

As alterações serão refletidas no arquivo package.json, que deve ficar mais ou menos como o trecho de código a seguir, junto com o restante do conteúdo e da configuração do manifesto do pacote:

1  “scripts”: {
2    "test:e2e": "playwright test"
3  },
4
5  "devDependencies": {
6    "@playwright/test": "^1.22.2",
7   }

Em seguida, podemos criar um novo arquivo de teste do Playwright neste local: ./e2e/home.spec.ts. Vamos criar um novo diretório e2e/ na raiz do projeto, caso ele ainda não exista.

Adicione o trecho de código a seguir como um exemplo simplificado de teste de ponta a ponta com Playwright. Ele configura um caso de teste que acessa a URL http://localhost:3000 e verifica se o título do site (geralmente definido pela entidade HTML <title>) corresponde à string Dogs security blog. Exemplo com Playwright:

1import { test, expect } from '@playwright/test';
2
3test('page should have title of "Dogs security blog"', async ({ page }) => {
4  await page.goto('http://localhost:3000/');
5  const title = await page.title();
6  expect(title).toBe(“Dogs security blog”);
7});

Se esta é a primeira vez que você adiciona automação com Playwright à sua stack, a configuração de package.json e o trecho de código para ./e2e/home.spec.ts acima devem ser suficientes para começar com um exemplo funcional do Playwright.

Verifique se o servidor ou aplicativo web está em execução e aceitando requisições. Em seguida, execute o comando npm run test:e2e para confirmar que os testes do Playwright podem ser executados e concluídos com sucesso.

A saída dos testes do Playwright deve ser parecida com esta:

1npm run test:e2e
2
3> the-snyk-blog@0.1.0 test:e2e
4> playwright test
5
6Running 1 test using 1 worker
7
8  ✓  e2e/home.spec.ts:3:1 › page should have title of "Dogs security blog" (4s)
9
10  1 passed (14s)

Uhu! Temos um teste funcional com Playwright!

Automação com Playwright e GitHub Actions

Agora, vamos configurar a integração contínua (CI) para que, quando novas contribuições de código forem feitas ao projeto, por nós ou por colaboradores externos, os testes sejam executados. Assim, teremos mais confiança de que as contribuições não vão comprometer as funcionalidades existentes.

Se você gerencia seus projetos no GitHub, é muito fácil usar o GitHub Actions como fluxo de trabalho de CI/CD, pois ele já faz parte da plataforma. Vamos configurar tudo para que novas contribuições de código feitas por meio de PRs acionem nosso fluxo de testes do Playwright e executem um pipeline de CI de ponta a ponta.

Primeiro, vamos configurar o Playwright com uma configuração predefinida que o instrui a executar um comando em segundo plano para iniciar nosso servidor. Assim, podemos manter a URL na configuração, em vez de defini-la diretamente no código dos testes do Playwright, como fizemos antes.

Adicione o conteúdo a seguir a um novo arquivo chamado playwright.config.ts, na pasta raiz do seu projeto JavaScript (onde está o arquivo package.json):

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4  webServer: {
5    command: 'npm run start',
6    url: 'http://localhost:3000',
7  },
8};
9
10export default config;

Se o servidor web local usar outra porta, ajuste a configuração url acima para refletir essa alteração e garantir que o Playwright possa acessá-lo no ambiente de CI.

Além disso, dependendo de como seu projeto é compilado, talvez seja necessário atualizar o hook start do ciclo de vida do npm em package.json para algo como o exemplo a seguir, que executa npm run build antes de iniciar o servidor:

1    "start": "npm run build && next start",

Em seguida, podemos criar um fluxo de trabalho do GitHub Actions para o Playwright.

Adicione o conteúdo a seguir a um novo arquivo neste caminho: .github/workflows/e2e-ci.yml:

1name: "Tests: E2E"
2on: [pull_request]
3jobs:
4  tests_e2e:
5    name: Run end-to-end tests
6    runs-on: ubuntu-latest
7    steps:
8      - uses: actions/checkout@v3
9      - uses: actions/setup-node@v3
10      - name: install dependencies
11        run: npm ci
12      - name: install playwright browsers
13        run: npx playwright install --with-deps
14      - name: npm run test:e2e
15        run: npm run test:e2e=

Pronto!

Abra um PR no seu repositório do GitHub e confirme que o fluxo de trabalho tests_e2e é executado como esperado e que todos os testes são aprovados.

Talvez você tenha visto tutoriais ou artigos sobre Playwright que mencionam o repositório de GitHub Actions do Playwright (https://github.com/microsoft/playwright-github-action) ou fazem referência direta à action microsoft/playwright-github-action@v1. Esses recursos não são mais necessários: a GitHub Action oficial foi descontinuada. Em vez disso, instale e use a CLI do playwright, como fizemos acima com o npm.

Como executar testes do Playwright nas URLs de preview do Netlify após o deploy

Se você usa o Netlify para compilar seu projeto frontend e fazer deploy da build do lado do cliente em um site ativo, uma vantagem adicional são os Netlify Previews, que se integram aos seus PRs. Sempre que um pull request é criado ou atualizado, o Netlify faz o deploy do projeto em uma URL para que você possa inspecionar visualmente e interagir com o estado e a qualidade da build frontend desse PR.

Uma integração nativa com o GitHub usando o bot do Netlify é mais ou menos assim:

Para executar nosso teste do Playwright em uma URL de preview do Netlify, precisamos:

1. Atualizar a URL base configurável do Playwright para que possamos defini-la dinamicamente ou voltar ao padrão localhost:3000 para executar um teste local do Playwright (no ambiente de desenvolvimento ou na CI).

2. Extrair o número do PR, que é como o Netlify identifica e cria uma URL exclusiva para a build frontend.

3. Aguardar a URL de preview do Netlify ficar disponível.

4. Executar nosso teste de ponta a ponta do Playwright na URL de preview do Netlify.

Vamos começar atualizando o arquivo de configuração do Playwright:

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4    use: {
5        baseURL: process.env.PLAYWRIGHT_TEST_BASE_URL || 'http://localhost:3000'
6    },
7    webServer: {
8        command: "npm run start"
9    }
10};
11
12export default config;

Com essa configuração, podemos definir dinamicamente a variável de ambiente PLAYWRIGHT_TEST_BASE_URL no nosso ambiente ou na CI.

Em seguida, também precisamos atualizar o próprio caso de teste do Playwright para remover a URL fixa e usar a baseURL definida no arquivo de configuração acima. Atualize o arquivo de teste ./e2e/home.spec.ts da seguinte forma:

1import { test, expect } from '@playwright/test';
2
3test('page should have title of "Dogs security blog"', async ({page, baseURL}) => {
4  await page.goto(baseURL);
5  const title = await page.title();
6  expect(title).toBe(“Dogs security blog”);
7});

Por fim, atualize o arquivo .github/workflows/e2e-ci.yml com duas novas etapas: uma que usa uma GitHub Action para aguardar a disponibilidade da URL de deploy e outra para executar os testes nela. O trecho de código a seguir mostra o arquivo de fluxo de trabalho completo:

1name: "Tests: E2E"
2
3on: [pull_request]
4
5env:
6  GITHUB_PR_NUMBER: ${{github.event.pull_request.number}}
7
8jobs:
9  tests_e2e:
10    name: Run end-to-end tests
11    runs-on: ubuntu-latest
12    steps:
13      - uses: actions/checkout@v3
14      - uses: actions/setup-node@v3
15      - name: install dependencies
16        run: npm ci
17      - name: install playwright browsers
18        run: npx playwright install --with-deps
19      - name: npm run test:e2e
20        run: npm run test:e2e
21
22  tests_e2e_netlify_prepare:
23    name: Wait for deployment on Netlify
24    runs-on: ubuntu-latest
25    steps:
26      - name: Waiting for Netlify Preview
27        uses: josephduffy/wait-for-netlify-action@v1
28        id: wait-for-netflify-preview
29        with:
30          site_name: "pull-request"
31          max_timeout: 180
32
33  tests_e2e_netlify:
34    needs: tests_e2e_netlify_prepare
35    name: Run end-to-end tests on Netlify PR preview
36    runs-on: ubuntu-latest
37    timeout-minutes: 5
38    steps:
39      - uses: actions/checkout@v3
40      - uses: actions/setup-node@v3
41      - name: install dependencies
42        run: npm ci
43      - name: install playwright browsers
44        run: npx playwright install --with-deps
45      - name: npm run test:e2e
46        run: npm run test:e2e
47        env:
48          PLAYWRIGHT_TEST_BASE_URL: "https://deploy-preview-${{env.GITHUB_PR_NUMBER}}--pull-request.netlify.app/"
49          DEBUG: pw:api

Observe que a segunda etapa, identificada como tests_e2e_netlify_prepare, pode ser configurada com o tempo limite que você preferir. Neste caso, defini 3 minutos.

A terceira etapa, identificada como tests_e2e_netlify, é parecida com o teste do Playwright executado localmente (que mantivemos como primeira etapa deste fluxo de trabalho), mas inclui uma configuração extra: a variável de ambiente PLAYWRIGHT_TEST_BASE_URL, definida e formatada dinamicamente para corresponder à URL de preview do Netlify esperada.

Também ativei explicitamente os recursos de depuração do Playwright para gerar uma saída mais detalhada, adicionando DEBUG: pw:api como uma nova variável de ambiente à última etapa do fluxo de trabalho.

Abra um novo PR e verifique se o fluxo de trabalho dos testes de ponta a ponta é concluído com sucesso:

Parabéns! Você criou com sucesso uma automação robusta de testes de ponta a ponta com Playwright, muito bem integrada à CI do seu projeto com GitHub Actions.

Como adicionar a depuração do Playwright à CI

O Playwright facilita a depuração de testes com vários recursos integrados. Para começar, ele oferece o Playwright Inspector, uma interface gráfica que permite inspecionar elementos HTML e depurar passo a passo os casos de teste do Playwright. Outro recurso integrado é o Playwright Trace Viewer, que permite reproduzir um teste gravado.

O Playwright Trace Viewer é especialmente útil quando você enfrenta testes instáveis, ou seja, não determinísticos e difíceis de reproduzir. Quando esse tipo de problema surgir nos seus testes de ponta a ponta, você pode ativar um recurso de depuração do Playwright que registra todas as interações e as salva em um arquivo. Depois, basta carregar o arquivo no Playwright Trace Viewer para investigar por que o teste falhou.

Vamos continuar de onde paramos e configurar o fluxo de trabalho de CI para ativar o rastreamento do Playwright, permitindo acessar esses arquivos mais tarde.

Podemos usar a GitHub Action oficial actions/upload-artifact para preservar arquivos ou o conteúdo de diretórios das builds e salvá-los como artefatos. Mas atenção: não use essa técnica para salvar arquivos de log ou outros dados que possam conter informações confidenciais, pois eles ficam disponíveis publicamente para qualquer pessoa.

Vamos adicionar a etapa a seguir aos testes locais de ponta a ponta existentes, identificados pelo ID do job tests_e2e:

1      - name: Upload test results
2        if: always()
3        uses: actions/upload-artifact@v2
4        with:
5          name: playwright-report
6          path: test-results

Você pode adicionar essa etapa a outras etapas de depuração do Playwright em outros fluxos de trabalho de CI, como o teste da URL de preview do Netlify.

Em seguida, atualize o arquivo .gitignore para garantir que esses arquivos de rastreamento não sejam enviados ao repositório. Para isso, adicione o seguinte ao arquivo:

1test-results/

Por fim, atualize o arquivo de configuração do Playwright playwright.config.ts para ativar o rastreamento. Com a alteração, ele deve ficar assim:

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4  webServer: {
5    command: 'npm run start'
6  },
7  use: {
8    trace: 'on',
9  },
10};
11
12export default config;

Pronto. Mas talvez você esteja se perguntando onde encontrar o artefato de depuração.

Os artefatos de CI podem ser acessados na guia Summary de uma execução do GitHub Actions. Na captura de tela a seguir, você pode ver o artefato na parte inferior de um job que foi concluído com sucesso na minha CI:

Vale destacar que estamos gerando o arquivo de rastreamento de depuração do Playwright em todas as builds, independentemente de terem sido concluídas com sucesso. Configuramos a CI para fazer isso usando a diretiva if: always() na etapa acima, identificada como o job tests_e2e.

Para visualizar o arquivo de rastreamento, você pode baixar o artefato, extraí-lo para uma pasta local e encontrar as informações de depuração do Playwright dentro dele, em um arquivo compactado. Você pode executá-lo facilmente com a própria CLI do Playwright:

1npx playwright show-trace <my-directory>/my-trace.zip

Playwright vs. Cypress

Se você já usou o Cypress, a ferramenta de automação Playwright vai parecer muito familiar, seja pela CLI, pela interface gráfica ao vivo para inspecionar e depurar testes ou pela forma como a linguagem funciona.

Como o Playwright funciona?

Ao contrário do Cypress, outra ferramenta de automação de testes que se injeta como uma biblioteca no DOM da página web para controlar o navegador, o Playwright usa APIs nativas do navegador para controlar a automação. Por exemplo, ele usa o CDP do Chrome como protocolo de depuração remota para se comunicar com um navegador Chrome. Além disso, o Playwright é compatível com todos os principais navegadores, como Chrome, Firefox, Edge e WebKit, e oferece recursos semelhantes aos do Cypress, como resiliência de testes, que aguarda automaticamente elementos e ações e evita testes instáveis.

O que é automação com Playwright?

O Playwright é um projeto de código aberto da Microsoft que oferece uma estrutura de testes de ponta a ponta com suporte a vários navegadores. Ele usa APIs da estrutura nativa de automação do navegador para controlá-lo e interagir com ele, além de disponibilizar SDKs para a API do Playwright em várias linguagens de programação. Seus diferenciais, além de ser de código aberto e gratuito, são a resiliência (que reduz a instabilidade dos testes), a automação completa do navegador, o rastreamento e a depuração.

Continue aprendendo sobre automação de testes com Playwright

Se você gostou deste artigo e quer ampliar seus conhecimentos sobre Playwright, recomendo os seguintes recursos:

• A documentação do Playwright em https://playwright.dev é excelente. Ela tem seções específicas, como depuração com Playwright, e apresenta exemplos de Playwright para ajudar quem está começando com essa estrutura de testes a dar os primeiros passos rapidamente.

• Para acompanhar notícias, tutoriais e outros conteúdos para desenvolvedores sobre Playwright, recomendo seguir Debbie O'Brien no Twitter. Ela é gerente de programas do Playwright na Microsoft e costuma falar sobre a ferramenta em eventos.

Recursos adicionais

• Como criar um pipeline de CI/CD seguro com GitHub Actions

• 10 práticas recomendadas de segurança do GitHub

• Testes de segurança de aplicações

• Adicione segurança aos fluxos de trabalho do GitHub com a Snyk