playwright-docs

Playwright Test (JS/TS) d'après la documentation officielle

Présentation

Cette compétence regroupe ce que la documentation de Playwright dit et qui est facile à mal interpréter : les règles d'auto-attente, la strictesse, les timeouts qui ne se cumulent pas comme on pourrait s'y attendre, les angles morts du mocking, les modes de mise à jour des instantanés, les paramètres CI et les API supprimées. Les conseils génériques de test sont exclus. Chaque affirmation est accompagnée de l'URL de la documentation dont elle provient, afin de pouvoir être vérifiée.

Version couverte

Playwright Test 1.64.1 pour Node.js et TypeScript (@playwright/test). Le contenu Python, Java et .NET est exclu. Lorsque la version installée est plus ancienne, consultez le tableau des versions dans references/version-changes.md avant d'appliquer une API plus récente.

Comment naviguer

1. Lisez le démarrage rapide ci-dessous. Il couvre les règles qui s'appliquent dans la plupart des tests.
2. Ouvrez le fichier de référence dont le domaine correspond à la tâche, à partir du tableau en fin de document.
3. Avant de relire du code ancien ou d'effectuer une mise à niveau, lisez « Anciens motifs » ci-dessous et references/version-changes.md.

Démarrage rapide

Localisateurs

• Par défaut : page.getByRole(role, { name }). Ensuite getByLabel, getByText (éléments non interactifs uniquement), getByTestId comme solution de repli basée sur un contrat. CSS ou XPath uniquement lorsque rien d'autre ne fonctionne du point de vue de l'utilisateur. https://playwright.dev/docs/locators#quick-guide
• Les localisateurs sont stricts : une action sur un localisateur correspondant à 2 éléments lève une exception. Affinez avec filter({ hasText }), filter({ has }) ou inner.within(outer) au lieu d'utiliser first() / nth(). https://playwright.dev/docs/locators#strictness
• Le localisateur à l'intérieur de filter({ has }) est résolu à partir de la correspondance externe, jamais à partir de la racine de la page. https://playwright.dev/docs/locators#filter-by-childdescendant
• La correspondance de texte est une sous-chaîne et insensible à la casse par défaut, et toujours normalisée au niveau des espaces, même avec exact: true. https://playwright.dev/docs/locators#locate-by-text

Actions et attente

• Les actions attendent automatiquement que l'élément soit actionnable. N'ajoutez pas de waitForTimeout, ni d'attente manuelle de chargement avant un clic. https://playwright.dev/docs/actionability#introduction et https://playwright.dev/docs/navigations#when-is-the-page-loaded
• fill() est la valeur par défaut pour le texte. pressSequentially() uniquement pour une gestion caractère par caractère. https://playwright.dev/docs/input#type-characters
• Événements (popup, téléchargement, sélecteur de fichier, réponse) : créez la promesse d'attente AVANT le clic, attendez-la après.

  const downloadPromise = page.waitForEvent('download');
  await page.getByText('Télécharger le fichier').click();
  const download = await downloadPromise;
  

  https://playwright.dev/docs/downloads#introduction
• Un écouteur dialog qui n'accepte ni ne refuse la boîte de dialogue bloque la page. Sans écouteur, les boîtes de dialogue sont automatiquement rejetées. https://playwright.dev/docs/dialogs#alert-confirm-prompt-dialogs

Assertions

• Utilisez toujours await expect(locator).toX(). N'utilisez jamais expect(await locator.isVisible()).toBe(true), qui ne vérifie qu'une seule fois. https://playwright.dev/docs/best-practices#use-web-first-assertions
• Le timeout des assertions est de 5 s, distinct du timeout de test de 30 s. https://playwright.dev/docs/test-timeouts
• Aucun matcher correspondant : utilisez par défaut expect.poll. expect(...).toPass() n'a PAS de timeout par défaut, donc transmettez-en un. https://playwright.dev/docs/test-assertions#expecttopass
• Utilisez le expect de Playwright, pas celui de Jest. https://playwright.dev/docs/test-assertions#compatibility-with-expect-library

Structure et configuration

