Playwright : obtenir des tests stables à 99%

Un test Playwright qui échoue une fois sur dix n’est pas un test à supprimer — c’est un signal à investiguer. Il peut révéler un test fragile, une hypothèse d’environnement implicite, ou un comportement de l’application sous certaines conditions que personne n’avait formalisé. Atteindre 99% de stabilité n’est pas une question de configuration : c’est le résultat de décisions d’architecture prises à chaque niveau de la suite. Locators, isolation, réseau, CI, fixtures — chaque couche contribue ou sabote la stabilité. Cet article documente les leviers qui font la différence, dans l’ordre d’impact réel.

Pourquoi les tests Playwright sont instables par défaut

Playwright est un outil déterministe. Le navigateur, lui, ne l’est pas. Un test instable est presque toujours le symptôme d’une hypothèse implicite sur l’état du système — une hypothèse qui tient en local mais qui est violée en CI, sous charge, ou dans un ordre d’exécution différent. Les causes racines se regroupent en quatre catégories. Chacune a ses solutions. Aucune ne se résout avec un waitForTimeout(2000).

Levier n°1 — Les locators stables

Le choix du locator est la décision la plus impactante sur la stabilité à long terme. Un locator fragile transforme chaque refactor front en dette de tests. Playwright expose une hiérarchie de locators, du plus stable au plus fragile :

// ✗ Fragile — couplé à l'implémentation CSS
await page.locator('.btn-primary.checkout > span:first-child').click();

// ✗ Fragile — couplé à la structure DOM
await page.locator('xpath=//div[3]/button[1]').click();

// ✗ Fragile — dépend de l'ordre de rendu
await page.locator('button').nth(2).click();

// ✓ Stable — sémantique, accessible, résistant aux refactors CSS
await page.getByRole('button', { name: 'Valider la commande' }).click();

// ✓ Stable — contrat explicite avec le front-end
await page.getByTestId('checkout-submit').click();

// ✓ Stable — texte visible, couplé au comportement pas à l'implémentation
await page.getByText('Valider la commande').click();

Hiérarchie recommandée (cohérente avec les Testing Library guidelines) :

• getByRole — premier choix. Teste ce que l’utilisateur perçoit et ce que les lecteurs d’écran annoncent. Un refactor CSS ne le casse pas.
• getByLabel, getByPlaceholder — pour les champs de formulaire. Couplé à l’accessibilité, pas à la structure.
• getByText — pour les contenus textuels stables qui ne changeront pas à chaque sprint.
• getByTestId — contrat explicite via data-testid, quand les options sémantiques ne suffisent pas. Documente l’intention côté front.
• CSS / XPath — dernier recours. À documenter avec un commentaire expliquant pourquoi les options stables ne convenaient pas.

Levier n°2 — Les attentes explicites

Le waitForTimeout est un anti-pattern. Il encode une durée au lieu d’un état — durée qui tient sur la machine du développeur mais qui est systématiquement trop courte ou trop longue en CI selon la charge du runner. La règle absolue : attendre un état, jamais une durée.

// ✗ Anti-pattern — durée arbitraire
await page.waitForTimeout(2000);
await page.click('#submit');

// ✓ Attendre la visibilité de l'élément cible
await page.getByRole('button', { name: 'Valider' }).waitFor({ state: 'visible' });

// ✓ Attendre la réponse réseau
await page.waitForResponse(
  res => res.url().includes('/api/products') && res.status() === 200
);

// ✓ Attendre un état DOM — auto-retrying jusqu'au timeout
await expect(page.getByTestId('product-grid')).toBeVisible();
await expect(page.getByRole('progressbar')).toBeHidden();

// ✓ Attendre une navigation
await page.waitForURL('/confirmation**');

Les assertions Playwright (expect) sont auto-retrying par défaut. Elles attendent que la condition soit vraie plutôt que de la vérifier instantanément — c’est le comportement correct. Calibrer le timeout global en fonction du runner CI le plus lent, pas de la machine de développement.

// playwright.config.ts
export default defineConfig({
  expect: {
    timeout: 10_000,       // 10s par assertion (défaut : 5s)
  },
  use: {
    actionTimeout: 10_000,   // timeout par action (click, fill…)
    navigationTimeout: 30_000,
  },
});

