Playwright Test : écrire et lancer son premier test

Un test Playwright est un script qui pilote un vrai navigateur pour vérifier qu'une fonctionnalité web se comporte comme prévu. Il suffit d'initialiser le projet avec une commande, d'écrire un scénario avec des locators et des assertions, puis de le lancer avec npx playwright test. Ce tutoriel vous guide de l'installation jusqu'à l'exécution sur plusieurs navigateurs, avec les réflexes de débogage qui évitent les tests instables.

Si vous venez du test manuel, votre premier test Playwright peut sembler intimidant. Pourtant, la logique reste celle que vous connaissez : ouvrir une page, effectuer des actions, comparer un résultat obtenu à un résultat attendu. La différence, c'est que ce scénario s'exécute seul, à chaque modification du code, et dans plusieurs navigateurs. Voici un parcours concret, avec du code à copier, pour passer de zéro à une première exécution réussie.

Playwright Test, c'est quoi ?

Playwright est un framework open source développé par Microsoft pour automatiser les tests end-to-end des applications web. Il pilote Chromium, Firefox et WebKit. Son lanceur de tests intégré, Playwright Test (le paquet @playwright/test), gère l'exécution, les assertions, les rapports et la parallélisation : vous n'avez pas besoin d'assembler un lanceur et une bibliothèque d'assertions à part.

Un test end-to-end parcourt l'application comme un utilisateur : il charge une page, clique, remplit un formulaire et vérifie ce qui s'affiche. Il valide ainsi toute la chaîne (interface, API, base de données) sur un parcours précis. Cette vision globale est sa force, mais aussi sa limite : il est plus lent et plus coûteux à maintenir qu'un test unitaire. On le réserve donc aux parcours critiques : connexion, recherche, ajout au panier, paiement, création de compte.

Bonne nouvelle pour un testeur manuel : un scénario bien rédigé se traduit presque ligne à ligne en test automatisé. Les étapes deviennent des actions, et les résultats attendus deviennent des assertions. Le guide pour automatiser ses tests avec Playwright aborde la démarche globale ; ici, on se concentre sur la pratique du premier test.

Installer Playwright et lancer un premier test

Les prérequis

• Node.js installé sur votre poste, dans sa dernière version LTS (vérifiez avec node -v) ;
• un éditeur de code, par exemple VS Code ;
• une application web à tester, locale ou en ligne, dont vous avez le droit d'automatiser les parcours. Pour ce premier test, nous utiliserons le site officiel de Playwright.

TypeScript n'est pas un obstacle : les tests Playwright reposent sur quelques motifs répétitifs (await, page, expect) que l'on assimile vite en pratiquant. Si vous voulez les bases avant de commencer, lisez TypeScript pour Playwright : les bases essentielles.

Initialiser le projet

Créez un dossier vide, ouvrez un terminal à l'intérieur, puis lancez l'assistant d'initialisation :

npm init playwright@latest

L'assistant pose quelques questions : TypeScript ou JavaScript, nom du dossier de tests, ajout d'un workflow GitHub Actions, installation des navigateurs. Choisissez TypeScript et acceptez l'installation des navigateurs. Vous obtenez notamment :

• playwright.config.ts : la configuration (navigateurs, délais, rapports) ;
• tests/ : le dossier de vos tests, avec un fichier d'exemple example.spec.ts ;
• package.json : les dépendances du projet.

Dans VS Code, l'extension officielle Playwright permet ensuite de lancer un test d'un clic depuis la marge de l'éditeur.

Écrire un premier test qui passe

Créez le fichier tests/premier-test.spec.ts et copiez ce test. Il ouvre le site de Playwright, vérifie le titre de la page, clique sur « Get started » et vérifie que la page d'installation s'affiche :

import { test, expect } from '@playwright/test';

test('la page d\'accueil mène à la documentation d\'installation', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);

  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Chaque élément a un rôle précis :

• test(...) déclare un scénario nommé : décrivez le comportement attendu, pas l'implémentation ;
• { page } est une fixture : Playwright fournit une page neuve et isolée à chaque test ;
• page.goto(...) ouvre l'adresse demandée ;
• getByRole(...) retrouve un élément comme le perçoit l'utilisateur, ici un lien et un titre ;
• expect(...) vérifie le résultat attendu.

Lancer le test

npx playwright test premier-test

Par défaut, Playwright lance les tests sans fenêtre (mode headless) et en parallèle. La configuration générée déclare trois navigateurs : votre test s'exécute donc trois fois, et la console affiche par exemple Running 3 tests using 3 workers puis 3 passed. Ouvrez le rapport HTML détaillé avec npx playwright show-report : chaque test y apparaît avec sa durée et, en cas d'échec, l'erreur complète.

