Playwright para web

Como automatizar jornadas completas no navegador com Playwright, sem esperas fixas nem seletores frágeis, e investigar falhas pelo trace.

Cerca de 16 min · Revisado em

Ao final, você vai conseguir

  • Explicar o que um teste de ponta a ponta prova e escolher quais jornadas merecem um
  • Escrever um teste Playwright com page.goto, getByRole, fill, click e expect
  • Trocar esperas fixas e seletores CSS por espera automática e localizadores orientados à pessoa usuária
  • Usar fixtures para manter cada teste isolado e independente da ordem
  • Ler a saída de npx playwright test e usar trace e relatório para separar bug do produto de teste instável

Imagine a Black Friday: o site da loja recebe milhares de compras por minuto e, depois de uma atualização na madrugada, o botão “Finalizar compra” parou de responder. Nenhum teste de função pegou, porque cada peça sozinha funcionava. Um teste de ponta a ponta abre o navegador e faz a compra inteira, como uma pessoa faria, minutos depois de cada mudança. Saber escrever esses testes sem deixá-los lentos e instáveis é o que separa uma automação que ajuda de uma que todo mundo ignora.

Um robô que usa o site como você

Um teste de ponta a ponta (em inglês, end-to-end ou E2E) abre um navegador de verdade, entra no site rodando com servidor e banco, e faz uma tarefa completa: entrar, buscar, comprar. Ele prova que as peças funcionam juntas.

O Playwright é uma ferramenta gratuita da Microsoft para escrever esses testes em TypeScript, JavaScript, Python, Java ou C#. Ele controla Chromium, Firefox e WebKit (o motor do Safari). Você já viu um gostinho dele na aula de testes de interface e usou o request dele nos testes de API.

O que acontece quando um teste de ponta a ponta calcula um frete.

  1. Teste → Navegador: abrir /carrinho. O teste manda o navegador abrir a página, como se alguém digitasse o endereço.
  2. Navegador → Site: carrega a página. O navegador baixa HTML, CSS e JavaScript do site, igual faria no seu celular.
  3. Teste → Navegador: preencher CEP e clicar. O teste encontra o campo pelo rótulo “CEP”, digita e clica no botão.
  4. Site → API: POST /frete. O código do site chama a API de verdade, que consulta o banco.
  5. API → Site: 200: R$ 8,00. A API responde, e o site mostra o valor na tela.
  6. Navegador → Teste: texto “Frete: R$ 8,00”. O teste confere o que aparece na tela. Se qualquer peça no caminho falhar, ele fica vermelho.

Essa força tem um preço: cada teste leva segundos (não milissegundos) e depende de muita coisa funcionando. Por isso a regra das trilhas de Testes e Fullstack é a mesma: regras de negócio ficam em testes de unidade e de API; o navegador fica para as jornadas críticas, as tarefas que não podem quebrar.

Sua equipe tem tempo para automatizar só um teste de ponta a ponta no app de delivery. Qual escolher?

  • A pessoa entra, escolhe um prato, paga e vê o pedido confirmado
  • O cálculo da taxa de entrega para 30 CEPs diferentes
  • A cor do botão “Pedir” em todas as telas
  • Todas as telas do app, para garantir que nada passe

Anatomia de um teste Playwright

Todo teste Playwright tem as mesmas peças: um nome que descreve a tarefa, a navegação até a página, ações sobre elementos e conferências no final. Explore cada parte abaixo.

O arquivo tests/frete.spec.ts. O sufixo .spec.ts é o jeito de o Playwright achar os testes.

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

