Teste Visual com Playwright: O Tutorial Completo

O Playwright da Microsoft inclui desde a versão 1.22 uma funcionalidade nativa de teste visual: o método toHaveScreenshot(). Permite capturar screenshots e compará-los automaticamente com imagens de referência, sem plugin externo.

É uma das opções mais sólidas para equipes de desenvolvimento que querem adicionar testes visuais à sua stack existente. Este tutorial cobre instalação, configuração, boas práticas e integração CI/CD.

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

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://seu-site.com');
  await expect(page).toHaveScreenshot('homepage.png');
});

A primeira execução gera a baseline (a imagem de referência). As seguintes comparam o screenshot atual com esta 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 a menor diferença de um pixel. Na prática, é preciso configurar limites de tolerância para evitar falsos positivos.

Em playwright.config.ts:

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

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

Você também pode ajustar por teste:

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

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

Gerenciar o conteúdo dinâmico

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

Mascarar zonas dinâmicas — a mais comum:

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

Substituir o conteúdo — para fixar valores:

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

Esconder via CSS — para elementos que não quer ver:

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

Estabilizar os testes

Um teste visual que passa um dia e falha no seguinte sem razão é inutilizável:

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

  // Esperar que a rede fique calma
  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();
});

Para desativar manualmente as animações:

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

Testar múltiplas resoluções

O Playwright facilita o teste multi-resolução via projetos:

// playwright.config.ts
projects: [
  {
    name: 'Desktop',
    use: { viewport: { width: 1920, height: 1080 } },
  },
  {
    name: 'Tablet',
    use: { viewport: { width: 768, height: 1024 } },
  },
  {
    name: 'Mobile',
    use: { ...devices['iPhone 13'] },
  },
]

Integração CI/CD

A integração no GitHub Actions é direta:

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/

Os limites da abordagem Playwright

Competências obrigatórias: é preciso dominar TypeScript/JavaScript, seletores e configuração de projeto. Não é acessível para QA não-desenvolvedores.

Sem dashboard: não há interface de revisão integrada.

Falsos positivos: a comparação de pixels é básica. Diferenças de anti-aliasing entre navegadores geram ruído.

Manutenção: cada mudança de UI intencional requer regenerar baselines. Em 200 testes com 3 navegadores, são 600 baselines.

Para equipes que querem teste visual sem essas restrições técnicas, as soluções no-code como Delta-QA oferecem uma alternativa com zero falsos positivos graças a um algoritmo de comparação estrutural em 5 passadas.

FAQ

Playwright é gratuito para testes visuais?

Sim, completamente. toHaveScreenshot() está integrado nativamente no Playwright, open source e mantido pela Microsoft.

Playwright ou Cypress para testes visuais?

Playwright integra o teste visual nativamente, enquanto Cypress precisa de plugin externo. Playwright suporta três motores de navegador (Chromium, Firefox, WebKit). Para teste visual, Playwright é a melhor opção open source.

Pode-se usar Playwright e Delta-QA juntos?

Sim. A abordagem recomendada é usar Playwright para testes visuais complexos e Delta-QA para verificações visuais de rotina mantidas pela equipe QA.

---

Playwright oferece uma base sólida para testes visuais automatizados. Para equipes que dominam TypeScript, é provavelmente a melhor opção open source disponível em 2026.

---

Experimentar Delta-QA Grátis →

---

Artigo anterior: Do Teste Manual ao Teste Automatizado: Guia para QA Não-Desenvolvedores