Pour vos propres tests, renseignez l'adresse de votre application une seule fois dans playwright.config.ts, avec l'option baseURL du bloc use. Vous pourrez alors écrire simplement page.goto('/').

Écrire des tests fiables : locators et assertions

La fiabilité d'un test dépend surtout de deux choses : la façon dont vous retrouvez les éléments de la page, et la façon dont vous vérifiez le résultat. C'est là que se jouent la plupart des tests instables.

Choisir les bons locators

Un locator décrit comment trouver un élément. Playwright recommande les locators qui reflètent ce que perçoit l'utilisateur : rôle, libellé, texte visible. Ils résistent mieux aux refontes de l'interface que des sélecteurs CSS liés à la structure du HTML.

Règle pratique : commencez par getByRole. Si l'élément n'a pas de rôle clair, essayez getByLabel ou getByText. N'ajoutez un attribut data-testid qu'en dernier recours, en accord avec l'équipe de développement.

Un scénario en plusieurs étapes

Voici un parcours type, à adapter à votre application : ajouter un produit au panier et vérifier la confirmation.

import { test, expect } from '@playwright/test';

test('un produit ajouté apparaît dans le panier', async ({ page }) => {
  await page.goto('/');

  await page.getByRole('link', { name: 'Casque audio' }).click();
  await page.getByRole('button', { name: 'Ajouter au panier' }).click();
  await expect(page.getByText('Produit ajouté au panier')).toBeVisible();

  await page.getByRole('link', { name: 'Panier' }).click();
  await expect(page.getByRole('heading', { name: 'Votre panier' })).toBeVisible();
  await expect(page.getByText('Casque audio')).toBeVisible();
});

Ce test se lit presque comme un scénario manuel. C'est volontaire : un bon test décrit un comportement utilisateur, pas des détails techniques.

Des assertions qui attendent toutes seules

Les assertions de la forme await expect(locator)... réessaient automatiquement jusqu'à ce que la condition soit remplie ou que le délai expire. Si votre message de confirmation met 300 ms à apparaître, le test attend sans que vous écriviez de pause. Il faut donc bannir les attentes fixes du type waitForTimeout : elles ralentissent la suite et ne garantissent rien. Les causes d'instabilité les plus fréquentes sont détaillées dans 8 étapes pour fiabiliser ses tests Playwright.

Les assertions les plus courantes : toBeVisible() et toBeHidden() pour l'affichage, toHaveText() et toContainText() pour le contenu, toHaveValue() pour un champ, toHaveURL() pour une navigation et toHaveCount() pour compter des éléments.

Des tests indépendants les uns des autres

Un test fiable ne dépend pas d'un autre test et donne le même résultat à chaque exécution. Playwright crée un contexte de navigateur neuf pour chaque test : cookies et stockage local ne passent pas d'un scénario à l'autre. À vous de garder cette discipline côté données : un test ne doit pas supposer l'existence d'un compte créé par un autre test. Pour regrouper les scénarios d'une fonctionnalité et factoriser une étape commune, utilisez test.describe et test.beforeEach :

test.describe('Panier', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/');
  });

  test('le panier est vide au départ', async ({ page }) => {
    await page.getByRole('link', { name: 'Panier' }).click();
    await expect(page.getByText('Votre panier est vide')).toBeVisible();
  });
});

Quand la suite grandit, regroupez les locators et les actions de chaque page dans des classes réutilisables : c'est le Page Object Model avec Playwright.

Exécuter et déboguer ses tests

Les commandes à connaître

Pour un premier essai, --headed est très parlant : vous voyez le navigateur cliquer à votre place.

Comprendre un test qui échoue

Un test rouge n'est pas un problème, c'est une information. Pour la lire, procédez dans cet ordre :

1. Lisez le message d'erreur : Playwright indique la ligne en échec, le locator cherché et ce qu'il a trouvé à la place ;
2. Relancez avec --ui pour rejouer chaque action et voir l'état de la page avant et après ;
3. Utilisez --debug pour avancer pas à pas et tester vos locators en direct ;
4. Activez les traces pour analyser un échec survenu ailleurs que sur votre poste, par exemple en intégration continue.

Les traces s'activent dans playwright.config.ts :

export default defineConfig({
  retries: 1,
  use: {
    baseURL: 'https://votre-application.fr',
    trace: 'on-first-retry',
  },
});

Une trace est alors enregistrée quand un test échoue puis est relancé. Le Trace Viewer permet de parcourir chronologiquement les actions, les captures d'écran, les requêtes réseau et les messages de la console : c'est l'outil le plus utile pour comprendre un échec que vous n'arrivez pas à reproduire.

Générer du code, sans s'y fier aveuglément

