La CLI Playwright propose des options pour filtrer les tests par fichier, titre ou tag, exécuter un test unique en mode headed avec le débogage, contrôler les projets navigateurs. Vous pouvez aussi définir le nombre de workers et choisir les reporters.

La commande de base

npx playwright test

Exécute tous les tests dans votre testDir (généralement ./tests) sur tous les projets définis dans playwright.config.ts.

Filtrer les tests à exécuter

Par fichier ou dossier

# Exécuter tous les tests dans un fichier spécifique
npx playwright test tests/login.spec.ts

# Exécuter tous les tests dans un dossier
npx playwright test tests/api/

# Exécuter plusieurs fichiers
npx playwright test tests/login.spec.ts tests/dashboard.spec.ts

Par nom de test (--grep)

# Exécuter les tests dont le nom contient "login"
npx playwright test --grep "login"

# Exécuter les tests correspondant à une regex
npx playwright test --grep "login|registration"

# Inverser : exécuter les tests qui NE correspondent PAS
npx playwright test --grep-invert "flaky"

La chaîne est comparée au titre complet du test, qui inclut le nom du bloc describe. "Login page > shows error" correspondrait à --grep "error" ou --grep "Login page".

Par tag

Si vos tests utilisent des tags :

test('smoke test @smoke', async ({ page }) => { ... });

npx playwright test --grep "@smoke"

Par projet (navigateur)

# Exécuter uniquement dans Chrome
npx playwright test --project=chromium

# Exécuter uniquement dans Firefox et WebKit
npx playwright test --project=firefox --project=webkit

Interface et mode navigateur

Headed (navigateur visible)

npx playwright test --headed

Ouvre une vraie fenêtre de navigateur. Utile pour voir ce qui se passe pendant un test.

Ralenti

npx playwright test --headed --slow-mo=500

Ajoute un délai de 500ms entre les actions. Bien pour enregistrer des démos ou déboguer des problèmes de timing.

Mode UI (interactif)

npx playwright test --ui

Ouvre l'interface interactive de Playwright, un débogueur temporel qui vous permet de :

  • Parcourir tous les tests dans une barre latérale
  • Exécuter des tests individuels
  • Regarder une chronologie de chaque action
  • Voir des snapshots DOM à chaque étape
  • Inspecter les appels réseau

C'est le meilleur outil de débogage que Playwright propose. Utilisez-le chaque fois que vous tracez un échec déroutant.

Mode Debug

npx playwright test --debug

Pause avant la première action et ouvre l'Inspecteur Playwright. Avancez les actions une par une. Vous pouvez aussi taper des commandes Playwright dans la console de l'inspecteur pour tester des choses de façon interactive.

Pour un test spécifique :

npx playwright test tests/login.spec.ts --debug

Codegen (enregistrer un nouveau test)

npx playwright codegen https://lab.becomeqa.com

Ouvre un navigateur où vos actions sont enregistrées. Le code Playwright généré apparaît dans la fenêtre de l'inspecteur. Copiez-le dans votre fichier de test.

Exécution parallèle

Définir le nombre de workers

# 4 workers en parallèle
npx playwright test --workers=4

# Séquentiel (1 worker)
npx playwright test --workers=1

Sharding (pour CI avec plusieurs machines)

# Diviser les tests en 4 shards — exécuter le shard 1 sur la machine 1
npx playwright test --shard=1/4

# Exécuter le shard 2 sur la machine 2
npx playwright test --shard=2/4

Chaque shard exécute un sous-ensemble de tests. Temps total divisé par le nombre de shards (approximativement).

Relances

# Relancer les tests en échec jusqu'à 3 fois
npx playwright test --retries=3

En général, vous définissez les relances dans playwright.config.ts, mais l'option CLI la remplace.

Reporting

Choisir le reporter

# List (sortie console en direct)
npx playwright test --reporter=list

# Rapport HTML
npx playwright test --reporter=html

# Dot (sortie minimale)
npx playwright test --reporter=dot

