Screenshot-Tests mit Playwright einrichten

Screenshot-Tests mit Playwright erkennen UI-Änderungen, bevor sie veröffentlicht werden. Der Test öffnet eine Seite, wartet auf einen stabilen Zustand, nimmt ein Bild auf und vergleicht es mit einer freigegebenen Baseline. Genau darin unterscheiden sie sich von gewöhnlicher Screenshot-Automatisierung und bilden die Grundlage für visuelle Regressionstests.

Die Beispiele nutzen die Shotomatic-Funktionsseite https://www.shotomatic.com/features als öffentliches Ziel. Noch nützlicher ist das Muster in der eigenen App: Dort lassen sich Daten, Anmeldestatus, Animationen und Testselektoren kontrollieren.

Wenn du lediglich Bilddateien für eine URL-Liste brauchst, beginne mit der gewöhnlichen Screenshot-Automatisierung in Playwright. Hier geht es um die Testvariante: Baselines, Bildvergleich, Browserprojekte und Prüfung der Änderungen.

Wann sich Screenshot-Tests lohnen

Screenshot-Tests helfen, wenn eine visuelle Abweichung mit gewöhnlichen Assertions leicht unbemerkt bliebe.

Gute Kandidaten sind:

• Marketingseiten mit wichtigen Hero-, Preis- oder Registrierungsbereichen
• Komponenten eines Designsystems mit vielen Zuständen
• Checkout-, Onboarding- oder Dashboard-Ansichten, bei denen das Layout zählt
• responsive Seiten, die bei mobilen Breiten häufig fehlerhaft dargestellt werden
• Seiten, auf denen CSS-Änderungen Inhalte unbemerkt verschieben oder ausblenden können

Weniger geeignet sind:

• Seiten mit ständig wechselnden Feeds, Anzeigen, Zeitstempeln oder nutzergenerierten Inhalten
• Seiten, bei denen die visuelle Ausführung keine wichtige Rolle spielt
• Abläufe, die bereits durch aussagekräftigere Text-, Rollen- oder Verhaltensprüfungen abgedeckt sind
• komplette Websites mit Hunderten instabilen Seiten, aber ohne geregelte Prüfung

Beginne mit einigen wichtigen Ansichten. Wer alles überwachen möchte, erzeugt schnell unnötig viele Fehlmeldungen.

Playwright Test installieren

In einem neuen oder bestehenden Node-Projekt kann der offizielle Playwright-Installer den Test-Runner, die Konfigurationsdatei, Beispieltests und die Browserinstallation anlegen:

$ npm init playwright@latest

Der Installer fragt nach TypeScript oder JavaScript, dem Testverzeichnis, einem GitHub-Actions-Workflow und der Browserinstallation. Führe nach der Einrichtung die Tests aus:

$ npx playwright test

Die Beispiele in dieser Anleitung verwenden TypeScript-Dateien unter tests/.

Den ersten Screenshot-Test erstellen

Erstelle tests/features-page.spec.ts:

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

test("features page has a stable desktop layout", async ({ page }) => {
  await page.goto("https://www.shotomatic.com/features");

  await expect(
    page.getByRole("heading", {
      name: /Shotomatic Features/i,
    }),
  ).toBeVisible();

  await expect(page).toHaveScreenshot("features-page-desktop.png", {
    fullPage: true,
  });
});

Der entscheidende Unterschied zu page.screenshot() ist die Assertion. toHaveScreenshot() in Playwright Test erstellt eine Baseline oder vergleicht die aktuelle Aufnahme damit. Beim ersten Lauf wird die fehlende Baseline geschrieben. Spätere Läufe vergleichen den neuen Screenshot mit diesem gespeicherten Bild.

Führe den Test aus:

$ npx playwright test tests/features-page.spec.ts

Beim ersten Lauf schreibt Playwright ein neues erwartetes Bild, weil noch keine Baseline vorhanden ist. Prüfe es, bevor du es eincheckst. Eine Baseline ist eine Testerwartung und kein beliebiges Artefakt.

Einen kleineren Seitenbereich testen

Ganzseiten-Screenshots erkennen großflächige Layoutverschiebungen, schlagen aber auch häufiger wegen einer unbeteiligten Änderung weiter unten fehl. Für viele Teams lässt sich eine Baseline für einen Abschnitt oder eine Komponente leichter pflegen.

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

test("features comparison cards stay aligned", async ({ page }) => {
  await page.goto("https://www.shotomatic.com/features");

  const comparisonHeading = page.getByRole("heading", {
    name: /Choose a workflow/i,
  });
  const comparisonSection = page.locator("section").filter({
    has: comparisonHeading,
  });

  await expect(comparisonHeading).toBeVisible();
  await expect(comparisonSection).toHaveScreenshot("features-comparison-section.png");
});

Nutze Locator-Screenshots für eine lokale Prüffrage: Sieht dieser Abschnitt noch richtig aus? Ein Seitenscreenshot passt, wenn das gesamte Seitenlayout zählt.