La commande npx playwright codegen ouvre un navigateur et enregistre vos actions sous forme de code. C'est un bon moyen de découvrir la syntaxe ou de trouver un locator. Mais le code généré reste un brouillon : renommez les tests, ajoutez de vraies assertions et vérifiez que les locators sont lisibles. Il en va de même pour le code proposé par un assistant d'intelligence artificielle : relisez-le et exécutez-le plusieurs fois avant de l'intégrer à votre suite.

Lancer ses tests sur plusieurs navigateurs

Le fichier de configuration contient une section projects : chaque projet correspond à un navigateur ou à un appareil. L'assistant d'initialisation en prépare trois :

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

Un seul npx playwright test exécute chaque scénario dans les trois moteurs. Pour cibler un navigateur, ajoutez --project=firefox. Vous pouvez aussi déclarer des profils mobiles, par exemple devices['iPhone 13'], pour vérifier l'affichage sur petit écran.

Un conseil de méthode : travaillez sur un seul navigateur tant que vos tests sont en construction, puis élargissez quand la suite est stable. Multiplier les navigateurs sur des tests encore fragiles ne fait que multiplier les échecs.

Et ensuite ?

Une fois votre premier test au vert, voici les étapes qui font monter une suite en qualité :

• structurer le code avec le Page Object Model et des fixtures ;
• préparer les données par l'API plutôt que par l'interface : voir automatiser vos tests API avec Playwright ;
• lancer les tests à chaque modification du code avec Playwright et GitHub Actions ;
• suivre les échecs grâce aux rapports et aux traces.

L'essentiel est de pratiquer sur un vrai parcours de votre application : un test qui vérifie une fonctionnalité réelle vous apprendra plus que dix exemples théoriques. Pour progresser avec un accompagnement et un projet concret, découvrez la formation Playwright Mission Playwright.

FAQ sur Playwright Test

Peut-on utiliser Playwright Test sans maîtriser TypeScript ?

Oui. Playwright Test peut être utilisé avec JavaScript, et ses tests reposent sur des concepts accessibles comme les fonctions, les conditions et les assertions. TypeScript apporte des vérifications de types utiles dans les projets plus importants, mais il n’est pas indispensable pour écrire un premier test. Il est toutefois utile de comprendre les bases du langage choisi afin de lire les erreurs, modifier les tests et maintenir la suite.

Quelle différence y a-t-il entre Playwright et Playwright Test ?

Playwright est l’outil d’automatisation qui permet notamment de piloter un navigateur, tandis que Playwright Test est le framework conçu pour organiser et exécuter des tests. Il fournit des fonctionnalités comme les assertions, les fixtures, le lancement parallèle et la gestion des rapports. Les deux sont souvent utilisés ensemble pour tester une application web, mais Playwright peut aussi servir à d’autres tâches d’automatisation du navigateur.

Comment éviter que les tests Playwright dépendent les uns des autres ?

Chaque test devrait pouvoir réussir ou échouer indépendamment des autres. Préparez les données nécessaires dans le test ou dans une fixture, puis nettoyez-les si l’application le permet. Évitez qu’un test dépende de l’état créé par un test précédent ou d’un ordre d’exécution particulier. Cette isolation facilite aussi les relances et l’exécution en parallèle, et rend les échecs plus faciles à diagnostiquer.

Peut-on exécuter Playwright Test dans une intégration continue ?

Oui. Playwright Test peut être intégré à un pipeline d’intégration continue afin d’exécuter automatiquement les tests, par exemple après une modification du code. La configuration doit installer les navigateurs nécessaires, lancer l’application ou rendre un environnement de test accessible, puis conserver les rapports et traces utiles en cas d’échec. Adaptez les navigateurs exécutés et le niveau de parallélisme aux ressources de votre pipeline.

Dans quels cas un agent IA peut-il aider à analyser un test d’interface ?

Un agent IA peut aider à résumer un échec, repérer une assertion incohérente ou suggérer des pistes à partir d’un message d’erreur, d’une trace ou d’une capture. Il peut aussi accélérer la lecture d’une suite de tests existante. Ses propositions doivent toutefois être vérifiées dans le contexte de l’application : il ne connaît pas nécessairement les règles métier et peut suggérer des sélecteurs fragiles ou masquer un vrai défaut.

Comment choisir Playwright Test plutôt qu’un autre outil de test web ?

Comparez les outils selon les besoins du projet : navigateurs à couvrir, langages déjà utilisés, intégration à la chaîne d’automatisation, facilité de diagnostic et compétences de l’équipe. Vérifiez aussi si vous avez besoin de tests de bout en bout, de tests de composants ou d’autres niveaux de validation, car les outils ne se recouvrent pas toujours entièrement. Un petit essai sur un parcours représentatif permet d’évaluer l’effort de maintenance avant d’élargir l’usage.