Tests de régression visuelle sur mobile : Playwright gratuit

Les tests de régression visuelle comparent des captures de vos pages avec des images de référence approuvées, et échouent quand les pixels changent. Pour les mises en page mobiles, ils détectent ce que les tests fonctionnels ne voient pas : un bouton de menu repoussé hors d’un écran de 360 px, un titre qui passe sur trois lignes, une grille de cartes qui se désorganise à la largeur d’une tablette. Vous pouvez les exécuter gratuitement avec toHaveScreenshot() de Playwright aux viewports mobile et tablette, puis décider si un service payant vaut le coup pour les flux de relecture et le rendu multinavigateur dans le cloud.

Comment fonctionnent les tests de régression visuelle

Un test visuel comporte quatre étapes : capturer une référence, recapturer après une modification, comparer les deux images, puis laisser une personne accepter ou rejeter la différence. Les modifications acceptées deviennent la nouvelle référence.

La comparaison est ce qui distingue les outils. La comparaison de pixels (Playwright, BackstopJS) compte les pixels modifiés et échoue au-delà d’un seuil que vous fixez. Applitools compare avec sa propre IA visuelle plutôt qu’avec un décompte strict de pixels, et Percy et Chromatic sont des services hébergés avec un tableau de relecture. Tous ont besoin de pages stables : si une horloge, une publicité ou une animation change entre deux exécutions, le test échoue sans vraie raison. Une bonne partie du travail de configuration ci-dessous consiste à supprimer ce bruit.

Comparaison des outils

L’assertion intégrée de Playwright couvre le cas gratuit et auto-hébergé. En octobre 2026 :

Percy compte chaque page à chaque navigateur et à chaque largeur comme une capture : deux pages à trois largeurs mobiles et tablette dans deux navigateurs représentent déjà douze captures. Les prix et limites des offres proviennent de la page tarifaire de chaque éditeur au 25 octobre 2026, et changent souvent.

Configurer des tests visuels aux viewports mobiles

Cette configuration utilise @playwright/test 1.64 (version en vigueur au 25 octobre 2026). Elle nécessite Node.js et un site accessible depuis la machine de test, en local ou déployé.

1. Installez Playwright et ses navigateurs :

   npm init playwright@latest

2. Ajoutez des projets mobiles dans playwright.config.ts. Chaque descripteur d’appareil définit le viewport, le ratio de pixels, le user agent et le support tactile, et choisit le moteur (iPhone 15 s’exécute dans WebKit, Pixel 7 dans Chromium).

   import { defineConfig, devices } from '@playwright/test';
   
   export default defineConfig({
     testDir: './visual',
     use: { baseURL: 'http://localhost:4321' },
     expect: {
       toHaveScreenshot: { maxDiffPixelRatio: 0.01 },
     },
     projects: [
       { name: 'pixel-7', use: { ...devices['Pixel 7'] } },
       { name: 'iphone-15', use: { ...devices['iPhone 15'] } },
       { name: 'tablet', use: { browserName: 'chromium', viewport: { width: 820, height: 1180 } } },
     ],
   });

   Dans Playwright 1.64, le descripteur Pixel 7 a un viewport de 412 × 839 avec un ratio de pixels de 2,625, et iPhone 15 a 393 × 659 avec 3. Le maxDiffPixelRatio de 1 % est une valeur de départ à ajuster, pas une norme.

3. Écrivez le test. Limitez-le aux pages dont la mise en page compte le plus :

   // visual/pages.spec.ts
   import { test, expect } from '@playwright/test';
   
   const pages = ['/', '/pricing', '/blog'];
   
   for (const path of pages) {
     test(`layout ${path}`, async ({ page }) => {
       await page.goto(path);
       await page.evaluate(async () => { await document.fonts.ready; });
       await expect(page).toHaveScreenshot({
         fullPage: true,
         mask: [page.locator('[data-testid="live-date"]')],
       });
     });
   }

4. Créez les références et validez-les dans le dépôt :

   npx playwright test --update-snapshots

   Playwright enregistre un PNG par test et par projet, avec le nom du projet et la plateforme à la fin du nom de fichier (par exemple ...-iphone-15-linux.png). Validez les dossiers *-snapshots.

5. Lancez npx playwright test sur chaque pull request. Une comparaison qui échoue fait échouer le test ; ouvrez le rapport HTML avec npx playwright show-report pour voir l’échec. Si le changement est voulu, mettez à jour les références avec --update-snapshots et validez-les avec la modification du code.

Les valeurs par défaut aident : toHaveScreenshot() attend que deux captures consécutives coïncident avant de comparer, désactive les animations et transitions CSS, et masque le curseur de texte (documentation de l’API Playwright). Son option scale vaut "css" par défaut, soit un pixel d’image par pixel CSS ; une référence iPhone fait donc 393 px de large et non 1179, et les comparaisons restent rapides.