• Options de l'exécuteur au niveau supérieur de defineConfig, options de navigateur et de contexte à l'intérieur de use. https://playwright.dev/docs/test-configuration#introduction
• Préférez les fixtures aux paires de hooks before/after. Les tests importent test depuis le fichier de fixtures. https://playwright.dev/docs/test-fixtures#with-fixtures
• beforeAll s'exécute une fois par worker, et un worker redémarre après chaque échec, donc beforeAll peut s'exécuter plusieurs fois. https://playwright.dev/docs/test-retries#failures
• Connectez-vous une fois dans un projet de configuration avec dependencies, enregistrez storageState après avoir attendu l'URL finale, ajoutez playwright/.auth au gitignore. https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
• Étalez d'abord un appareil, puis remplacez viewport, car un appareil définit également son propre viewport. https://playwright.dev/docs/emulation#viewport
• Playwright ne vérifie pas les types. Exécutez tsc --noEmit sur CI et effectuez une analyse statique avec @typescript-eslint/no-floating-promises. https://playwright.dev/docs/test-typescript#introduction et https://playwright.dev/docs/best-practices#lint-your-tests

Réseau

• Enregistrez page.route AVANT page.goto. Un glob doit correspondre à l'URL complète, et ? correspond uniquement à un point d'interrogation littéral. https://playwright.dev/docs/mock#mock-api-requests et https://playwright.dev/docs/network#glob-url-patterns
• Les routes manquent les requêtes servies par un service worker. Définissez serviceWorkers: 'block'. https://playwright.dev/docs/network#missing-network-events-and-service-workers
• page.request partage les cookies du navigateur. request.newContext() est isolé et doit être libéré. https://playwright.dev/docs/api-testing#context-request-vs-global-request

CI

• forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, trace: 'on-first-retry', et toujours un globalTimeout, sinon une exécution bloquée ne produit aucun rapport. https://playwright.dev/docs/test-configuration#basic-configuration et https://playwright.dev/docs/ci#global-timeout
• npx playwright install --with-deps après npm ci et après chaque mise à niveau. Ne mettez pas en cache les navigateurs. https://playwright.dev/docs/ci#caching-browsers
• Fragmentez avec fullyParallel: true et fusionnez les rapports blob. https://playwright.dev/docs/test-sharding#balancing-shards
• Sérialisez les tests qui partagent une ressource avec un verrou, pas le mode série : test('x', { lock: 'db' }, ...). https://playwright.dev/docs/test-parallel#test-locks

Instantanés

• Sans -u, un instantané manquant est écrit ET le test échoue. --update-snapshots=missing écrit et réussit. -u signifie changed. https://playwright.dev/docs/aria-snapshots#updating-snapshots-with-playwrighttest-and-the---update-snapshots-flag
• Les références de capture d'écran sont par navigateur et par système d'exploitation. Générez-les là où elles sont comparées. https://playwright.dev/docs/test-snapshots#introduction

Anciens motifs