test('calcula o frete para um CEP válido', async ({ page }) => {
  await page.goto('/carrinho');
  await page.getByLabel('CEP').fill('01310-100');
  await page.getByRole('button', { name: 'Calcular frete' }).click();

  await expect(page.getByRole('status')).toHaveText('Frete: R$ 8,00');
  await expect(page.getByText('Entrega amanhã')).toBeVisible();
});
  • Importação: test cria um caso de teste e expect faz as conferências. Os dois vêm do pacote do Playwright.
  • test e page: O nome aparece no relatório, então descreva a tarefa da pessoa. page é uma aba nova e limpa do navegador que o Playwright entrega para cada teste. A função é async porque quase tudo no navegador leva algum tempo.
  • goto: Abre a página. O endereço base (como http://localhost:5173) fica no arquivo de configuração, então o teste funciona no seu computador e na CI.
  • Localizar e preencher: getByLabel acha o campo pelo rótulo que a pessoa lê. fill limpa o campo e digita o texto.
  • Localizar e clicar: getByRole acha pelo papel do elemento (botão) e pelo nome visível. Antes de clicar, o Playwright espera o botão aparecer, estar habilitado e parado na tela.
  • Conferência com espera: Esse expect tenta de novo por alguns segundos (5 por padrão) até o texto aparecer. É assim que o teste espera a resposta da API sem precisar adivinhar quanto tempo ela leva.
  • toBeVisible: Confere que o elemento está na tela e visível para a pessoa, não apenas escondido no HTML.

Complete o teste de login: abrir a página, preencher o e-mail, clicar em Entrar e conferir a saudação.

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

____('pessoa entra na conta', async ({ ____ }) => {
  await page.____('/login');
  await page.getByLabel('E-mail').____('ana@exemplo.com');
  await page.getByLabel('Senha').fill(process.env.SENHA_TESTE);
  await page.getByRole('button', { name: 'Entrar' }).____();
  await ____(page.getByRole('heading', { name: 'Olá, Ana' })).toBeVisible();
});

Encontrar elementos como uma pessoa

Um localizador (em inglês, locator) é a descrição de como achar um elemento na página. Ele não guarda o elemento: procura de novo toda vez que é usado. Por isso continua funcionando quando a tela é redesenhada depois de uma resposta da API.

A ordem de preferência recomendada pela documentação do Playwright
LocalizadorAcha peloExemplo
getByRolePapel e nome acessívelgetByRole('button', { name: 'Pagar com Pix' })
getByLabelRótulo do campogetByLabel('CEP')
getByPlaceholderTexto de exemplo dentro do campogetByPlaceholder('00000-000')
getByTextTexto visívelgetByText('Pedido confirmado')
getByTestIdAtributo data-testid combinado com o timegetByTestId('total-carrinho')
locator com CSSClasse, id, posiçãolocator('.btn-a7') (último recurso)

Os primeiros da lista enxergam a página como a pessoa usuária e as tecnologias assistivas. Se getByRole não acha o seu botão, talvez ele seja uma div com clique, e o teste acabou de revelar um problema de acessibilidade. O data-testid é um combinado com quem desenvolve: um nome que não muda com o design, útil quando não há texto ou papel estável.

Ordene os localizadores do mais recomendado ao último recurso.

  • getByRole('button', { name: 'Finalizar compra' })
  • getByLabel('Número do cartão')
  • getByText('Frete grátis')
  • getByTestId('resumo-pedido')
  • locator('div.col-3 > span:nth-child(2)')

O teste falhou com: strict mode violation: getByRole('button', { name: 'Adicionar' }) resolved to 3 elements. O que isso quer dizer?

  • Há três botões “Adicionar” na página e o Playwright não adivinha qual você quer; é preciso deixar o localizador mais específico
  • O site está com defeito, porque botões não podem ter o mesmo nome
  • Basta usar .first() sempre que isso acontecer

Esperar o resultado, não o relógio

Antes de cada ação, o Playwright faz a espera automática (auto-wait): confere se o elemento existe, está visível, habilitado e parado. E os expect que olham a página, como toHaveText e toBeVisible, tentam de novo até a condição ser verdadeira ou o tempo limite acabar.

Conserte um teste E2E instável

A página da padaria é o site; o código abaixo traz um mini Playwright e dois testes. O primeiro usa classe CSS e uma espera fixa de 300 ms, mas o servidor leva 700 ms: ele falha. Reescreva-o com getByLabel, getByRole e expect(...).toHaveText(...), e escreva o segundo teste. Não apague as linhas que começam com // =====. Leia o console: ✓ passou, ✗ falhou.

<main>
  <h1>Padaria Pão Quente</h1>
  <p>Entrega de pão fresquinho no seu bairro.</p>
  <label for="cep">CEP</label>
  <input id="cep" class="x91" inputmode="numeric" />
  <button id="calcular" class="btn-a7">Calcular frete</button>
  <p role="status" id="resultado"></p>
</main>
body { font-family: system-ui, sans-serif; padding: 16px; }
main { max-width: 360px; display: grid; gap: 8px; }
input, button { font: inherit; padding: 8px; }
[role="status"] { font-weight: bold; min-height: 1.4em; }
// ===== O site da padaria (não precisa mexer) =====
let modoQuebrado = false;
const campoCep = document.getElementById('cep');
const resultado = document.getElementById('resultado');

document.getElementById('calcular').addEventListener('click', () => {
  const cep = campoCep.value.replace(/[^0-9]/g, '');
  resultado.textContent = 'Calculando...';
  // O servidor demora um pouco para responder, como na vida real
  setTimeout(() => {
    if (modoQuebrado) resultado.textContent = 'Frete: R$ NaN';
    else if (cep.length !== 8) resultado.textContent = 'CEP inválido';
    else resultado.textContent = 'Frete: R$ 8,00';
  }, 700);
});

function reiniciarSite() {
  campoCep.value = '';
  resultado.textContent = '';
}

// ===== Mini Playwright (não precisa mexer) =====
function nomeAcessivel(el) {
  const rotulo = el.id && document.querySelector('label[for="' + el.id + '"]');
  return (el.getAttribute('aria-label') || (rotulo && rotulo.textContent) || el.textContent || '').trim();
}

const papeis = {
  button: 'button',
  heading: 'h1, h2, h3',
  textbox: 'input, textarea',
  status: '[role="status"]',
};

async function aguardar(condicao, descricao, limite = 2000) {
  const inicio = Date.now();
  let ultimo = { ok: false, detalhe: '' };
  while (Date.now() - inicio < limite) {
    ultimo = condicao();
    if (ultimo.ok) return ultimo.el;
    await new Promise((r) => setTimeout(r, 50));
  }
  throw new Error('Timeout de ' + limite + ' ms: ' + descricao + (ultimo.detalhe ? ' (' + ultimo.detalhe + ')' : ''));
}

function localizador(descricao, buscar) {
  const achar = () => {
    const el = buscar();
    return { ok: Boolean(el), el, detalhe: el ? '' : 'nenhum elemento encontrado' };
  };
  return {
    descricao,
    buscar,
    async fill(texto) {
      const el = await aguardar(achar, 'esperando ' + descricao);
      el.value = texto;
      el.dispatchEvent(new Event('input', { bubbles: true }));
    },
    async click() {
      const el = await aguardar(achar, 'esperando ' + descricao);
      el.click();
    },
  };
}

const page = {
  getByRole(papel, opcoes = {}) {
    const nome = opcoes.name ? ", { name: '" + opcoes.name + "' }" : '';
    return localizador("getByRole('" + papel + "'" + nome + ')', () =>
      [...document.querySelectorAll(papeis[papel] || '[role="' + papel + '"]')].find(
        (el) => !opcoes.name || nomeAcessivel(el) === opcoes.name,
      ),
    );
  },
  getByLabel(texto) {
    return localizador("getByLabel('" + texto + "')", () => {
      const rotulo = [...document.querySelectorAll('label')].find((l) => l.textContent.trim() === texto);
      return rotulo ? document.getElementById(rotulo.htmlFor) : null;
    });
  },
  getByText(texto) {
    return localizador("getByText('" + texto + "')", () =>
      [...document.querySelectorAll('body *')].find(
        (el) => el.children.length === 0 && el.textContent.trim() === texto,
      ),
    );
  },
  locator(seletor) {
    return localizador("locator('" + seletor + "')", () => document.querySelector(seletor));
  },
  waitForTimeout(ms) {
    return new Promise((r) => setTimeout(r, ms));
  },
};

function expect(loc) {
  return {
    async toBeVisible() {
      await aguardar(() => {
        const el = loc.buscar();
        const visivel = Boolean(el && el.getClientRects().length);
        return { ok: visivel, el, detalhe: el ? 'elemento escondido' : 'nenhum elemento encontrado' };
      }, 'esperava ' + loc.descricao + ' visível');
    },
    async toHaveText(esperado) {
      await aguardar(() => {
        const el = loc.buscar();
        const atual = el ? el.textContent.trim() : null;
        return { ok: atual === esperado, el, detalhe: el ? 'recebeu "' + atual + '"' : 'nenhum elemento encontrado' };
      }, 'esperava ' + loc.descricao + ' com o texto "' + esperado + '"');
    },
  };
}

const testes = [];
function test(nome, fn) {
  testes.push({ nome, fn });
}

// ===== Seus testes =====
test('calcula o frete para um CEP válido', async ({ page }) => {
  await page.locator('.x91').fill('01310-100');
  await page.locator('.btn-a7').click();
  await page.waitForTimeout(300);
  const texto = document.querySelector('#resultado').textContent;
  if (texto !== 'Frete: R$ 8,00') {
    throw new Error('esperava "Frete: R$ 8,00", recebeu "' + texto + '"');
  }
});

test('avisa quando o CEP é inválido', async ({ page }) => {
  // Escreva este teste: preencha o CEP com '123', clique em "Calcular frete"
  // e confira que o status mostra 'CEP inválido'
});

// ===== Rodar os testes (não precisa mexer) =====
async function rodar() {
  for (const t of testes) {
    reiniciarSite();
    try {
      await t.fn({ page });
      console.log('✓ ' + t.nome);
    } catch (erro) {
      console.log('✗ ' + t.nome + ': ' + erro.message);
    }
  }
  console.log('Fim: ' + testes.length + ' testes');
}
rodar();
  • Os dois testes passam (✓) e nenhum falha
  • Os testes usam getByRole, sem classes CSS nem querySelector
  • Nenhuma espera fixa (waitForTimeout ou setTimeout) nos testes
  • Os dois testes ficam vermelhos quando o site quebra (frete vira R$ NaN)
O primeiro teste falhava com “Calculando...”. Se você trocasse a espera de 300 ms por 1000 ms, ele passaria. Por que isso ainda é uma má ideia?

Porque o tempo do servidor varia. Na CI, com a máquina ocupada, 700 ms viram 1200 e o teste falha de vez em quando. E quando o servidor responde em 100 ms, você desperdiça 900 ms em cada teste, vezes centenas de testes. Esperar a condição é ao mesmo tempo mais rápido e mais confiável.

Fixtures: cada teste começa do zero

Aquele { page } no começo do teste é uma fixture: algo que o Playwright prepara antes do teste e limpa depois. Cada teste ganha um contexto de navegador novo, como uma janela anônima: sem cookies, sem login, sem carrinho do teste anterior.

Isso garante isolamento: os testes podem rodar em qualquer ordem e em paralelo, em vários workers (processos que rodam testes ao mesmo tempo). Se você precisa de algo pronto antes, como uma pessoa logada, crie sua própria fixture em vez de depender de outro teste.

Duas formas de preparar o terreno sem criar dependência entre testes

beforeEach

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

test.beforeEach(async ({ page }) => {
  await page.goto('/cardapio');
});

test('mostra o pão de queijo', async ({ page }) => {
  await expect(page.getByRole('heading', { name: 'Pão de queijo' })).toBeVisible();
});

Fixture própria

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

// Cria uma pessoa nova pela API e entrega a página já logada
const test = base.extend({
  paginaLogada: async ({ page, request }, use) => {
    const email = 'teste-' + Date.now() + '@exemplo.com';
    await request.post('/api/contas', { data: { email, senha: process.env.SENHA_TESTE } });
    await page.goto('/login');
    await page.getByLabel('E-mail').fill(email);
    await page.getByLabel('Senha').fill(process.env.SENHA_TESTE);
    await page.getByRole('button', { name: 'Entrar' }).click();
    await use(page);
    await request.delete('/api/contas/' + email);
  },
});

test('vê o histórico de pedidos', async ({ paginaLogada }) => {
  await paginaLogada.getByRole('link', { name: 'Meus pedidos' }).click();
  await expect(paginaLogada.getByText('Nenhum pedido ainda')).toBeVisible();
});

Tudo antes de use(page) é preparação; tudo depois é limpeza, que roda mesmo se o teste falhar. Criar dados pela API, como você viu na aula de testes de API, é bem mais rápido que clicar em telas de cadastro.

O teste “cancela pedido” só passa se “faz pedido” rodar antes dele, porque usa o pedido criado ali. Rodando sozinho, falha. O que fazer?

  • Fazer “cancela pedido” criar o próprio pedido (pela API ou numa fixture) antes de cancelar
  • Juntar os dois num teste só e rodar sempre na mesma ordem
  • Configurar o Playwright para rodar com um único worker

Gravar, rodar e investigar falhas

Para começar rápido, o codegen abre um navegador e transforma seus cliques em código. É ótimo para descobrir localizadores; depois você revisa, troca valores fixos e acrescenta as conferências que ele não sabe escolher.

O codegen grava enquanto você usa o site e escreve o teste na janela ao lado.

npx playwright codegen http://localhost:5173
test('test', async ({ page }) => {
  await page.goto('http://localhost:5173/');
  await page.getByLabel('CEP').click();
  await page.getByLabel('CEP').fill('01310-100');
  await page.getByRole('button', { name: 'Calcular frete' }).click();
  await page.getByText('Frete: R$ 8,00').click();
});
O que você mudaria nesse código gravado antes de commitar?

Dar um nome que descreva a tarefa no lugar de test. Trocar o endereço completo por /, usando o endereço base da configuração. Apagar o click() extra no campo. E, principalmente, trocar o último clique no texto do frete por uma conferência: await expect(page.getByRole('status')).toHaveText('Frete: R$ 8,00'). Sem expect, o teste não confere nada.

Quando um teste falha, o Playwright deixa evidências. O relatório HTML lista testes, tempos e erros. O trace (rastro) é uma gravação passo a passo: para cada ação, mostra a tela antes e depois, as requisições de rede e o console. Com ele você vê a falha da CI como se estivesse lá.

Rode a suíte e investigue a falha

Você está no projeto da loja. Rode os testes, leia com calma a mensagem de erro e use as ferramentas de investigação.

  1. Rode todos os testes de ponta a ponta: npx playwright test

    npx playwright test
    Running 6 tests using 3 workers
    
      ✓  1 [chromium] › tests/busca.spec.ts:3:5 › pessoa busca um produto (1.2s)
      ✓  2 [chromium] › tests/login.spec.ts:5:5 › pessoa entra na conta (1.8s)
      ✓  3 [chromium] › tests/carrinho.spec.ts:4:5 › adiciona pão de queijo (1.4s)
      ✘  4 [chromium] › tests/frete.spec.ts:3:5 › calcula o frete para um CEP válido (5.6s)
      ✓  5 [chromium] › tests/frete.spec.ts:10:5 › avisa quando o CEP é inválido (1.1s)
      ✓  6 [chromium] › tests/pedido.spec.ts:6:5 › finaliza pedido com Pix (2.3s)
    
      1) [chromium] › tests/frete.spec.ts:3:5 › calcula o frete para um CEP válido
    
        Error: expect(locator).toHaveText(expected) failed
    
        Locator:  getByRole('status')
        Expected: "Frete: R$ 8,00"
        Received: "CEP inválido"
        Timeout:  5000ms
    
          5 |   await page.getByLabel('CEP').fill('01310-100');
          6 |   await page.getByRole('button', { name: 'Calcular frete' }).click();
        > 7 |   await expect(page.getByRole('status')).toHaveText('Frete: R$ 8,00');
            |                                          ^
    
        attachment #1: trace (application/zip)
        test-results/frete-calcula-o-frete-chromium/trace.zip
    
      1 failed
        [chromium] › tests/frete.spec.ts:3:5 › calcula o frete para um CEP válido
      5 passed (9.4s)
  2. Rode só o arquivo do frete para repetir a falha mais rápido: npx playwright test frete

    npx playwright test frete
    Running 2 tests using 2 workers
    
      ✘  1 [chromium] › tests/frete.spec.ts:3:5 › calcula o frete para um CEP válido (5.5s)
      ✓  2 [chromium] › tests/frete.spec.ts:10:5 › avisa quando o CEP é inválido (1.0s)
    
      1 failed
      1 passed (6.8s)
  3. Abra o trace da falha: npx playwright show-trace test-results/frete-calcula-o-frete-chromium/trace.zip

    npx playwright show-trace test-results/frete-calcula-o-frete-chromium/trace.zip
    Abrindo o Trace Viewer...
    
      fill getByLabel('CEP')                 valor digitado: "01310-100"
      click getByRole('button', { name: 'Calcular frete' })
      POST /api/frete  →  422  {"erro":"CEP deve ter só números"}
      expect toHaveText                      recebido: "CEP inválido"
  4. Abra o relatório HTML para ver a suíte inteira: npx playwright show-report

    npx playwright show-report
      Serving HTML report at http://localhost:9323. Press Ctrl+C to quit.

