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.tscontinuam 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.