Levier n°3 — L’isolation de l’état

Un test qui dépend de l’état laissé par un test précédent n’est pas un test — c’est une transaction dans une séquence couplée. L’isolation est la propriété la plus structurellement importante d’une suite stable. Elle se décline à trois niveaux.

Isolation du stockage navigateur

// Contexte navigateur vierge par test (comportement par défaut)
export default defineConfig({
  use: { storageState: undefined },
});

// Pour les tests nécessitant une authentification :
// générer le state une fois (project "setup"), le réutiliser en lecture seule
export default defineConfig({
  projects: [
    { name: 'setup', testMatch: '**/auth.setup.ts' },
    {
      name: 'authenticated',
      use: { storageState: '.auth/user.json' },
      dependencies: ['setup'],
    },
  ],
});

Isolation de la base de données

// Reset via endpoint de test — fixture connue avant chaque test
test.beforeEach(async ({ request }) => {
  await request.post('/api/test/reset', {
    data: { fixture: 'checkout-flow' }
  });
});

// Alternative : cleanup après chaque test passé uniquement
test.afterEach(async ({ request }, testInfo) => {
  if (testInfo.status !== 'passed') return; // garder l'état sur échec pour debug
  await request.delete(`/api/test/orders/${orderId}`);
});

Levier n°4 — Le contrôle du réseau

Tester contre des services externes réels est une source de flakiness structurelle — le service peut être lent, indisponible, ou retourner des données variables. La solution n’est pas de retenter — c’est d’intercepter. page.route() est l’outil central.

// Mocker une réponse API avec fixture
await page.route('**/api/products**', async route => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify(productFixture),
  });
});

// Simuler une erreur — impossible à reproduire en conditions réelles
await page.route('**/api/payment**', route =>
  route.fulfill({ status: 503 })
);

// Simuler une latence réseau dégradée
await page.route('**/api/search**', async route => {
  await new Promise(r => setTimeout(r, 3000));
  await route.continue();
});

// Enregistrer les requêtes pour assertions sur le comportement réseau
const calls: string[] = [];
await page.route('**/api/**', route => {
  calls.push(route.request().url());
  route.continue();
});

Le mocking réseau a une double valeur : il rend les tests déterministes et il permet de tester des scénarios d’erreur impossibles à reproduire en conditions réelles — timeout, 503, réponse malformée, latence extrême. Ces scénarios sont souvent les plus critiques à valider.

Levier n°5 — Les animations et le timing visuel

Les animations CSS sont une source de flakiness sous-estimée. Un clic pendant une transition d’entrée peut toucher un élément dans un état intermédiaire — techniquement visible, mais pas encore à la position attendue par Playwright. Deux approches complémentaires.

// Option 1 — Désactiver les animations globalement en test
export default defineConfig({
  use: {
    reducedMotion: 'reduce',  // réduit les animations à leur état final
  },
});

// Option 2 — Forcer via CSS injecté (plus radical)
await page.addStyleTag({
  content: `*, *::before, *::after {
    animation-duration: 0ms !important;
    transition-duration: 0ms !important;
  }`,
});

// Option 3 — Attendre l'état stable du composant animé
const modal = page.getByRole('dialog');
await expect(modal).toBeVisible();
await expect(modal).not.toHaveClass(/animating/);
await modal.getByRole('button', { name: 'Confirmer' }).click();

Levier n°6 — La configuration CI

Un test parfaitement écrit en local peut être instable en CI pour des raisons d’environnement indépendantes du test lui-même. Les trois pièges les plus courants :