Pelo trace, a API agora recusa CEP com hífen (422), e o site mostra “CEP inválido” para 01310-100. Na semana passada esse mesmo teste passava. O que você faz?

  • Abro um relato de bug no produto: pessoas digitam CEP com hífen, e o site deveria aceitar ou limpar o hífen antes de enviar
  • Mudo o teste para digitar 01310100, sem hífen, e ele volta a passar
  • Rodo de novo até passar, porque deve ser instabilidade

Nem toda falha é bug do produto. Um teste instável (flaky) passa e falha sem nenhuma mudança no código. Um bom diagnóstico é rodar o mesmo teste várias vezes seguidas, com npx playwright test frete --repeat-each=20: se falhar 3 de 20, o problema é de estabilidade.

Cada falha abaixo é causa típica de teste instável ou sinal de bug do produto?

Teste instável · Bug do produto

  • O teste espera 2 segundos fixos e a API às vezes leva 3
  • Dois testes em paralelo usam a mesma conta e um esvazia o carrinho do outro
  • O teste depende da data de hoje e falha todo dia 31
  • O teste clica no primeiro “Adicionar”, e a ordem da lista muda a cada carga
  • Todo CEP com hífen é recusado desde o último deploy
  • O botão “Pagar” fica desabilitado depois de aplicar um cupom, em toda execução

