Visuelles Testen mit Playwright: Das Komplette Tutorial
Playwright von Microsoft enthält seit Version 1.22 eine native Funktion für visuelles Testen: die Methode toHaveScreenshot(). Sie ermöglicht es, Screenshots aufzunehmen und automatisch mit Referenzbildern zu vergleichen, ohne externes Plugin.
Das ist eine der solidesten Optionen für Entwicklungsteams, die visuelle Tests zu ihrem bestehenden Stack hinzufügen möchten. Dieses Tutorial behandelt Installation, Konfiguration, Best Practices und CI/CD-Integration.
Installation und erster Test
Die Einrichtung geht schnell, wenn Sie bereits ein Node.js-Projekt haben:
npm install -D @playwright/test
npx playwright install
Erstellen Sie dann Ihren ersten visuellen Test in tests/visual.spec.ts:
import { test, expect } from '@playwright/test';
test('homepage visual test', async ({ page }) => {
await page.goto('https://ihre-seite.com');
await expect(page).toHaveScreenshot('homepage.png');
});
Der erste Durchlauf generiert die Baseline (das Referenzbild). Die folgenden Durchläufe vergleichen den aktuellen Screenshot mit dieser Baseline und melden Unterschiede.
# Erstes Mal: Baselines generieren
npx playwright test --update-snapshots
# Danach: vergleichen
npx playwright test
So einfach ist der Einstieg. Die Komplexität kommt mit den realen Anwendungsfällen.
Toleranz konfigurieren
Standardmäßig meldet Playwright den kleinsten Unterschied eines einzelnen Pixels. In der Praxis müssen Toleranzschwellen konfiguriert werden, um falsch-positive Ergebnisse zu vermeiden.
In playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
maxDiffPixelRatio: 0.01, // 1% unterschiedliche Pixel toleriert
animations: 'disabled', // CSS-Animationen deaktivieren
scale: 'device', // Retina-Displays berücksichtigen
},
},
});
Sie können auch pro Test anpassen:
// Statische Seite: strenger Schwellenwert
await expect(page).toHaveScreenshot('landing.png', {
maxDiffPixelRatio: 0.001
});
// Dashboard mit Diagrammen: lockerer Schwellenwert
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixelRatio: 0.05,
mask: [page.locator('.chart')]
});
Dynamische Inhalte verwalten
Dynamische Inhalte (Daten, Werbung, Avatare, Zähler) sind der Albtraum visueller Tests. Playwright bietet drei Lösungen:
Dynamische Bereiche maskieren — die häufigste Methode:
await expect(page).toHaveScreenshot({
mask: [
page.locator('.ad-banner'),
page.locator('.timestamp'),
page.locator('.user-avatar')
]
});
Inhalte ersetzen — um Werte einzufrieren:
await page.evaluate(() => {
document.querySelector('.date').textContent = '01.01.2026';
});
await expect(page).toHaveScreenshot();
Per CSS ausblenden — für Elemente, die gar nicht sichtbar sein sollen:
await page.addStyleTag({
content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();
Tests stabilisieren
Ein visueller Test, der einen Tag besteht und am nächsten ohne Grund fehlschlägt, ist unbrauchbar. So garantieren Sie Stabilität:
test('stable visual test', async ({ page }) => {
await page.goto('https://ihre-seite.com');
// Warten, bis das Netzwerk ruhig ist
await page.waitForLoadState('networkidle');
// Warten auf das Laden der Schriften
await page.evaluate(() => document.fonts.ready);
// Warten auf ein kritisches Element
await page.waitForSelector('.hero-image', { state: 'visible' });
await expect(page).toHaveScreenshot();
});
Und um Animationen manuell zu deaktivieren, wenn die globale Option nicht ausreicht:
await page.addStyleTag({
content: `
*, *::before, *::after {
animation-duration: 0s !important;
transition-duration: 0s !important;
}
`
});
Mehrere Auflösungen testen
Playwright erleichtert Multi-Auflösungstests über Projekte:
// 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'] },
},
]
Jedes Projekt generiert seine eigenen Baselines. Ein Test wird also dreimal ausgeführt, in drei Auflösungen, mit drei Screenshot-Sets.
CI/CD-Integration
Die Integration in GitHub Actions ist direkt:
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/
Wenn ein Test fehlschlägt, generiert Playwright drei Bilder: die Baseline (erwartet), den aktuellen Screenshot und einen Diff mit den rot markierten Unterschieden. Der HTML-Bericht (npx playwright show-report) zeigt sie nebeneinander an.
Die Grenzen des Playwright-Ansatzes
Playwright ist hervorragend für Entwicklungsteams, hat aber Grenzen, die man kennen sollte:
Erforderliche Kompetenzen: Man muss TypeScript/JavaScript, Selektoren und Projektkonfiguration beherrschen. Das ist für QA-Mitarbeiter ohne Entwicklungshintergrund nicht zugänglich.
Kein Dashboard: Es gibt kein integriertes Review-Interface. Die Baseline-Verwaltung erfolgt über Terminal und Dateisystem. Im Team wird das schnell komplex.
Falsch-positive Ergebnisse: Der Pixel-Vergleich bleibt einfach. Anti-Aliasing-Unterschiede zwischen Browsern, Font-Rendering-Variationen zwischen Betriebssystemen — all das erzeugt Rauschen, das manuell mit Masks und Schwellenwerten verwaltet werden muss.
Wartung: Jede beabsichtigte UI-Änderung erfordert die Neugenerierung der Baselines (--update-snapshots). Bei einem Projekt mit 200 visuellen Tests und 3 Browsern sind das 600 Baselines, die verwaltet werden müssen.
Für Teams, die visuelles Testen ohne diese technischen Einschränkungen wollen, bieten No-Code-Lösungen wie Delta-QA eine Alternative: dasselbe Ergebnis (Erkennung visueller Regressionen) ohne Code zu schreiben, ohne manuelle Baseline-Verwaltung und mit null falsch-positiven Ergebnissen dank eines strukturellen 5-Phasen-Vergleichsalgorithmus anstelle eines rohen Pixel-Vergleichs.
FAQ
Ist Playwright für visuelle Tests kostenlos?
Ja, vollständig. toHaveScreenshot() ist nativ in Playwright integriert, das Open Source ist und von Microsoft gepflegt wird. Keine Lizenz, keine Screenshot-Limits.
Wie lange dauert es, visuelle Tests mit Playwright einzurichten?
Wenn Sie Playwright bereits beherrschen, rechnen Sie mit einigen Stunden für Konfiguration und die ersten Tests. Wenn Sie bei null anfangen (Installation, TypeScript-Lernen, CI-Konfiguration), rechnen Sie mit 2 bis 3 Tagen.
Playwright oder Cypress für visuelle Tests?
Playwright hat den Vorteil, visuelles Testen nativ zu integrieren (toHaveScreenshot()), während Cypress ein externes Plugin benötigt. Playwright unterstützt auch drei Browser-Engines (Chromium, Firefox, WebKit) gegenüber nur einer bei Cypress (Chromium-basiert). Speziell für visuelles Testen ist Playwright die beste Open-Source-Wahl.
Kann man Playwright und Delta-QA zusammen verwenden?
Ja. Der empfohlene Ansatz ist, Playwright für komplexe visuelle Tests (mit bedingter Logik, dynamischen Daten) und Delta-QA für routinemäßige visuelle Überprüfungen zu verwenden, die vom QA-Team gepflegt werden. Jedes Tool deckt einen anderen Bedarf ab.
Playwright bietet eine solide Grundlage für automatisierte visuelle Tests. Für Entwicklungsteams, die TypeScript beherrschen, ist es wahrscheinlich die beste verfügbare Open-Source-Option im Jahr 2026. Wichtig ist, die Toleranzschwellen gut zu konfigurieren und die Tests von Anfang an zu stabilisieren, um falsch-positive Ergebnisse zu vermeiden.
Vorheriger Artikel: Vom Manuellen zum Automatisierten Testen: Leitfaden für QA-Mitarbeiter ohne Entwicklungshintergrund