Teste visual com Playwright: o guia completo

Teste visual com Playwright: o guia completo

Sexta à noite, você faz o merge de uma reformulação do header. Segunda de manhã, um colega avisa que o botão de login deslizou alguns pixels na página de preços: uma página que você nem tinha tocado. Nenhum teste soou o alarme, porque nenhum teste olhava a aparência. É exatamente esse buraco que o teste visual preenche.

O Playwright, da Microsoft, inclui desde a versão 1.22 uma funcionalidade nativa de teste visual: o método toHaveScreenshot(). Ele permite capturar screenshots e compará-los automaticamente com imagens de referência, sem plugin externo. É uma solução totalmente gratuita: para outras ferramentas gratuitas de teste visual, veja nosso comparativo.

É uma das opções mais sólidas para equipes que querem adicionar testes visuais à suíte existente. Para entender as bases da regressão visual, consulte nosso guia completo. Este guia cobre instalação, configuração, boas práticas e integração CI/CD, e depois o que o SDK Vision do Delta-QA muda nesses mesmos testes.

O essencial em uma página: o que uma ferramenta sem código realmente automatiza e como ela se compara: Automação de testes sem código.

O toHaveScreenshot() ainda obriga você a escrever e manter código? O Delta-QA captura e compara suas páginas sem escrever uma linha de código, sem cartão de crédito. Testar o Delta-QA grátis →

Instalação e primeiro teste

A configuração é rápida se você já tem um projeto Node.js:

npm install -D @playwright/test
npx playwright install

Em seguida, crie seu primeiro teste visual em tests/visual.spec.ts:

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

test('homepage visual test', async ({ page }) => {
  await page.goto('https://your-site.com');
  await expect(page).toHaveScreenshot('homepage.png');
});

A primeira execução gera a baseline (a imagem de referência). As execuções seguintes comparam a captura do momento com essa baseline e sinalizam as diferenças.

# Primeira vez: gerar as baselines
npx playwright test --update-snapshots

# Depois: comparar
npx playwright test

É simples assim para começar. A complexidade chega com os casos reais.

Configurar a tolerância

Por padrão, o Playwright sinaliza qualquer diferença de um pixel. Na prática, é preciso configurar limites de tolerância para evitar os falsos positivos.

No playwright.config.ts:

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

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01,  // tolera 1 % de pixels diferentes
      animations: 'disabled',    // desativa as animações CSS
      scale: 'device',           // considera telas Retina
    },
  },
});

Você também pode ajustar teste a teste:

// Página estática: limite estrito
await expect(page).toHaveScreenshot('landing.png', {
  maxDiffPixelRatio: 0.001
});

// Painel com gráficos: limite mais flexível
await expect(page).toHaveScreenshot('dashboard.png', {
  maxDiffPixelRatio: 0.05,
  mask: [page.locator('.chart')]
});

O limite é um meio-termo: baixo demais, qualquer variação de renderização faz o teste falhar; alto demais, uma margem que passa de 16px para 12px escorrega por baixo da régua sem ser vista.

Lidar com conteúdo dinâmico

O conteúdo dinâmico (datas, anúncios, avatares, contadores) é o pesadelo dos testes visuais. O Playwright oferece três soluções:

Mascarar as zonas dinâmicas, o método mais comum:

await expect(page).toHaveScreenshot({
  mask: [
    page.locator('.ad-banner'),
    page.locator('.timestamp'),
    page.locator('.user-avatar')
  ]
});

Substituir o conteúdo para fixar os valores:

await page.evaluate(() => {
  document.querySelector('.date').textContent = '01/01/2026';
});
await expect(page).toHaveScreenshot();

Esconder via CSS os elementos que não devem aparecer de jeito nenhum:

