Por Victor Oliveira - QA Senior com mais de 13 anos de experiencia

O Playwright e uma ferramenta de automacao de testes open-source desenvolvida pela Microsoft, projetada para testes de ponta a ponta (E2E) em aplicacoes web modernas. Com suporte nativo a Chromium, Firefox e WebKit, o Playwright permite que voce escreva testes que rodam em varios navegadores com uma unica API. Neste tutorial, voce vai aprender como configurar um projeto do zero, desde a instalacao ate a execucao do primeiro teste.

1. O que e Playwright?

Playwright foi lancado em 2020 pela Microsoft e rapidamente se tornou uma das ferramentas mais adotadas para automacao de testes web. Diferente do Selenium, que usa o WebDriver como ponte entre o codigo e o navegador, o Playwright se comunica diretamente com o navegador via o protocolo CDP (Chrome DevTools Protocol), o que traz mais velocidade e confiabilidade.

Principais vantagens:

  • Multi-navegador nativo — Chromium, Firefox e WebKit em uma unica API
  • Auto-wait inteligente — espera automatica por elementos antes de interagir, reduzindo testes flaky
  • Interceptacao de rede — controle sobre requisicoes e respostas HTTP
  • Mobile emulation — emula dispositivos moveis como iPhone e Android
  • Codegen — gravador de testes que gera codigo enquanto voce navega
  • Trace Viewer — depuracao visual passo a passo dos testes
  • Suporte a multiplas linguagens — JavaScript, TypeScript, Python, Java e .NET

2. Pre-requisitos

Antes de comecar, voce precisa ter instalado:

  • Node.js 18+ — nodejs.org
  • npm — ja vem com Node.js
  • Git (opcional, mas recomendado) — para versionamento
  • VS Code (ou qualquer editor de sua preferencia)

Verifique se o Node.js esta instalado corretamente:

node --version
npm --version

3. Instalacao do Playwright

Existem duas formas de comecar um projeto com Playwright: usando o comando init ou manualmente.

3.1. Via npm init (recomendado)

No terminal, execute:

npm init playwright@latest

O assistente vai perguntar:

  • Onde colocar os testes? — Padrao: tests/
  • Adicionar exemplo? — Sim, para ver a estrutura
  • Usar TypeScript ou JavaScript? — Escolha TypeScript para projetos maiores
  • Instalar navegadores? — Sim (Chromium, Firefox, WebKit)
  • Instalar GitHub Actions? — Opcional, para CI/CD

3.2. Instalacao manual

Se preferir comecar manualmente:

mkdir meu-projeto-playwright
cd meu-projeto-playwright
npm init -y
npm install --save-dev @playwright/test
npx playwright install

O comando npx playwright install baixa os navegadores necessarios (Chromium, Firefox e WebKit).

Verifique a instalacao:

npx playwright --version

4. Estrutura de Diretorios

Apos a instalacao, a estrutura recomendada do projeto e:

meu-projeto-playwright/
├── tests/
│   ├── example.spec.ts
│   └── login.spec.ts
├── playwright.config.ts
├── package.json
└── node_modules/
  • tests/ — arquivos de teste com extensao .spec.ts ou .spec.js
  • playwright.config.ts — configuracao central do Playwright
  • package.json — dependencias e scripts do projeto

5. Criando o Primeiro Teste

Crie o arquivo tests/primeiro_teste.spec.ts:

import { test, expect } from '@playwright/test';

test('deve acessar o Google e verificar o titulo', async ({ page }) => {
    await page.goto('https://google.com');
    const titulo = await page.title();
    expect(titulo).toBe('Google');
});

Vamos entender cada parte:

  • test() — define um caso de teste com nome descritivo
  • expect() — funcao de assertiva do Playwright
  • page.goto() — navega para uma URL
  • page.title() — retorna o titulo da pagina
  • { page } — fixture do Playwright que fornece uma pagina limpa para cada teste

5.1. Teste com interacao

Vamos criar um teste mais completo que interage com elementos na pagina:

import { test, expect } from '@playwright/test';

test('deve fazer login com sucesso', async ({ page }) => {
    await page.goto('https://example.com/login');
    
    // Preenche os campos
    await page.fill('#username', 'admin');
    await page.fill('#password', 'senha123');
    
    // Clica no botao de login
    await page.click('button[type="submit"]');
    
    // Verifica se o login foi bem-sucedido
    await expect(page.locator('.welcome-message')).toHaveText('Bem-vindo, admin!');
});

6. Localizadores Modernos

Uma das grandes vantagens do Playwright sao os localizadores modernos, que tornam os testes mais legiveis e resilientes. Evite usar XPath ou CSS complexos — prefira localizadores por funcao:

// Rolagem por funcao (role) — RECOMENDADO
await page.getByRole('button', { name: 'Enviar' }).click();

// Por texto
await page.getByText('Bem-vindo').click();

// Por placeholder
await page.getByPlaceholder('Digite seu email').fill('teste@email.com');

// Por label
await page.getByLabel('Nome completo').fill('Victor Oliveira');

