GitLab CI + Playwright: Guide de Configuration Complet

GitLab CI utilise un fichier .gitlab-ci.yml à la racine du dépôt pour définir les stages, les jobs et les déclencheurs du pipeline. La syntaxe diffère de GitHub Actions, mais le modèle sous-jacent est identique.

Prérequis

Projet Playwright fonctionnel en local avec npx playwright test
Dépôt GitLab (gitlab.com ou auto-hébergé)
.gitlab-ci.yml n'existe pas encore (ou vous le complétez)

Le pipeline minimal

Créez .gitlab-ci.yml à la racine de votre projet :

image: mcr.microsoft.com/playwright:v1.44.0-jammy

stages:
  - test

playwright-tests:
  stage: test
  script:
    - npm ci
    - npx playwright test
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 7 days

C'est tout. Poussez ce fichier et GitLab CI lancera vos tests à chaque commit.

Voici ce que fait chaque partie.

Explication ligne par ligne

`image: mcr.microsoft.com/playwright:v1.44.0-jammy`

C'est le conteneur Docker dans lequel tourne votre pipeline. L'image Docker officielle de Playwright intègre Node.js, toutes les dépendances de navigateur Playwright pré-installées, et un environnement Linux.

C'est l'approche recommandée : aucune installation de navigateur nécessaire dans le pipeline.

Épinglez la version (v1.44.0, pas latest) pour que votre pipeline ne casse pas lors d'une nouvelle version de Playwright. Mettez-la à jour manuellement quand vous upgradez Playwright en local.

`npm ci` vs `npm install`

En CI, utilisez toujours npm ci plutôt que npm install. Il installe exactement ce qui est dans package-lock.json (déterministe), est plus rapide dans les environnements CI, et échoue si package-lock.json est absent ou incohérent.

`artifacts`

Playwright génère un rapport HTML dans playwright-report/ après chaque run. La section artifacts indique à GitLab de sauvegarder ce dossier pour pouvoir le télécharger et le consulter.

when: always sauvegarde les artifacts même si les tests échouent, ce qui est précisément quand vous en avez besoin. expire_in: 7 days indique à GitLab de les supprimer automatiquement après 7 jours.

Pour consulter le rapport : dans GitLab CI, accédez au pipeline, puis au job, cliquez sur "Download artifacts" et ouvrez playwright-report/index.html.

Un pipeline plus complet

Pour des projets réels, ajoutez un peu plus de structure :

image: mcr.microsoft.com/playwright:v1.44.0-jammy

stages:
  - test

variables:
  # Cache node_modules entre les runs pour aller plus vite
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - .npm/
    - node_modules/

playwright-tests:
  stage: test
  
  # Lancer sur les merge requests et la branche main
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"
  
  script:
    - npm ci
    - npx playwright test --reporter=html,junit
  
  artifacts:
    when: always
    paths:
      - playwright-report/
      - test-results/
    reports:
      junit: test-results/results.xml
    expire_in: 7 days
  
  # Timeout pour l'ensemble du job
  timeout: 20 minutes

Ce qui change ici

variables : Variables d'environnement pour le job. npm_config_cache indique à npm le répertoire de cache à utiliser. cache : Les node modules sont mis en cache entre les runs. Le premier run est lent (tout est téléchargé), les suivants sont rapides (lecture depuis le cache). La clé est le nom de la branche, donc chaque branche a son propre cache. rules : Contrôle quand ce job s'exécute. La configuration ci-dessus s'exécute sur les merge requests (pour voir les résultats avant de fusionner) et les pushes sur main (après la fusion). --reporter=html,junit : Génère un rapport HTML et un fichier XML JUnit. Le format JUnit est reconnu par GitLab et affiche les résultats directement dans l'interface du pipeline. reports: junit: : Indique à GitLab où se trouve le fichier JUnit XML. GitLab affiche alors un onglet "Tests" dans le pipeline avec le statut par test.

Variables d'environnement (secrets)

Ne mettez jamais de mots de passe ou clés API dans .gitlab-ci.yml. Utilisez les variables CI/CD de GitLab :

Configurer les variables dans GitLab :

1. Projet → Settings → CI/CD → Variables

2. Ajoutez : BASE_URL, ADMIN_EMAIL, ADMIN_PASSWORD, API_KEY

3. Marquez les variables sensibles comme "Masked" (masquées dans les logs)

4. Marquez les variables spécifiques à un environnement comme "Protected" (uniquement sur les branches protégées)