await page.addStyleTag({
  content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();

Cada uma dessas soluções é mantida à mão: um novo bloco dinâmico na página, e é mais um seletor para adicionar.

Estabilizar os testes

Um teste visual que passa um dia e falha no outro sem motivo é inutilizável. Veja como garantir a estabilidade:

test('stable visual test', async ({ page }) => {
  await page.goto('https://your-site.com');

  // Esperar a rede acalmar
  await page.waitForLoadState('networkidle');

  // Esperar o carregamento das fontes
  await page.evaluate(() => document.fonts.ready);

  // Esperar um elemento crítico
  await page.waitForSelector('.hero-image', { state: 'visible' });

  await expect(page).toHaveScreenshot();
});

E para desativar as animações à mão quando a opção global não basta:

await page.addStyleTag({
  content: `
    *, *::before, *::after {
      animation-duration: 0s !important;
      transition-duration: 0s !important;
    }
  `
});

Testar várias resoluções

O Playwright facilita o teste multirresolução por meio de projetos:

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Desktop',
      use: { viewport: { width: 1920, height: 1080 } },
    },
    {
      name: 'Tablet',
      use: { viewport: { width: 768, height: 1024 } },
    },
    {
      name: 'Mobile',
      use: { ...devices['iPhone 13'] },
    },
  ],
});

Cada projeto gera suas próprias baselines. Um teste é executado, portanto, três vezes, em três resoluções, com três conjuntos de capturas para manter atualizados.

Integração CI/CD

A integração no GitHub Actions é direta. Para uma configuração completa, consulte nosso guia de testes de regressão no GitHub Actions ou, no lado do GitLab, o de teste visual no GitLab CI.

name: Visual Tests
on: [push, pull_request]
jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

Quando um teste falha, o Playwright produz três imagens: a baseline (esperada), a captura do momento e um diff com as diferenças em vermelho. O relatório HTML (npx playwright show-report) as exibe lado a lado.

Ponto de atenção: a renderização das fontes varia de um sistema para outro. Baselines geradas em um Mac não corresponderão às capturas feitas no runner Linux da CI. Gere-as na CI, ou na imagem Docker oficial do Playwright.

O toHaveScreenshot() ainda pede que você escreva código? O Delta-QA captura e compara suas páginas sem código, sem cartão de crédito. Testar o Delta-QA grátis →

Os limites da abordagem Playwright

O Playwright é excelente para equipes que escrevem seus testes, mas o toHaveScreenshot() tem limites que é preciso conhecer:

Competências obrigatórias: é preciso dominar TypeScript/JavaScript, seletores e configuração de projeto. QAs que não escrevem código não conseguem criar nem manter esses testes.

Sem interface de revisão: não há espaço compartilhado para julgar as diferenças. A gestão das baselines é feita pelo terminal e pelo sistema de arquivos. Em equipe, isso fica complexo rápido.

Uma comparação de pixels: o diff mostra uma zona vermelha, não o que mudou. As diferenças de anti-aliasing entre navegadores, as variações de renderização de fontes entre sistemas: tudo isso gera ruído que é preciso tratar à mão com máscaras e limites.

Manutenção: cada mudança de interface desejada obriga a regenerar as baselines (--update-snapshots). Em um projeto com 200 testes visuais e 3 navegadores, são 600 baselines para gerenciar, versionadas no repositório. Nosso guia sobre gestão de baselines detalha as estratégias para mantê-las.

Manter o Playwright, mudar a comparação: o SDK Vision

Se os seus testes Playwright já existem, você não precisa abandoná-los para superar parte desses limites. O SDK Vision do Delta-QA (@delta-qa/vision) adiciona uma verificação Delta-QA onde o teste deve olhar a página:

import { test } from "@delta-qa/vision/fixture";

test("Checkout", async ({ page, vision }) => {
  const checkout = await vision.open(page, { id: "checkout", name: "Checkout" });
  await page.goto("https://shop.example.com/checkout");
  await checkout.check("Payment");
}); // fechado pela fixture: uma diferença não julgada faz o teste falhar

O SDK lê a chave de API na variável DELTAQA_API_KEY. Sem a fixture, open(page, { … }) de @delta-qa/vision abre o mesmo teste, e close() o fecha em um afterEach.