Browser- und Geräteprojekte hinzufügen

Der Test-Runner von Playwright kann denselben Test in benannten Projekten ausführen. Damit geht der Ablauf über ein einfaches Aufnahmeskript hinaus: Browser, Gerät, Ansichtsgröße und Snapshot-Name werden Teil der Testmatrix.

Beispiel für playwright.config.ts:

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  use: {
    baseURL: "https://www.shotomatic.com",
    trace: "on-first-retry",
  },
  projects: [
    {
      name: "desktop-chromium",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 1440, height: 1000 },
      },
    },
    {
      name: "mobile-safari",
      use: {
        ...devices["iPhone 13"],
      },
    },
  ],
});

Verwende danach relative URLs im Test:

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

test("features page visual baseline", async ({ page }) => {
  await page.goto("/features");
  await expect(page.getByRole("main")).toBeVisible();

  await expect(page).toHaveScreenshot("features-page.png", {
    fullPage: true,
  });
});

Playwright speichert für jedes Projekt eigene Snapshots. Desktop- und Mobil-Baselines können daher nebeneinanderliegen, ohne fälschlich als identisch zu gelten. Das eignet sich besser als ein einzelner Ansichtsgrößen-Screenshot, wenn du die Darstellung bei mehreren Gerätegrößen prüfen möchtest.

Einen stabilen Seitenzustand herstellen

Viele unnötige Fehlschläge entstehen durch einen wechselnden Seitenzustand. Playwright deaktiviert CSS-Animationen und Übergänge während einer Screenshot-Assertion standardmäßig. Veränderliche Daten, verzögert geladene Inhalte, Anzeigen oder nutzerspezifische Elemente können Pixel trotzdem verschieben.

Warte vor der Aufnahme auf einen konkreten Zustand:

await page.goto("/features");
await expect(page.getByRole("main")).toBeVisible();
await expect(page.getByText("Hands-Free Capture")).toBeVisible();

Verlasse dich nicht hauptsächlich auf eine feste Wartezeit. Benötigt die Seite vor der Aufnahme eine Karte, Überschrift, Tabelle oder ein geladenes Bild, warte direkt auf dieses Element.

Lädt die Seite Inhalte unterhalb des sichtbaren Bereichs erst beim Scrollen, scrolle vor dem Ganzseiten-Screenshot:

await page.evaluate(async () => {
  const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
  const viewportHeight = window.innerHeight;

  for (let y = 0; y < document.body.scrollHeight; y += viewportHeight) {
    window.scrollTo(0, y);
    await delay(100);
  }

  window.scrollTo(0, 0);
});

Ein solcher Helfer ist sinnvoll, wenn die Seite ihn braucht. Lass ihn in der Nähe des Tests, damit der Grund für das Scrollen erkennbar bleibt.

Veränderliche Elemente ausblenden oder maskieren

Manche Seitenbereiche sollen nicht in den visuellen Vergleich einfließen, etwa Zeitstempel, Avatare, Anzeigen, nutzerspezifische Namen, Ladeindikatoren oder Video-Vorschaubilder.

Dafür gibt es zwei übliche Wege.

Bestimmte Locator maskieren:

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  mask: [page.locator("[data-testid='release-date']")],
});

Oder während der Aufnahme ein Stylesheet anwenden:

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  stylePath: "./tests/screenshot.css",
});

Beispiel für tests/screenshot.css:

[data-testid="release-date"],
[data-testid="animated-cursor"] {
  visibility: hidden !important;
}

Blende keine echte Produktoberfläche aus, nur damit die Tests bestehen. Masken sind für wechselnde Inhalte gedacht, die nicht Teil der visuellen Prüffrage sind.

Einen Diff-Grenzwert vorsichtig festlegen

Playwright kann eine begrenzte Zahl abweichender Pixel zulassen:

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  maxDiffPixels: 100,
});

Das kann kleine Rendering-Unterschiede abfangen, aber auch echte Regressionen verdecken. Halte die Grenzwerte niedrig, dokumentiere ihren Grund und stabilisiere möglichst zuerst die Seite, bevor du den Vergleich lockerst.

Gemeinsame Vorgaben für Screenshot-Assertions lassen sich in playwright.config.ts festlegen:

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

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,
    },
  },
});

Baselines prüfen und aktualisieren

Wenn ein Screenshot-Test fehlschlägt, lautet die Frage nicht: „Wie bekommen wir den Test wieder grün?“, sondern: „War diese visuelle Änderung beabsichtigt?“

Handelt es sich um einen Fehler, korrigiere die Oberfläche und führe den Test erneut aus. Ist die Änderung gewollt, aktualisiere die Baseline:

$ npx playwright test --update-snapshots

Prüfe das neue Baseline-Bild anschließend im Pull Request. Behandle Snapshot-Updates wie Codeänderungen: Jemand sollte nachvollziehen können, was sich geändert hat und warum.