Vérifiez la mise en page avant de créer les références

Une référence enregistre l’aspect de la page au moment de la capture. Si la première capture montre déjà une mise en page mobile cassée, chaque exécution suivante défendra ce bogue. Avant de créer les références, regardez chaque page aux largeurs testées :

1. Ouvrez la page à une largeur de mobile. Mobile View Extension recharge l’onglet avec le user agent, la taille d’écran et le ratio de pixels d’un téléphone, et peut afficher deux appareils côte à côte : vous pouvez donc contrôler ensemble les mises en page téléphone et tablette d’une même URL. Il fonctionne sur localhost.
2. Faites défiler toute la page et vérifiez la navigation, les titres qui passent à la ligne, les tableaux et les éléments fixes.
3. Corrigez ce que vous trouvez, puis lancez --update-snapshots.

L’extension affiche avec le moteur de Chrome sur ordinateur et à la souris ; elle montre donc la mise en page, pas le rendu de Safari ni le comportement tactile. Le projet WebKit de Playwright couvre une partie de cet écart, et un vrai iPhone couvre le reste. Une routine plus large pour les contrôles manuels se trouve dans comment tester un design responsive, et les captures ponctuelles pour des tickets dans faire une capture d’écran mobile d’un site web.

Corriger les écarts de capture instables

Les écarts instables viennent de ce qui change entre deux exécutions ; la solution est donc de rendre ces éléments identiques à chaque fois. Voici les causes habituelles et ce qu’il faut faire :

La première ligne explique les échecs qui semblent aléatoires. La documentation de Playwright prévient que le rendu peut varier selon le système d’exploitation de l’hôte, la version, les réglages et le matériel, et la plateforme fait partie du nom de la capture pour cette raison : une référence créée sur un Mac (-darwin.png) n’est pas utilisée sur un runner Linux de CI (-linux.png). Choisissez un seul environnement pour les références. Lancer npx playwright test --update-snapshots dans la même image Docker que celle de la CI supprime cette source de différence.

Un fichier stylePath est l’endroit le plus propre pour masquer le bruit dans tous les tests :

/* visual/screenshot.css */
iframe, [data-testid="cookie-banner"] { visibility: hidden; }

import path from 'node:path';

await expect(page).toHaveScreenshot({
  stylePath: path.join(__dirname, 'screenshot.css'),
});

La même option peut figurer dans expect.toHaveScreenshot de la configuration pour s’appliquer à tous les tests.

Ce que les tests visuels ne détectent pas

Une comparaison de captures vérifie les pixels dans les moteurs que vous exécutez. Elle ne vérifie ni qu’un bouton fonctionne, ni qu’une zone tactile est assez grande, ni le comportement de la page dans le navigateur réel d’un téléphone, avec sa barre d’outils et son clavier. WebKit dans Playwright est proche de Safari, mais ce n’est pas Safari sur un iPhone. Gardez des tests fonctionnels à côté des tests visuels, et couvrez les navigateurs réels avec la liste de contrôle des tests multinavigateurs.

Gardez la suite réduite. Chaque page, projet et état multiplie le nombre d’images à relire. Trois à dix gabarits clés (accueil, une liste, une page de détail, un formulaire) à deux tailles de mobile et une taille de tablette permettent de limiter la relecture à quelques dizaines d’images par exécution. Ce nombre est un point de départ à ajuster (un choix de design), non une règle.

Questions fréquentes

Les tests de régression visuelle sont-ils gratuits ?

Oui, avec des outils open source. toHaveScreenshot() de Playwright et BackstopJS tournent en local et dans votre CI sans frais. Des services payants comme Percy, Chromatic et Applitools ajoutent un rendu hébergé et des tableaux de relecture, et Percy et Chromatic ont des offres gratuites de 5 000 captures ou instantanés par mois à octobre 2026.

Quelle différence entre tests visuels et tests de captures d’écran ?

Les deux prennent une capture et la comparent à une référence approuvée. La différence tient à la comparaison : Playwright et BackstopJS comptent les pixels modifiés, tandis qu’Applitools utilise l’IA visuelle (voir le tableau des outils ci-dessus).

Pourquoi mes captures Playwright échouent-elles en CI et réussissent-elles en local ?

Parce que les références ont été créées sur un autre système d’exploitation ou une autre version de navigateur. Playwright inclut la plateforme dans le nom du fichier de capture, et les polices et l’anticrénelage diffèrent entre macOS et Linux. Créez les références dans la même image Docker que celle de la CI.

Comment ignorer le contenu dynamique dans les tests visuels ?

Utilisez l’option mask pour couvrir des éléments comme les dates et les publicités, ou masquez-les avec une feuille de style stylePath. Pour des zones entières qui changent, capturez un élément stable au lieu de la page complète.