# Plusieurs reporters
npx playwright test --reporter=html,list

Ouvrir le dernier rapport HTML

npx playwright show-report

Ouvre playwright-report/index.html dans votre navigateur. C'est le rapport visuel avec tous les résultats de tests, captures d'écran, traces et vidéos.

Fusionner les rapports shardés

Après l'exécution de tests shardés, fusionnez les rapports :

npx playwright merge-reports --reporter html ./blob-reports

Trace Viewer

Voir une trace enregistrée (le fichier .zip d'un test en échec) :

npx playwright show-trace trace.zip

Ou depuis le rapport HTML : cliquez sur "Trace" sur n'importe quel test en échec.

Combinaisons utiles

# Déboguer un test en échec spécifique
npx playwright test tests/checkout.spec.ts --grep "payment fails" --debug

# Exécuter uniquement les smoke tests dans Chrome, headed
npx playwright test --grep "@smoke" --project=chromium --headed

# Exécuter tous les tests mais relancer les échecs une fois, avec sortie verbeuse
npx playwright test --retries=1 --reporter=list

# Vérification rapide : premier worker uniquement, 5 premiers tests
npx playwright test --workers=1 --max-failures=5

# Exécuter sans le fichier de config (utile pour des scripts ponctuels)
npx playwright test --config=minimal.config.ts

# Lister tous les tests sans les exécuter
npx playwright test --list

Variables d'environnement avec la CLI

Vous pouvez passer des variables d'environnement directement :

BASE_URL=https://staging.myapp.com npx playwright test

Ou en définir plusieurs :

BASE_URL=https://staging.myapp.com ENV=staging npx playwright test

Elles sont disponibles dans votre config et vos tests via process.env.BASE_URL.

Référence des options courantes

| Option | Ce qu'elle fait |

|---|---|

| --headed | Afficher la fenêtre du navigateur |

| --debug | Pause et ouvrir l'inspecteur |

| --ui | Ouvrir le mode UI interactif |

| --slow-mo=N | Ajouter un délai de N ms entre les actions |

| --grep "pattern" | Filtrer les tests par nom |

| --grep-invert "pattern" | Exclure les tests par nom |

| --project=name | Exécuter un projet spécifique (navigateur) |

| --workers=N | Nombre de workers en parallèle |

| --retries=N | Relancer les tests en échec N fois |

| --shard=X/Y | Exécuter le shard X sur Y |

| --reporter=type | Choisir le format de sortie |

| --timeout=N | Remplacer le timeout de test (ms) |

| --max-failures=N | S'arrêter après N échecs |

| --list | Lister tous les tests sans les exécuter |

| --config=file | Utiliser un fichier de config différent |

| --pass-with-no-tests | Ne pas échouer si aucun test trouvé |

Scripts package.json

Ajoutez les commandes courantes comme scripts npm pour que les coéquipiers n'aient pas à se souvenir des options :

{
  "scripts": {
    "test": "npx playwright test",
    "test:headed": "npx playwright test --headed",
    "test:debug": "npx playwright test --debug",
    "test:ui": "npx playwright test --ui",
    "test:smoke": "npx playwright test --grep @smoke",
    "test:chrome": "npx playwright test --project=chromium",
    "test:report": "npx playwright show-report",
    "test:ci": "npx playwright test --reporter=list,junit"
  }
}

N'importe qui peut alors exécuter npm run test:smoke sans avoir besoin de connaître l'option grep.

La CLI vaut la peine d'être maîtrisée. Entre --grep, --debug et --ui, vous pouvez accélérer considérablement votre workflow de débogage : cibler exactement le test en échec, dans exactement le mode dont vous avez besoin pour l'investiguer.

→ See also: Fichier de Configuration Playwright Expliqué: Toutes les Options à Connaître | Playwright Trace Viewer: Déboguez les Tests Échoués Comme un Pro | Configuration VS Code pour Playwright: Extensions, Paramètres et Productivité