Ancien	Actuel	Source
locator.type(), page.type()	locator.fill(), ou pressSequentially()	https://playwright.dev/docs/release-notes#version-138
page.$(), ElementHandle, page.$eval + expect générique	Localisateur + assertion web-first	https://playwright.dev/docs/handles#locator-vs-elementhandle
expect(await locator.isVisible()).toBe(true)	await expect(locator).toBeVisible()	https://playwright.dev/docs/best-practices#dont-use-manual-assertions
pseudo-classe :visible	locator.visible()	https://playwright.dev/docs/release-notes#version-163
sélecteurs text=Log in, id=, data-testid=	getByText, getByTestId	https://playwright.dev/docs/other-locators#legacy-text-locator
sélecteurs de disposition :right-of(), :near()	localisateurs visibles par l'utilisateur	https://playwright.dev/docs/other-locators#css-matching-elements-based-on-layout
sélecteurs _react, _vue	localisateurs standard	https://playwright.dev/docs/release-notes#version-158
page.accessibility	@axe-core/playwright	https://playwright.dev/docs/release-notes#version-157
globalSetup pour la connexion ou l'initialisation	projet de configuration avec dependencies	https://playwright.dev/docs/test-global-setup-teardown#introduction
test.describe.configure({ mode: 'serial' }) pour une ressource partagée	verrous de test	https://playwright.dev/docs/test-parallel#test-locks
webServer.port	webServer.url	https://playwright.dev/docs/test-webserver#configuring-a-web-server
videosPath, videoSize	recordVideo, ou use.video dans l'exécuteur	https://playwright.dev/docs/release-notes#version-160
option de lancement devtools: true	args: ['--auto-open-devtools-for-tabs']	https://playwright.dev/docs/release-notes#version-158
drapeau -gv	--grep-invert ou -G	https://playwright.dev/docs/release-notes#version-154
npx playwright open pour enregistrer	npx playwright codegen	https://playwright.dev/docs/release-notes#version-154
updateSnapshots: 'all' pour rafraîchir ceux qui ont changé	'changed' ('all' réécrit tout)	https://playwright.dev/docs/release-notes#version-150
waitUntil: 'networkidle'	auto-attente et assertions web-first	https://playwright.dev/docs/puppeteer#automation-example
@playwright/experimental-ct-* avec JSX mount(<C />)	stories + mount('Story/Id', props) depuis @playwright/test	https://playwright.dev/docs/test-components#migration-from-the-experimental-packages
navigateurs téléchargés par npm install	npx playwright install --with-deps	https://playwright.dev/docs/release-notes#version-138

Fichiers de référence

Fichier	Lisez-le pour
references/locators.md	priorité des localisateurs, correspondance de texte, strictesse, filter, within, and / or, visible(), DOM Shadow, frames, sélecteurs legacy
references/actions-and-events.md	vérifications d'actionnabilité par action, force, saisie, glisser-déposer, boîtes de dialogue, téléchargements, téléversements, popups, navigation, hydration, evaluate, scripts d'initialisation, handles
references/assertions.md	matchers web-first versus génériques, timeouts des assertions, expect.poll, toPass, assertions douces, matchers personnalisés, test.step
references/snapshots-and-accessibility.md	modes de mise à jour des instantanés, instantanés aria, tolérances et nommage de toHaveScreenshot, instantanés non-image, scans axe
references/configuration.md	structure de la configuration, portées et valeurs par défaut de use, projets et dépendances, appareils et émulation, gestion TypeScript, webServer
references/timeouts-retries-annotations.md	chaque timeout et sa valeur par défaut, tentatives et redémarrages de worker, mode série, skip / fail / fixme, tags, tests paramétrés et projets
references/fixtures-and-auth.md	isolation, fixtures personnalisées, portées, options, ordre d'exécution, hooks globaux, projets de configuration, objets de page, authentification storageState, rôles, comptes par worker
references/network-and-mocking.md	route, règles glob, en-têtes et redirections qu'une route ne peut pas toucher, enregistrement et relecture HAR, simulations WebSocket, simulations d'API navigateur, service workers
references/api-testing-and-clock.md	fixture request, cookies partagés versus isolés, libération des contextes, méthodes page.clock et ordre
references/ci-parallel-sharding.md	base de référence CI, GitHub Actions et autres fournisseurs, workers, fullyParallel, verrous de test, sharding, fusion des rapports blob
references/browsers-and-docker.md	installation et cache des navigateurs, canaux Chromium, proxys et miroirs, image Docker, extensions Chrome, WebView2, grille Selenium
references/debugging-and-reporting.md	drapeaux CLI, --debug, inspecteur, modes trace et vidéo, visualiseur de trace, mode UI, rapporteurs
references/component-testing-and-migration.md	tests de composants avec stories et galerie, migration depuis les packages ct expérimentaux, Testing Library, Protractor, Puppeteer
references/codegen-and-agent-tooling.md	codegen, Library versus Test, canaux de version, agents de test, playwright-cli, Playwright MCP
references/version-changes.md	changements de comportement cassants, API supprimées et dépréciées avec leurs remplacements, changements de support de plateforme

Les sources et les détails de récupération sont listés dans SOURCES.md.