// Por test id (data-testid)
await page.getByTestId('submit-button').click();

// Por titulo
await page.getByTitle('Fechar').click();

// Por alt text (imagens)
await page.getByAltText('Logo da empresa').click();

Os localizadores do Playwright sao auto-waiting: eles esperam automaticamente o elemento estar visivel e habilitado antes de interagir.

7. Assertivas (Assertions)

O Playwright oferece assertivas poderosas que tambem aguardam automaticamente a condicao:

import { expect } from '@playwright/test';

// Assertivas basicas
expect(page.locator('.titulo')).toHaveText('Bem-vindo');
expect(page.locator('.erro')).toBeVisible();
expect(page.locator('.spinner')).toBeHidden();
expect(page.locator('#campo')).toBeDisabled();
expect(page.locator('#campo')).toBeEnabled();
expect(page.locator('.checkbox')).toBeChecked();

// Assertivas de URL
expect(page).toHaveURL('https://example.com/dashboard');

// Assertivas de screenshot (teste visual)
expect(page).toHaveScreenshot('homepage.png');

// Soft assertions — nao interrompem o teste
await expect.soft(page.locator('.aviso')).toBeVisible();
await page.getByRole('button', { name: 'Continuar' }).click();

// Assertiva de valor de input
expect(page.locator('#email')).toHaveValue('teste@email.com');

// Assertiva de contagem de elementos
expect(page.locator('.item-lista')).toHaveCount(5);

8. Executando os Testes

Com o teste criado, execute no terminal:

npx playwright test

O Playwright vai executar todos os arquivos *.spec.* dentro da pasta de testes configurada.

8.1. Modos de execucao

# Executar em modo headed (com navegador visivel)
npx playwright test --headed

# Executar um arquivo especifico
npx playwright test tests/login.spec.ts

# Executar por nome do teste
npx playwright test -g "login"

# Executar em um navegador especifico
npx playwright test --project=chromium

# Executar em modo debug (com Paused)
npx playwright test --debug

# Executar com rastreamento (trace)
npx playwright test --trace on

8.2. Relatorios

O Playwright gera relatorios em HTML automaticamente:

npx playwright show-report

Isso abre um servidor local com o relatorio detalhado, mostrando:

  • Testes que passaram/falharam
  • Tempo de execucao
  • Traces passo a passo com screenshots
  • Erros e stack traces

8.3. Configuracao no playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
    testDir: './tests',
    timeout: 30000,
    retries: 1,
    use: {
        headless: true,
        viewport: { width: 1280, height: 720 },
        screenshot: 'only-on-failure',
    },
    projects: [
        { name: 'chromium', use: { browserName: 'chromium' } },
        { name: 'firefox', use: { browserName: 'firefox' } },
        { name: 'webkit', use: { browserName: 'webkit' } },
    ],
});

9. Codegen: Gravador de Testes

O Playwright inclui uma ferramenta chamada Codegen que grava suas acoes no navegador e gera o codigo automaticamente:

npx playwright codegen https://example.com

Isso abre duas janelas:

  • O navegador para voce navegar
  • O painel do Codegen gerando o codigo em tempo real

Use o Codegen para:

  • Aprender localizadores otimos
  • Gerar esqueleto de testes rapidamente
  • Explorar paginas complexas

10. Trace Viewer: Depuracao Visual

O Trace Viewer permite debug visual dos testes:

npx playwright show-trace trace.zip

Com ele, voce pode:

  • Ver cada passo do teste com screenshots
  • Inspecionar o estado do DOM em cada acao
  • Ver logs de console e requisicoes de rede
  • Identificar exatamente onde um teste falhou

11. Dicas e Boas Praticas

  • Use data-testid — localizadores por atributo data-testid sao os mais resilientes
  • Prefira getByRole — alem de resilientes, promovem acessibilidade
  • Evite page.waitForTimeout() — use auto-waiting do Playwright em vez de waits fixos
  • Use test.describe() — agrupe testes relacionados para melhor organizacao
  • Paralelize testes — o Playwright executa testes em paralelo por padrao
  • Mantenha dados de teste via API — use API calls no beforeEach para configurar estado
  • Teste em mobile tambem — use a emulacao de dispositivos do Playwright
import { test, expect, devices } from '@playwright/test';

test.use(devices['iPhone 13']);

test('deve funcionar em mobile', async ({ page }) => {
    await page.goto('https://example.com');
    await expect(page.locator('.menu-mobile')).toBeVisible();
});

12. Proximos Passos

Agora que voce ja sabe iniciar um projeto com Playwright, explore estes topicos:

  • API Testing — Playwright possui cliente HTTP nativo para testar APIs
  • Network Interception — mocke requisicoes e respostas para testar cenarios offline
  • Visual Regression — compare screenshots automaticamente
  • Component Testing — teste componentes isolados (experimental)
  • CI/CD com GitHub Actions — integre seus testes no pipeline
  • Playwright com Docker — ambientes isolados para execucao em CI

Continue acompanhando o QA Overflow para mais tutoriais praticos sobre automacao de testes!