Tests de régression visuelle Playwright

Ce chapitre présente les fonctionnalités de test de régression visuelle de Playwright, qui détectent les changements inattendus de l'interface utilisateur grâce à la comparaison de captures d'écran.

Qu'est-ce que le test de régression visuelle

Le test de régression visuelle compare la capture d'écran actuelle avecla capture d'écran de référence (Golden File)pour détecter les changements d'interface utilisateur sur la page par différences de pixels.

Lorsqu'une modification CSS affecte de manière inattendue la mise en page d'autres pages, le test de régression visuelle peut détecter directement ce problème.

expect(page).toHaveScreenshot() Comparaison de capture d'écran de page

Exemple

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

  // Première exécution : enregistrer la capture d'écran de référence
  // Exécutions suivantes : comparer avec la capture d'écran de référence
  await expect(page).toHaveScreenshot('example-homepage.png');
});

Lors de la première exécution, Playwright signalera une erreur et générera une capture d'écran de référence :

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

Lors de la deuxième exécution, il la comparera automatiquement à la capture d'écran de référence.

Options complètes de toHaveScreenshot

Exemple

await expect(page).toHaveScreenshot('homepage.png', {
  fullPage: true,                // Capture d'écran pleine page
  maxDiffPixelRatio: 0.01,       // Autoriser 1% de différence de pixels
  maxDiffPixels: 100,            // Autoriser jusqu'à 100 différences de pixels
  threshold: 0.2,                // Seuil de différence de pixels (0~1)
  animations: 'disabled',        // Désactiver les animations (recommandé)
  mask: [                        // Ignorer des zones spécifiques
    page.getByText('Current Time'),
  ],
});

expect(locator).toHaveScreenshot() Comparaison de capture d'écran d'élément

Exemple

test('Régression visuelle de la barre de navigation', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Comparer uniquement la capture d'écran de la barre de navigation
  const navbar = page.getByRole('navigation');
  await expect(navbar).toHaveScreenshot('navbar.png');
});

Gestion des fichiers de référence

Générer un fichier de référence

Lors de la première exécution d'une assertion de capture d'écran, Playwright génère automatiquement un fichier de référence et l'enregistre dans le-snapshotsrépertoire à côté du fichier de test :

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

Le nom du fichier contient le nom du navigateur et le système d'exploitation, ce qui garantit que les références de base pour différentes plateformes sont gérées indépendamment.

Mettre à jour le fichier de référence

Lorsque l'interface utilisateur subit des modifications de conception attendues, vous devez mettre à jour la capture d'écran de référence :

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

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

Explication des options de comparaison visuelle

OptionTypeDescription
maxDiffPixelRationombreRatio de différence de pixels autorisé (0~1), par défaut 0
maxDiffPixelsnombreNombre autorisé de différences de pixels, par défaut 0
thresholdnombreTolérance de différence par pixel (0~1), par défaut 0.2
animationsstringIndique s'il faut désactiver les animations :'disabled' | 'allow'
maskLocator[]Zones ignorées (non prises en compte lors de la comparaison des différences)

Considérations relatives à l'environnement CI

Les résultats de rendu du navigateur sont affectés par des facteurs tels que le système d'exploitation, la version du navigateur, le matériel, l'état d'alimentation et le mode headless. Pour garantir la cohérence, générez les fichiers de référence et exécutez les tests dans le même environnement. Il est recommandé d'utiliser un conteneur Docker ou la même plateforme que la CI pour éliminer les différences.

Tests visuels dans Docker

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

Bonnes pratiques pour les tests visuels

  • Générer les fichiers de référence et exécuter les comparaisons sur la même plateforme
  • Utiliseranimations: 'disabled'pour éliminer l'incertitude liée aux animations
  • Utilisermaskpour ignorer le contenu dynamique (comme les horodatages, les emplacements publicitaires)
  • Prioriser les tests de régression visuelle pour les pages critiques (page d'accueil, connexion, paiement)
  • Commiter les Golden Files dans le système de contrôle de version
  • Utiliser des versions fixes de navigateurs et de systèmes d'exploitation dans CI
Autres extensions