Fechamento

  • Um teste de ponta a ponta usa um navegador de verdade para provar que as peças funcionam juntas; guarde-o para as jornadas críticas.
  • Um teste Playwright navega com page.goto, localiza com getByRole e getByLabel, age com fill e click e confere com expect.
  • A espera automática e os expect que tentam de novo substituem esperas fixas, que deixam a suíte lenta e instável.
  • Fixtures dão a cada teste um navegador limpo e dados próprios, então os testes rodam isolados, em qualquer ordem e em paralelo.
  • Codegen ajuda a começar; relatório, trace e --repeat-each ajudam a separar bug do produto de teste instável.

Automatize o fluxo principal de um site

Escolha um projeto seu (ou um site de exemplo que você possa rodar localmente) e proteja a tarefa mais importante dele com Playwright, investigando uma falha pelo trace.

  1. Instale com npm init playwright@latest e configure o baseURL e o webServer do seu projeto
  2. Grave o fluxo principal com npx playwright codegen e reescreva o código com nome claro e conferências com expect
  3. Garanta que o teste usa getByRole ou getByLabel e nenhuma espera fixa
  4. Quebre o site de propósito, rode o teste e investigue a falha com npx playwright show-trace
  5. Rode o teste sozinho, junto com a suíte e com --repeat-each=10 para confirmar que ele é estável

Referências

Cursos relacionados