O que muda em relação ao toHaveScreenshot():

  • O relatório nomeia o elemento que mudou. Nada de zona vermelha para interpretar: o relatório diz qual elemento mudou, por exemplo o botão "Pagar", que passou de azul para verde.
  • As referências deixam de viver no repositório. Na primeira execução, cada check vira a referência. Depois, uma diferença não julgada faz o teste falhar, e o log da CI traz o link do relatório. Ali você julga cada diferença: "Voulu" (pretendida) ou "Bug".
  • Uma referência por branch. O teste informa sua branch e sua branch de base (branch, baseBranch): uma branch nova é comparada com a sua branch de base desde a primeira execução, e "Voulu" só se aplica às branches que você marcar.
  • O resto do teste não muda. Os projetos do playwright.config.ts continuam valendo: cada tamanho de tela tem a sua própria referência. Uma única condição: densidade de tela 1 (deviceScaleFactor: 1).

O SDK cobre Playwright em TypeScript e JavaScript, em Chromium. Ele é oferecido primeiro em acesso antecipado: o acesso é solicitado a partir da própria página.

E para quem não escreve testes

Os testes Playwright continuam sendo código. Para que QAs, product owners ou designers também verifiquem a aparência da aplicação, soluções sem código como o Delta-QA oferecem outro caminho: grava-se um fluxo no navegador, o Delta-QA o reexecuta a cada versão e compara cada etapa com a sua referência. Esses cenários e os checks do SDK Vision são julgados no mesmo espaço do Delta-QA, com o mesmo relatório.

Quer testar sem uma linha de TypeScript nem uma única baseline para regenerar? Compare suas páginas com o Delta-QA agora mesmo, de graça e sem cartão de crédito. Testar o Delta-QA grátis →

FAQ

O Playwright é gratuito para testes visuais?

Sim, totalmente. O toHaveScreenshot() é nativo do Playwright, que é open source e mantido pela Microsoft. Sem licença, sem limite de screenshots.

Quanto tempo leva para configurar os testes visuais do Playwright?

Se você já domina o Playwright, conte algumas horas para configurar e escrever os primeiros testes. Se parte do zero (instalação, aprendizado de TypeScript, configuração da CI), conte de 2 a 3 dias.

Playwright ou Cypress para testes visuais?

O Playwright tem a vantagem de integrar o teste visual nativamente (toHaveScreenshot()), enquanto o Cypress exige um plugin externo. O Playwright também suporta três motores de navegador (Chromium, Firefox, WebKit), ao passo que o Cypress suporta os navegadores Chromium e Firefox, com o WebKit ainda experimental. Para os detalhes, veja nosso comparativo Playwright vs Cypress, ou Playwright vs Selenium se você está em dúvida entre esses dois frameworks.

Dá para usar Playwright e Delta-QA juntos?

Sim, e no mesmo teste. Com o SDK Vision, você adiciona vision.check() nas etapas em que a página deve ser verificada: o Playwright conduz o navegador e as suas asserções funcionais, o Delta-QA compara a página com a sua referência. Os fluxos gravados sem código pela equipe de QA são julgados no mesmo espaço.

Preciso remover meus toHaveScreenshot() para usar o SDK Vision?

Não. Os dois podem coexistir na mesma suíte: você pode adicionar vision.check() em algumas páginas, comparar os resultados e depois decidir, página a página, o que manter.


O Playwright oferece uma base sólida para testes visuais automatizados. Para equipes que escrevem seus testes em TypeScript, o toHaveScreenshot() é provavelmente a melhor opção open source disponível em 2026, desde que os limites sejam bem ajustados e os testes estabilizados desde o início. Quando o diff de pixels e as baselines do repositório se tornam a principal carga, o SDK Vision mantém seus testes e muda a comparação. Para situar o Playwright frente às outras ferramentas, consulte nosso comparativo das ferramentas de teste de regressão.