Test Visuel avec Playwright : Le Tutoriel Complet
Playwright de Microsoft inclut depuis la version 1.22 une fonctionnalité native de test visuel : la méthode toHaveScreenshot(). Elle permet de capturer des screenshots et de les comparer automatiquement à des images de référence, sans plugin externe.
C'est l'une des options les plus solides pour les équipes de développement qui veulent ajouter des tests visuels à leur stack existante. Ce tutoriel couvre l'installation, la configuration, les bonnes pratiques et l'intégration CI/CD.
Installation et premier test
La mise en place est rapide si vous avez déjà un projet Node.js :
npm install -D @playwright/test
npx playwright install
Créez ensuite votre premier test visuel dans tests/visual.spec.ts :
import { test, expect } from '@playwright/test';
test('homepage visual test', async ({ page }) => {
await page.goto('https://votre-site.com');
await expect(page).toHaveScreenshot('homepage.png');
});
La première exécution génère la baseline (l'image de référence). Les exécutions suivantes comparent le screenshot actuel à cette baseline et signalent les différences.
# Première fois : générer les baselines
npx playwright test --update-snapshots
# Ensuite : comparer
npx playwright test
C'est aussi simple que ça pour démarrer. La complexité arrive avec les cas réels.
Configurer la tolérance
Par défaut, Playwright signale la moindre différence d'un pixel. En pratique, il faut configurer des seuils de tolérance pour éviter les faux positifs.
Dans playwright.config.ts :
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
maxDiffPixelRatio: 0.01, // 1% de pixels différents tolérés
animations: 'disabled', // Désactive les animations CSS
scale: 'device', // Gère les écrans Retina
},
},
});
Vous pouvez aussi ajuster par test :
// Page statique : seuil strict
await expect(page).toHaveScreenshot('landing.png', {
maxDiffPixelRatio: 0.001
});
// Dashboard avec graphiques : seuil souple
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixelRatio: 0.05,
mask: [page.locator('.chart')]
});
Gérer le contenu dynamique
Le contenu dynamique (dates, publicités, avatars, compteurs) est le cauchemar des tests visuels. Playwright propose trois solutions :
Masquer les zones dynamiques — la plus courante :
await expect(page).toHaveScreenshot({
mask: [
page.locator('.ad-banner'),
page.locator('.timestamp'),
page.locator('.user-avatar')
]
});
Remplacer le contenu — pour figer des valeurs :
await page.evaluate(() => {
document.querySelector('.date').textContent = '01/01/2026';
});
await expect(page).toHaveScreenshot();
Cacher via CSS — pour les éléments qu'on ne veut pas du tout voir :
await page.addStyleTag({
content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();
Stabiliser les tests
Un test visuel qui passe un jour et échoue le lendemain sans raison est inutilisable. Voici comment garantir la stabilité :
test('stable visual test', async ({ page }) => {
await page.goto('https://votre-site.com');
// Attendre que le réseau soit calme
await page.waitForLoadState('networkidle');
// Attendre le chargement des polices
await page.evaluate(() => document.fonts.ready);
// Attendre un élément critique
await page.waitForSelector('.hero-image', { state: 'visible' });
await expect(page).toHaveScreenshot();
});
Et pour désactiver manuellement les animations quand l'option globale ne suffit pas :
await page.addStyleTag({
content: `
*, *::before, *::after {
animation-duration: 0s !important;
transition-duration: 0s !important;
}
`
});
Tester plusieurs résolutions
Playwright facilite le test multi-résolution via les projets :
// 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'] },
},
]
Chaque projet génère ses propres baselines. Un test s'exécute donc trois fois, sur trois résolutions, avec trois jeux de screenshots.
Intégration CI/CD
L'intégration dans GitHub Actions est directe :
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/
Quand un test échoue, Playwright génère trois images : la baseline (attendue), le screenshot actuel, et un diff avec les différences en rouge. Le rapport HTML (npx playwright show-report) les affiche côte à côte.
Les limites de l'approche Playwright
Playwright est excellent pour les équipes de développement, mais il a des limites qu'il faut connaître :
Compétences obligatoires : il faut maîtriser TypeScript/JavaScript, les sélecteurs, et la configuration de projet. Ce n'est pas accessible aux QA non-développeurs.
Pas de dashboard : il n'y a pas d'interface de revue intégrée. La gestion des baselines se fait via le terminal et le système de fichiers. En équipe, ça devient vite complexe.
Faux positifs : la comparaison pixel reste basique. Les différences d'anti-aliasing entre navigateurs, les variations de rendu de fonts entre OS — tout ça génère du bruit qu'il faut gérer manuellement avec des masks et des seuils.
Maintenance : chaque changement d'UI intentionnel nécessite de regénérer les baselines (--update-snapshots). Sur un projet avec 200 tests visuels et 3 navigateurs, ça fait 600 baselines à gérer.
Pour les équipes qui veulent du test visuel sans ces contraintes techniques, les solutions no-code comme Delta-QA offrent une alternative : même résultat (détection des régressions visuelles) sans écrire de code, sans gérer de baselines manuellement, et avec zéro faux positif grâce à un algorithme de comparaison structurelle en 5 passes plutôt qu'une comparaison pixel brute.
FAQ
Playwright est-il gratuit pour les tests visuels ?
Oui, entièrement. toHaveScreenshot() est intégré nativement dans Playwright, qui est open source et maintenu par Microsoft. Pas de licence, pas de limite de screenshots.
Combien de temps pour mettre en place les tests visuels Playwright ?
Si vous maîtrisez déjà Playwright, comptez quelques heures pour configurer et écrire vos premiers tests. Si vous partez de zéro (installation, apprentissage TypeScript, configuration CI), comptez 2 à 3 jours.
Playwright ou Cypress pour les tests visuels ?
Playwright a l'avantage d'intégrer le test visuel nativement (toHaveScreenshot()), tandis que Cypress nécessite un plugin externe. Playwright supporte aussi trois moteurs de navigateurs (Chromium, Firefox, WebKit) contre un seul pour Cypress (Chromium-based). Pour le test visuel spécifiquement, Playwright est le meilleur choix open source.
Peut-on utiliser Playwright et Delta-QA ensemble ?
Oui. L'approche recommandée est d'utiliser Playwright pour les tests visuels complexes (avec logique conditionnelle, données dynamiques) et Delta-QA pour les vérifications visuelles de routine maintenues par l'équipe QA. Chaque outil couvre un besoin différent.
Playwright offre une base solide pour les tests visuels automatisés. Pour les équipes de développement qui maîtrisent TypeScript, c'est probablement la meilleure option open source disponible en 2026. L'important est de bien configurer les seuils de tolérance et de stabiliser les tests dès le départ pour éviter les faux positifs.
Essayer Delta-QA Gratuitement →
Article précédent : Du Test Manuel au Test Automatisé : Guide pour les QA Non-Développeurs