Sexta-feira à noite, você faz 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 pricing — uma página em que você nem tinha mexido. Nenhum teste soou o alarme, porque nenhum teste olhava para a aparência. É exatamente essa lacuna 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(). 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 guia cobre instalação, configuração, boas práticas e integração CI/CD.
O toHaveScreenshot() ainda obriga você a escrever e manter código? O Delta-QA captura e compara as suas páginas sem escrever uma linha de código, sem inscrição e com os seus dados a ficarem locais. 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
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();
Sem vontade de escrever e manter toHaveScreenshot() à mão? Capture e compare screenshots no Delta-QA sem uma linha de código, num app Desktop gratuito e sem inscrição. Testar o Delta-QA grátis →
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 motor de comparação visual determinístico.
Quer testar sem uma linha de TypeScript nem uma única baseline para regenerar? Compare as suas páginas com o Delta-QA agora mesmo, de graça e sem inscrição. Testar o Delta-QA grátis →
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.