// playwright.config.ts — configuration adaptée CI/local
export default defineConfig({
  workers: process.env.CI ? 2 : '50%',
  retries: process.env.CI ? 1 : 0,
  reporter: process.env.CI
    ? [['github'], ['html', { open: 'never' }]]
    : 'list',
  use: {
    trace: 'on-first-retry',
    video: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

Mesurer la stabilité — le taux de flakiness

On ne peut pas améliorer ce qu’on ne mesure pas. Le taux de flakiness se calcule sur un historique d’exécutions — pas sur le dernier run.

Taux de flakiness = (runs avec résultat incohérent) / (total des runs) × 100

Exemple — 100 exécutions du test "checkout flow" :
  ├── 92 passes au premier run
  ├──  6 fails sans retry
  └──  2 passes après retry  ← résultats incohérents

Flakiness = (6 + 2) / 100 × 100 = 8%   → objectif : ≤ 1%

Outils pour suivre cette métrique dans le temps :

• Playwright HTML report — intègre les retries et les tests instables sur la dernière exécution. Point de départ.
• GitHub Actions + JUnit XML — agréger les résultats sur 30 jours avec un script parsant les XML produits par Playwright. Pas d’outil externe requis.
• Currents.dev / BuildPulse — services dédiés au tracking de flakiness sur l’historique CI, avec alertes et tendances par test. Utile dès que la suite dépasse 500 tests.

Règle de priorisation : traiter en premier les tests à forte flakiness sur les chemins critiques — checkout, authentification, onboarding. Un test instable sur un flow critique a un coût asymétrique : chaque faux négatif déclenche une investigation et érode la confiance dans toute la suite.

Architecture — les fixtures comme fondation

Les fixtures Playwright sont le mécanisme le plus sous-utilisé pour écrire des tests stables et maintenables. Elles encapsulent la mise en place d’état, le teardown, et les dépendances — de façon composable et sans duplication.

// fixtures/index.ts
import { test as base } from '@playwright/test';
import type { Page } from '@playwright/test';

type Fixtures = {
  authenticatedPage: Page;
  productInCart: { id: string; name: string };
};

export const test = base.extend<Fixtures>({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
    await page.getByLabel('Mot de passe').fill(process.env.TEST_USER_PASS!);
    await page.getByRole('button', { name: 'Se connecter' }).click();
    await page.waitForURL('/dashboard');
    await use(page);  // ← le test s'exécute ici, teardown après
  },
});

// tests/checkout.spec.ts — setup invisible, test lisible
import { test, expect } from '../fixtures';

test('valider une commande', async ({ authenticatedPage: page }) => {
  // page est déjà authentifiée — pas de beforeEach, pas de duplication
});

Les fixtures composent : une fixture peut dépendre d’une autre, Playwright gère l’ordre d’initialisation et le teardown. C’est le pattern qui permet d’écrire des tests lisibles sans duplication de setup — et de changer le comportement d’authentification en un seul endroit.

Nuances — ce que la stabilité à 99% ne garantit pas

Un objectif de stabilité à 99% est juste — mais il peut masquer des problèmes de conception si on n’est pas précis sur ce qu’on mesure.

Matrice diagnostic — symptôme × cause × solution

Symptôme	Cause probable	Solution
Passe en local, échoue en CI	Timeout trop court, ressources limitées, dépendance externe non mockée	Calibrer timeouts sur CI, mocker les APIs tierces
Échoue aléatoirement partout	État partagé, ordre d’exécution, race condition applicative	Isolation par test, beforeEach reset, waitFor explicite — investiguer si bug applicatif
Échoue uniquement en parallèle	Port réseau ou base de données partagés entre workers	Isolation par worker, port dynamique, schéma DB par worker
Échoue après un refactor CSS	Locator couplé à l’implémentation visuelle	Migrer vers getByRole / getByTestId
Échoue sur les éléments animés	Interaction pendant une transition CSS	reducedMotion: 'reduce', attendre l’état stable du composant
Screenshots différents local / CI	Fonts système, rendu headless, résolution d’écran	Générer et versionner les snapshots de référence exclusivement en CI

Conclusion

La stabilité à 99% n’est pas un paramètre de configuration — c’est le résultat de décisions d’architecture prises à chaque niveau de la suite : choix de locators sémantiques, isolation complète par test, contrôle du réseau, calibrage CI sur le runner réel, fixtures composables. Chaque couche qui reste instable coûte du temps d’investigation, érode la confiance des développeurs, et transforme les tests en bruit plutôt qu’en signal.

Le signe d’une suite de tests mature n’est pas l’absence d’échecs — c’est la certitude que chaque échec signale un vrai problème dans le code. Quand les développeurs arrêtent de relancer les tests en espérant que ça passe, la suite fait son travail.