Utilisation dans le pipeline :

playwright-tests:
  script:
    - npm ci
    - npx playwright test
  variables:
    BASE_URL: $BASE_URL              # Depuis les variables GitLab CI
    ADMIN_EMAIL: $ADMIN_EMAIL        # Depuis les variables GitLab CI

Utilisation dans la config Playwright :

// playwright.config.ts
import dotenv from 'dotenv';
dotenv.config();

export default defineConfig({
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
  },
});

Les variables GitLab CI sont disponibles comme variables d'environnement dans le job : process.env.BASE_URL fonctionne directement.

Exécution parallèle et sharding

Pour les suites de tests volumineuses, lancez les tests en parallèle :

playwright-tests:
  stage: test
  
  parallel:
    matrix:
      - SHARD: ["1/4", "2/4", "3/4", "4/4"]
  
  script:
    - npm ci
    - npx playwright test --shard=$SHARD
  
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 7 days

Ça crée 4 jobs parallèles, chacun exécutant 25 % des tests. La durée totale est divisée approximativement par 4.

À noter : fusionner les rapports HTML fractionnés nécessite des étapes supplémentaires (la commande merge-reports de Playwright).

Mode headed pour le débogage

Par défaut, Playwright tourne en headless en CI. Pour déboguer visuellement :

playwright-debug:
  stage: test
  script:
    - npm ci
    - npx playwright test --headed --video=on
  when: manual  # Se déclenche uniquement manuellement
  artifacts:
    when: always
    paths:
      - test-results/  # Les vidéos sont sauvegardées ici
    expire_in: 1 day

when: manual signifie que ce job ne se lance pas automatiquement. Vous le déclenchez manuellement depuis l'interface GitLab quand vous avez besoin de déboguer.

Gérer les tests flaky

Playwright intègre une logique de retry. Configurez-la pour CI :

// playwright.config.ts
export default defineConfig({
  retries: process.env.CI ? 2 : 0,  // 2 retries en CI seulement
});

Ou dans .gitlab-ci.yml, autorisez le job lui-même à se relancer en cas d'échec :

playwright-tests:
  retry:
    max: 1  # Relancer le job une fois s'il échoue
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

Le retry au niveau du job (GitLab) cible les pannes d'infrastructure. Le retry au niveau du test (config Playwright) cible les tests flaky. Utilisez les deux.

Exemple complet avec plusieurs environnements

image: mcr.microsoft.com/playwright:v1.44.0-jammy

stages:
  - test

.playwright-base:
  script:
    - npm ci
    - npx playwright test --reporter=html,junit
  artifacts:
    when: always
    paths:
      - playwright-report/
    reports:
      junit: test-results/results.xml
    expire_in: 7 days
  timeout: 20 minutes

playwright-staging:
  extends: .playwright-base
  variables:
    BASE_URL: https://staging.yourapp.com
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

playwright-production:
  extends: .playwright-base
  variables:
    BASE_URL: https://yourapp.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment:
    name: production

Cette configuration lance les tests de staging sur la branche develop et les MR, et les tests de production uniquement lors d'un merge sur main.

Problèmes fréquents

Erreur "Executable doesn't exist" :

Vous n'utilisez pas l'image Docker Playwright, ou la version est incorrecte. Restez sur mcr.microsoft.com/playwright:v1.44.0-jammy et la version doit correspondre exactement à votre version de @playwright/test.

Les tests expirent en CI mais passent en local :

Les machines CI sont plus lentes. Augmentez les timeouts dans playwright.config.ts :

export default defineConfig({
  timeout: 60000,        // 60s par test (contre 30s par défaut)
  actionTimeout: 15000,  // 15s par action
});

"Cannot find module" en CI :

Une dépendance manque dans package.json. Lancez npm install en local et committez package.json et package-lock.json mis à jour.

Pipeline lent à cause de npm install :

Ajoutez le cache (voir l'exemple complet ci-dessus). Le premier run sera lent ; les suivants seront rapides.

Checklist avant de pousser

[ ] .gitlab-ci.yml est à la racine du projet
[ ] Image Docker Playwright avec version épinglée
[ ] npm ci (pas npm install)
[ ] Artifacts configurés pour sauvegarder playwright-report/
[ ] Secrets dans les variables GitLab CI, pas dans le fichier YAML
[ ] retries Playwright configuré pour l'environnement CI
[ ] timeout défini dans playwright.config.ts (les machines CI sont plus lentes)