Playwright-Tests für visuelle Regression

Dieses Kapitel stellt die Funktionen von Playwright für visuelles Regressionstesting vor, mit denen unerwartete UI-Änderungen durch Screenshot-Vergleich erkannt werden.


Was ist visuelles Regressionstesting

Visuelles Regressionstesting vergleicht den aktuellen Screenshot mitdem Baseline-Screenshot (Golden File), um UI-Änderungen auf der Seite durch Pixelunterschiede zu erkennen.

Wenn sich eine CSS-Änderung unerwartet auf das Layout anderer Seiten auswirkt, kann visuelles Regressionstesting dieses Problem direkt aufdecken.


expect(page).toHaveScreenshot() Seiten-Screenshot-Vergleich

Beispiel

test('EXAMPLE Homepage Visual Regression', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Erster Durchlauf: Baseline-Screenshot speichern
  // Nachfolgende Durchläufe: mit Baseline-Screenshot vergleichen
  await expect(page).toHaveScreenshot('example-homepage.png');
});

Beim ersten Durchlauf meldet Playwright einen Fehler und erstellt einen Baseline-Screenshot:

Error: A snapshot doesn't exist at example-homepage-chromium-darwin.png,
writing actual.

Beim zweiten Durchlauf wird automatisch mit dem Baseline-Screenshot verglichen.

Vollständige toHaveScreenshot-Optionen

Beispiel

await expect(page).toHaveScreenshot('homepage.png', {
  fullPage: true,                // Ganzseitiger Screenshot
  maxDiffPixelRatio: 0.01,       // 1% Pixelunterschied zulassen
  maxDiffPixels: 100,            // Bis zu 100 Pixelunterschiede zulassen
  threshold: 0.2,                // Schwellenwert für Pixelunterschiede (0~1)
  animations: 'disabled',        // Animationen deaktivieren (empfohlen)
  mask: [                        // Bestimmte Bereiche ignorieren
    page.getByText('Current Time'),
  ],
});

expect(locator).toHaveScreenshot() Element-Screenshot-Vergleich

Beispiel

test('Visuelle Regression der Navigationsleiste', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Nur den Screenshot der Navigationsleiste vergleichen
  const navbar = page.getByRole('navigation');
  await expect(navbar).toHaveScreenshot('navbar.png');
});

Golden-File-Verwaltung

Golden File generieren

Beim ersten Ausführen einer Screenshot-Assertion generiert Playwright automatisch eine Golden File und speichert sie im-snapshotsVerzeichnis neben der Testdatei:

tests/
├── example.spec.ts
└── example.spec.ts-snapshots/
    └── example-homepage-chromium-darwin.png

Der Dateiname enthält den Browser-Namen und das Betriebssystem, wodurch sichergestellt wird, dass Baselines für verschiedene Plattformen unabhängig verwaltet werden.

Golden File aktualisieren

Wenn die UI erwartete Designänderungen erfährt, müssen Sie den Baseline-Screenshot aktualisieren:

# 更新所有截图基准
npx playwright test --update-snapshots

# 只更新特定文件
npx playwright test tests/example.spec.ts --update-snapshots

Erläuterung der Optionen für den visuellen Vergleich

OptionTypeBeschreibung
maxDiffPixelRationumberZulässiges Pixel-Differenzverhältnis (0~1), Standard 0
maxDiffPixelsnumberZulässige Anzahl von Pixelunterschieden, Standard 0
thresholdnumberDifferenztoleranz pro Pixel (0~1), Standard 0.2
animationsstringOb Animationen deaktiviert werden sollen:'disabled' | 'allow'
maskLocator[]Ignorierte Bereiche (werden beim Differenzvergleich nicht berücksichtigt)

Überlegungen zur CI-Umgebung

Die Ergebnisse des Browser-Renderings werden durch Faktoren wie Betriebssystem, Browser-Version, Hardware, Energiezustand und Headless-Modus beeinflusst. Um Konsistenz zu gewährleisten, sollten Golden Files in derselben Umgebung generiert und Tests darin ausgeführt werden. Es wird empfohlen, einen Docker-Container oder dieselbe Plattform wie die CI zu verwenden, um Unterschiede auszuschließen.

Visuelles Testen in Docker

# 使用 Playwright Docker 镜像确保渲染一致性
docker run --rm -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.52.0-jammy \
  npx playwright test --update-snapshots

Best Practices für visuelles Testen

  • Golden Files auf derselben Plattform generieren und Vergleiche ausführen
  • Verwenden Sieanimations: 'disabled'um Unsicherheit durch Animationen auszuschließen
  • Verwenden Siemaskum dynamische Inhalte (wie Zeitstempel, Werbeplätze) zu ignorieren
  • Priorisieren Sie visuelle Regressionstests für kritische Seiten (Startseite, Login, Zahlung)
  • Golden Files in das Versionskontrollsystem committen
  • Verwenden Sie feste Versionen von Browsern und Betriebssystemen in CI
Andere Erweiterungen