Screenshot-Tests in CI ausführen

Screenshot-Vergleiche reagieren empfindlich auf ihre Umgebung. Schriftarten, Betriebssystem, Browserversion, Hardware und Headless-Modus können Pixel verändern. Erzeuge und vergleiche Baselines deshalb in derselben Umgebung.

In der Praxis bedeutet das meist:

• Baseline-Snapshots einchecken, die in CI oder einem passenden lokalen Container erzeugt wurden
• das Screenshot-Projekt bei Pull Requests ausführen
• keine macOS-Baselines mit Linux-CI vergleichen, sofern du keine Abweichungen erwartest
• Playwright und die zugehörigen Browser-Binärdateien bewusst aktualisieren
• geänderte Snapshots prüfen, bevor du sie akzeptierst

Wenn ein Fehler schwer verständlich ist, helfen der HTML-Bericht oder der Trace Viewer von Playwright. Ein fehlgeschlagener Screenshot-Test braucht mehr Kontext als nur einen roten Build.

Wann gewöhnliche Screenshot-Automatisierung besser passt

Screenshot-Tests prüfen die visuelle Qualität einer eigenen Benutzeroberfläche. Sie erfüllen eine andere Aufgabe als das Sammeln von Screenshots für Freigaben, Berichte, Archive oder redaktionelle Abläufe.

Nutze gewöhnliche Screenshot-Automatisierung mit Playwright, wenn du Bilddateien für URLs brauchst.

Nutze Screenshot-Automatisierung mit Puppeteer, wenn du ein kleines, auf Chrome ausgerichtetes Skript ohne Playwright Test bevorzugst.

Nutze Website Capture in Shotomatic, wenn du URL-Listen ohne Code aufnehmen möchtest: URLs hinzufügen, Aufnahmeoptionen anpassen, Ergebnisse prüfen und Screenshots exportieren, ohne eine Testsuite zu pflegen. Für manuelle Prüfungen responsiver Screenshots kann das ausreichen. Automatische Bestanden-/Fehlgeschlagen-Tests gehören weiterhin in Playwright Test.

Häufige Fehler

• Zu große Bereiche testen: Beginne mit wichtigen Abschnitten, bevor du Ganzseiten-Baselines anlegst.
• Wechselnde Daten aufnehmen: Nutze feste Testdaten, Masken oder Styles für Inhalte, die sich bei jedem Lauf ändern.
• Snapshots ungeprüft aktualisieren: Aktualisiere Baselines erst nach der Sichtprüfung.
• Baselines auf einem Rechner erzeugen und auf einem anderen vergleichen: Halte die Rendering-Umgebung einheitlich.
• Visuelle Tests wie Verhaltenstests behandeln: Ergänze Screenshot-Tests durch gewöhnliche Assertions für Text, Rollen, Navigation und Interaktionen.

FAQ

Kann Playwright Screenshot-Tests ausführen?

Ja. Playwright Test enthält Screenshot-Prüfungen mit expect(page).toHaveScreenshot() und expect(locator).toHaveScreenshot().

Was unterscheidet Screenshot-Tests vom bloßen Speichern von Screenshots?

Beim Speichern entstehen Bilddateien. Ein Screenshot-Test vergleicht neue Aufnahmen mit freigegebenen Baselines und schlägt fehl, wenn die Abweichung den erlaubten Grenzwert überschreitet.

Wo speichert Playwright die Baselines für Screenshot-Tests?

Standardmäßig liegen die Baselines in einem Verzeichnis, das wie die Testdatei heißt und auf -snapshots endet. Den Pfad kannst du in der Playwright-Konfiguration mit snapshotPathTemplate anpassen.

Wie aktualisiere ich Screenshot-Baselines in Playwright?

Führe Playwright Test mit --update-snapshots aus, nachdem du geprüft hast, dass die visuelle Änderung beabsichtigt ist.

Sollte ich für jede Seite einen Playwright-Screenshot-Test anlegen?

Nein. Nutze Screenshot-Tests für wichtige, stabile UI-Zustände. Verhalten prüfst du besser mit gewöhnlichen Assertions; visuelle Baselines lohnen sich für Seiten oder Komponenten, bei denen Layoutänderungen relevant sind.

Quellen

Die Beispiele wurden anhand der aktuellen offiziellen Dokumentation geprüft:

• Installationsanleitung von Playwright zur Einrichtung von Playwright Test
• Anleitung zu visuellen Vergleichen für toHaveScreenshot(), Baselines, den Update-Ablauf und Vergleichsoptionen
• PageAssertions.toHaveScreenshot()-API für fullPage, mask, stylePath, maxDiffPixels, threshold und verwandte Optionen
• Assertions-Anleitung zu automatisch wiederholten Web-Assertions
• Anleitung zum Ausführen und Debuggen von Tests sowie Trace-Viewer-Anleitung zur Prüfung fehlgeschlagener Tests