Playwright, notre outil de tests end-to-end

Les navigateurs Playwright (Chromium, Firefox, WebKit) pèsent plusieurs centaines de mégaoctets et n'ont rien à faire dans les dépendances du projet. Ils ne servent qu'à l'exécution des tests. Deux approches selon le contexte du projet.

Pourquoi un job CI dédié dans les deux cas ?

• Les tests E2E sont plus lents que les tests unitaires : les isoler évite de bloquer le pipeline sur un job mixte
• Les navigateurs ne sont téléchargés ou démarrés que si le job E2E est déclenché, pas à chaque yarn install

Cas 1 : image Docker applicative existante (Symfony + Node)

Le runner utilise déjà une image Docker personnalisée pour le projet. Il faut alors télécharger le navigateur en début de job, juste avant de lancer les tests :

variables:
  # Redirige l'install des binaires Playwright vers un dossier du projet pour pouvoir le mettre en cache GitLab CI
  PLAYWRIGHT_BROWSERS_PATH: "$CI_PROJECT_DIR/.playwright-browsers"

e2e:
  stage: test
  when: manual
  artifacts:
    when: on_failure
    expire_in: 2 days
    paths:
      - test-results/  # screenshots, videos et traces générés par Playwright en cas d'échec
  cache:
    - key: "${CI_PROJECT_ID}_cache"
      paths:
        - node_modules/
    - key: "${CI_PROJECT_ID}_playwright_browsers"
      paths:
        - .playwright-browsers/
  script:
    - yarn install
    - yarn playwright install chromium --with-deps
    - yarn test:e2e:ci

L'option --with-deps installe également les dépendances système requises par Chromium (librairies GTK, NSS...), indispensables sur les runners CI qui partent d'une image Linux/Node minimale.

Cas 2 : projet front Node.js (Vue.js, React...) — image officielle Playwright

Microsoft publie une image Docker officielle avec Chromium, Firefox et WebKit déjà installés et leurs dépendances système pré-configurées. C'est l'approche recommandée pour les projets full front : aucune étape playwright install dans le script, le job démarre directement sur yarn install puis les tests.

La version de l'image doit correspondre exactement à la version de @playwright/test dans package.json.

e2e:
  stage: test
  when: manual
  artifacts:
    when: on_failure
    expire_in: 2 days
    paths:
      - test-results/
  image: mcr.microsoft.com/playwright:v1.59.1-noble
  script:
    - yarn install
    - yarn test:e2e:ci

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:ci": "playwright test --reporter list",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:debug": "playwright test --debug",
    "test:e2e:codegen": "playwright codegen http://localhost:8080"
  }
}

• test:e2e : lance tous les tests E2E en mode headless sur le poste du développeur. Le reporter par défaut génère un rapport HTML complet à l'issue de l'exécution : détail de chaque test, captures d'écran, traces, et bouton "Copy prompt" sur les tests en échec.
• test:e2e:ci : variante pour la CI. L'option --reporter list remplace le rapport HTML par une sortie stdout ligne par ligne, adaptée aux logs des runners GitLab CI qui ne peuvent pas ouvrir un fichier HTML.
• test:e2e:ui : ouvre l'interface graphique de Playwright. Elle permet d'explorer les tests, de les rejouer un par un, de voir les captures d'écran et les traces d'exécution. Indispensable pour comprendre pourquoi un test échoue.
• test:e2e:debug : lance les tests avec le Playwright Inspector ouvert. L'exécution est mise en pause à chaque étape pour inspecter le DOM, les sélecteurs et l'état de la page. Utile pour déboguer un test précis plutôt que de relancer toute la suite.
• test:e2e:codegen : lance le mode enregistrement sur http://localhost:8080. Playwright ouvre un navigateur et génère automatiquement le code de test correspondant à chaque action effectuée dans l'interface. Point de départ idéal pour créer un nouveau test sans écrire le sélecteur à la main.

Il y a 2 manières de faire :

Cibler directement le fichier de la spec :

yarn test:e2e tests/e2e/specs/parcours_simple.spec.js

Cette version de la commande doit être ajoutée en tête du fichier de spec en commentaire pour simplifier l'exécution du test lors de sa rédaction ou modification.

Ou avec un pattern glob si on souhaite matcher par nom :

yarn test:e2e --grep "Complétion du parcours simple"

--grep filtre par nom de test.describe ou de test(), pratique pour cibler un test précis dans un fichier.

Ces deux formes d'isolation (chemin de fichier et --grep) fonctionnent aussi avec test:e2e:ui : l'interface graphique s'ouvrira en n'affichant que les tests correspondants, ce qui accélère la navigation quand la suite complète est volumineuse.

Les locators sont la pièce centrale du système d'attente automatique et de relance (auto-waiting et retry-ability) de Playwright. Concrètement, un locator représente une façon de trouver un ou plusieurs éléments sur la page à n'importe quel moment : à chaque action, Playwright interroge le DOM à nouveau plutôt que de s'appuyer sur une référence capturée au départ.

Choisir le bon locator est important car les deux objectifs d'un bon test E2E sont parfois en tension : représenter au plus près ce que l'utilisateur perçoit et interagi, tout en garantissant un test stable qui ne casse pas à chaque refactoring mineur du HTML.

Recommandation Playwright & SmartBooster : getByRole() est la façon la plus proche de ce que voient l'utilisateur et les technologies d'assistance (lecteurs d'écran). C'est le point de départ par défaut pour tout élément interactif.

Si le besoin de votre test est plus fin, voici l'ordre de priorité recommandé :

Priorité	Locator	Quand l'utiliser
1	getByRole()	Tout élément interactif : bouton, lien, champ, case à cocher. Correspond aux attributs d'accessibilité implicites et explicites.
2	getByLabel()	Champs de formulaire associés à un <label>. Reflète exactement ce que l'utilisateur lit avant de saisir.
3	getByPlaceholder()	Inputs sans label visible mais avec un placeholder explicite.
4	getByText()	Éléments non interactifs (div, span, p) identifiés par leur contenu textuel.
5	getByAltText()	Images et éléments avec un attribut alt significatif.
6	getByTitle()	Éléments portant un attribut title (info-bulle). Usage peu fréquent.
7	getByTestId()	Quand aucun locator sémantique ne suffit, ou quand la stabilité du test prime. Nécessite d'ajouter data-testid dans le code source de l'élément.

getByTestId() pour la stabilité maximale : tester via un attribut data-testid est la méthode la plus résistante aux changements. Même si le texte du bouton ou son rôle évolue, le test passe. En contrepartie, ce locator ne reflète pas ce que l'utilisateur voit réellement. À réserver aux cas où le rôle ou le texte ne suffisent pas, ou quand la stabilité prime sur la lisibilité du test.

Playwright gère nativement Chromium, Firefox et WebKit (le moteur de Safari) via la clé projects dans playwright.config.ts. Chaque projet est un navigateur indépendant : la même suite de tests s'exécute sur les trois moteurs sans modifier une ligne de code de test.

Les binaires Chromium, Firefox et WebKit sont téléchargés par Playwright lui-même (playwright install). Edge en revanche repose sur le binaire du navigateur installé sur la machine (via channel: 'msedge') et n'est donc pas disponible sur les runners CI Linux standards, d'où son exclusion par défaut.

projects: [
  // Edge réutilise le binaire Chromium (pas d'install séparée), mais nécessite
  // Edge installé sur la machine avec channel: 'msedge'
  // { name: 'edge', use: { ...devices['Desktop Edge'] } },
  { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
  { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
]

Quand un test échoue en mode CLI, Playwright génère automatiquement un rapport HTML et propose de l'ouvrir dans le navigateur. Sur la page du rapport, chaque test en échec dispose d'un bouton "Copy prompt" : en cliquant dessus, Playwright copie dans le presse-papiers un prompt structuré contenant toutes les informations liées à l'erreur (message d'erreur, stack trace, captures d'écran, étapes ayant échoué...).

Ce prompt peut être collé directement dans Claude Code pour obtenir un premier diagnostic sans avoir à extraire manuellement les logs. Claude Code peut identifier la cause probable de l'échec et, si l'erreur est dans le code de test lui-même (mauvais sélecteur, assertion incorrecte, ordre d'étapes inadapté), proposer un début de correction applicable immédiatement.

getByRole('spinbutton') est bien le locator correct pour un <input type="number">. Ce rôle n'est pas inventé par Playwright : il correspond au rôle ARIA implicite de tous les champs numériques, tel que défini par la spec WAI-ARIA. Un lecteur d'écran annoncera ce champ comme un "spinbutton" (zone de saisie numérique incrémentale) à ses utilisateurs.

Conformément à l'ordre de priorité des locators décrit plus haut, getByRole est le sélecteur à privilégier car il reflète ce que l'utilisateur et les technologies d'assistance perçoivent réellement. Le codegen suit donc la bonne pratique en proposant ce rôle plutôt qu'un sélecteur CSS fragile comme input[type="number"].

Intercepter les appels réseau avec page.route() permet de substituer la réponse d'une API par une donnée contrôlée, sans toucher au serveur réel. Trois raisons principales justifient cette pratique :

• Éviter le spam des services tiers : une suite E2E qui tourne en CI peut déclencher des dizaines d'appels vers une API de géolocalisation, d'envoi d'email ou de paiement. Le mock isole le test de ces effets de bord et garanti de ne pas se retrouver blacklisté.
• Indépendance vis-à-vis de l'uptime externe : si l'API tierce est en maintenance ou ralentit, le test ne doit pas échouer pour une raison qui ne lui appartient pas.
• Contrôle du format de réponse : définir la réponse à l'avance permet de tester des cas précis (ville trouvée, liste vide, erreur 500...) sans dépendre des données réelles du service.

page.route(pattern, handler) intercepte toutes les requêtes dont l'URL correspond au pattern glob fourni. Quand une requête correspond, le handler reçoit un objet route et peut appeler route.fulfill() pour retourner une réponse simulée directement au navigateur, sans qu'aucun appel réseau réel ne soit émis.

Ordre impératif : page.route() doit être enregistré avant l'action qui déclenche l'appel API. Playwright enregistre les handlers dans l'ordre et les applique dès qu'une requête correspondante est émise. Un handler ajouté après l'appel ne sera jamais exécuté pour cette requête.

// Le mock est déclaré EN PREMIER, avant toute interaction avec la page
await page.route('**/geographic/cities/**', route => route.fulfill({
  json: { cities: [{ postalCode: '69001', name: 'LYON 01' }] }
}))

// L'action utilisateur qui déclenche l'appel API vient ensuite
await page.getByPlaceholder('Code postal ou nom de ville').pressSequentially('69001')

Le pattern **/geographic/cities/** utilise la syntaxe glob : ** correspond à n'importe quel segment d'URL, ce qui permet d'intercepter la route quelle que soit l'origine ou les paramètres de chemin autour du segment ciblé.

route.fulfill({ json: ... }) sérialise automatiquement l'objet en JSON et positionne le header Content-Type: application/json.

Playwright expose une API native page.coverage basée sur le Chrome DevTools Protocol. Elle collecte les données de couverture JavaScript directement dans le navigateur pendant l'exécution des tests, sans modifier le build.

Contrainte majeure : Chromium uniquement. page.coverage n'est pas disponible sur Firefox ni WebKit. Le coverage E2E est donc limité au projet chromium de Playwright, ce qui est suffisant car le coverage mesure quels chemins de code sont exercés — pas la compatibilité cross-browser.

Dépendances

yarn add -D v8-to-istanbul nyc

• v8-to-istanbul : convertit les données V8 brutes retournées par stopJSCoverage() en format Istanbul
• nyc : lit les fichiers Istanbul dans .nyc_output/ et génère les rapports finaux (HTML, lcov, cobertura)

Fixture auto (tests/e2e/fixtures.js)

Le coverage est collecté via une fixture auto qui s'exécute autour de chaque test sans modifier les specs. Elle ne s'active que lorsque la variable d'environnement COVERAGE=true est présente.

import { test as base } from '@playwright/test'
import { writeFileSync, mkdirSync } from 'node:fs'
import { randomUUID } from 'node:crypto'
import { resolve } from 'node:path'
import v8toIstanbul from 'v8-to-istanbul'

export const test = base.extend({
  collectCoverage: [async ({ page }, use) => {
    if (process.env.COVERAGE) {
      await page.coverage.startJSCoverage({ resetOnNavigation: false })
    }
    await use()
    if (!process.env.COVERAGE) return
    const entries = await page.coverage.stopJSCoverage()
    const istanbulCoverage = {}
    for (const entry of entries) {
      if (!entry.url.includes('/src/') || !entry.source) continue
      const filePath = resolve(process.cwd(), entry.url.replace(/^https?:\/\/[^/]+\//, ''))
      const converter = v8toIstanbul(filePath, 0, { source: entry.source })
      await converter.load()
      converter.applyCoverage(entry.functions)
      Object.assign(istanbulCoverage, converter.toIstanbul())
    }
    if (Object.keys(istanbulCoverage).length > 0) {
      mkdirSync('.nyc_output', { recursive: true })
      writeFileSync(`.nyc_output/${randomUUID()}.json`, JSON.stringify(istanbulCoverage))
    }
  }, { auto: true }]
})

export { expect } from '@playwright/test'

Points clés :

• resetOnNavigation: false est indispensable si votre projet est une app de type SPA avec vue-router : sans cette option, les données de coverage seraient réinitialisées à chaque changement de route pendant un test
• Le filtre !/src/ exclut les scripts Vite internes (@vite/client), les chunks node_modules et les scripts inline sans lien avec le code applicatif
• randomUUID() garantit un nom de fichier unique par test même avec fullyParallel: true et plusieurs workers
• Les specs importent test et expect depuis ../fixtures.js au lieu de @playwright/test

Configuration du rapport (.nycrc.json)

{
  "reporter": ["html", "text", "lcov", "cobertura"],
  "include": ["src/**"],
  "exclude": ["src/**/*.stories.{js,vue}", "src/stories/**"],
  "report-dir": "coverage/e2e"
}

• html : rapport navigable dans coverage/e2e/index.html
• text : résumé affiché dans la sortie stdout du CI (nécessaire pour la regex GitLab)
• lcov : format standard pour les outils tiers
• cobertura : format lu par GitLab pour les annotations de coverage inline dans les diffs de MR

Scripts package.json

"test:e2e:coverage-chromium": "rm -rf .nyc_output && COVERAGE=true playwright test --reporter list --project=chromium",
"test:e2e:coverage-report": "nyc report"

Le rm -rf .nyc_output en tête de commande est important : sans lui, nyc report mergerait les fichiers d'un run précédent avec les nouveaux et fausserait le calcul du coverage.

Job GitLab CI (test-e2e-coverage-chromium)

test-e2e-coverage-chromium:
    stage: test
    image: mcr.microsoft.com/playwright:v1.59.1-noble
    when: manual
    coverage: /All files\s*\|\s*(\d+\.?\d*)/
    artifacts:
        when: always
        expire_in: 2 days
        paths:
            - test-results/
            - coverage/e2e/
        reports:
            coverage_report:
                coverage_format: cobertura
                path: coverage/e2e/cobertura-coverage.xml
    script:
        - yarn install
        - yarn test:e2e:coverage-chromium
        - yarn test:e2e:coverage-report

• coverage: : regex qui extrait le pourcentage global depuis la sortie text de nyc (All files | 67.5 | ...) et l'affiche dans l'UI pipeline et sur les MR GitLab
• artifacts: when: always : le rapport HTML et le XML cobertura sont uploadés même si les tests passent
• coverage_report: cobertura : active les annotations de coverage inline dans les diffs de MR GitLab
• Le job est when: manual car si vous avez beaucoup de test E2E il n'est pas nécessaire de lancer ce job automatiquement