playwright-docs (Documentación de Playwright Test para JS/TS)

Playwright Test (JS/TS) desde la documentación oficial

Resumen

Este skill contiene lo que la documentación de Playwright dice que es fácil de malinterpretar: reglas de espera automática, estrictez, tiempos de espera que no se acumulan como uno espera, puntos ciegos en el mockeo, modos de actualización de instantáneas, configuraciones de CI y APIs eliminadas. Se omite el consejo genérico de pruebas. Cada afirmación lleva la URL de la documentación de la que proviene, para que pueda ser verificada.

Versión cubierta

Playwright Test 1.64.1 para Node.js y TypeScript (@playwright/test). El contenido de Python, Java y .NET está excluido. Cuando la versión instalada sea más antigua, consulte la tabla de versiones en references/version-changes.md antes de aplicar una API más nueva.

Cómo navegar

1. Lea la guía de inicio rápido a continuación. Cubre las reglas que importan en la mayoría de las pruebas.
2. Abra el archivo de referencia cuyo dominio coincida con la tarea, desde la tabla al final.
3. Antes de revisar código antiguo o actualizar, lea "Patrones antiguos" a continuación y references/version-changes.md.

Inicio rápido

Localizadores

• Predeterminado: page.getByRole(role, { name }). Luego getByLabel, getByText (solo elementos no interactivos), getByTestId como alternativa basada en contratos. CSS o XPath solo cuando nada orientado al usuario funciona. https://playwright.dev/docs/locators#quick-guide
• Los localizadores son estrictos: una acción sobre un localizador que coincide con 2 elementos lanza un error. Reduzca con filter({ hasText }), filter({ has }) o inner.within(outer) en lugar de usar first() / nth(). https://playwright.dev/docs/locators#strictness
• El localizador dentro de filter({ has }) se resuelve desde la coincidencia externa, nunca desde la raíz de la página. https://playwright.dev/docs/locators#filter-by-childdescendant
• La coincidencia de texto es por subcadena y no distingue entre mayúsculas y minúsculas de forma predeterminada, y siempre normaliza los espacios en blanco, incluso con exact: true. https://playwright.dev/docs/locators#locate-by-text

Acciones y esperas

• Las acciones esperan automáticamente a que el elemento sea accionable. No añada waitForTimeout, ni esperas manuales de carga antes de un clic. https://playwright.dev/docs/actionability#introduction y https://playwright.dev/docs/navigations#when-is-the-page-loaded
• fill() es el valor predeterminado para texto. pressSequentially() solo para manejo tecla por tecla. https://playwright.dev/docs/input#type-characters
• Eventos (popup, download, filechooser, response): cree la promesa de espera ANTES del clic, espérela después.

  const downloadPromise = page.waitForEvent('download');
  await page.getByText('Download file').click();
  const download = await downloadPromise;
  

  https://playwright.dev/docs/downloads#introduction
• Un listener de dialog que ni acepta ni descarta cuelga la página. Sin listener, los diálogos se descartan automáticamente. https://playwright.dev/docs/dialogs#alert-confirm-prompt-dialogs

Aserciones

• Siempre await expect(locator).toX(). Nunca expect(await locator.isVisible()).toBe(true), que comprueba una sola vez. https://playwright.dev/docs/best-practices#use-web-first-assertions
• El tiempo de espera de las aserciones es de 5 segundos, separado del tiempo de espera de la prueba de 30 segundos. https://playwright.dev/docs/test-timeouts
• Sin un matcher específico: use expect.poll. expect(...).toPass() NO tiene tiempo de espera por defecto, así que pásele uno. https://playwright.dev/docs/test-assertions#expecttopass
• Use el expect de Playwright, no el de Jest. https://playwright.dev/docs/test-assertions#compatibility-with-expect-library

Estructura y configuración

• Opciones del ejecutor en el nivel superior de defineConfig, opciones del navegador y del contexto dentro de use. https://playwright.dev/docs/test-configuration#introduction
• Prefiera fixtures sobre pares de hooks before/after. Las pruebas importan test desde el archivo de fixtures. https://playwright.dev/docs/test-fixtures#with-fixtures
• beforeAll se ejecuta una vez por worker, y un worker se reinicia después de cada fallo, por lo que beforeAll puede ejecutarse varias veces. https://playwright.dev/docs/test-retries#failures
• Inicie sesión una vez en un proyecto de configuración con dependencies, guarde storageState después de esperar la URL final, añada playwright/.auth a .gitignore. https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
• Primero extienda un dispositivo y luego sobrescriba viewport, porque un dispositivo también define su propio viewport. https://playwright.dev/docs/emulation#viewport
• Playwright no verifica tipos. Ejecute tsc --noEmit en CI y lint con @typescript-eslint/no-floating-promises. https://playwright.dev/docs/test-typescript#introduction y https://playwright.dev/docs/best-practices#lint-your-tests

Red

• Registre page.route ANTES de page.goto. Un glob debe coincidir con la URL completa, y ? coincide solo con un signo de interrogación literal. https://playwright.dev/docs/mock#mock-api-requests y https://playwright.dev/docs/network#glob-url-patterns
• Las rutas pierden las solicitudes servidas por un service worker. Establezca serviceWorkers: 'block'. https://playwright.dev/docs/network#missing-network-events-and-service-workers
• page.request comparte las cookies del navegador. request.newContext() está aislado y debe ser eliminado. 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', y siempre un globalTimeout, de lo contrario una ejecución colgada no produce ningún informe. https://playwright.dev/docs/test-configuration#basic-configuration y https://playwright.dev/docs/ci#global-timeout
• npx playwright install --with-deps después de npm ci y después de cada actualización. No almacene en caché los navegadores. https://playwright.dev/docs/ci#caching-browsers
• Divida en fragmentos (shard) con fullyParallel: true y fusione informes blob. https://playwright.dev/docs/test-sharding#balancing-shards
• Serialice las pruebas que comparten un recurso con un bloqueo, no con el modo serial: test('x', { lock: 'db' }, ...). https://playwright.dev/docs/test-parallel#test-locks

Instantáneas

• Sin -u, una instantánea faltante se escribe Y la prueba falla. --update-snapshots=missing escribe y pasa. -u significa changed. https://playwright.dev/docs/aria-snapshots#updating-snapshots-with-playwrighttest-and-the---update-snapshots-flag
• Las líneas de base de las capturas de pantalla son por navegador y sistema operativo. Genérelas donde se comparan. https://playwright.dev/docs/test-snapshots#introduction

Patrones antiguos

Antiguo	Actual	Fuente
locator.type(), page.type()	locator.fill(), o pressSequentially()	https://playwright.dev/docs/release-notes#version-138
page.$(), ElementHandle, page.$eval + expect genérico	Localizador + aserción 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
Pseudoclase :visible	locator.visible()	https://playwright.dev/docs/release-notes#version-163
Selectores text=Log in, id=, data-testid=	getByText, getByTestId	https://playwright.dev/docs/other-locators#legacy-text-locator
Selectores de diseño :right-of(), :near()	Localizadores visibles por el usuario	https://playwright.dev/docs/other-locators#css-matching-elements-based-on-layout
Selectores _react, _vue	Localizadores estándar	https://playwright.dev/docs/release-notes#version-158
page.accessibility	@axe-core/playwright	https://playwright.dev/docs/release-notes#version-157
globalSetup para inicio de sesión o siembra	Proyecto de configuración con dependencies	https://playwright.dev/docs/test-global-setup-teardown#introduction
test.describe.configure({ mode: 'serial' }) para un recurso compartido	Bloqueos de prueba	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, o use.video en el ejecutor	https://playwright.dev/docs/release-notes#version-160
Opción de lanzamiento devtools: true	args: ['--auto-open-devtools-for-tabs']	https://playwright.dev/docs/release-notes#version-158
Bandera -gv	--grep-invert o -G	https://playwright.dev/docs/release-notes#version-154
npx playwright open para grabar	npx playwright codegen	https://playwright.dev/docs/release-notes#version-154
updateSnapshots: 'all' para actualizar las cambiadas	'changed' ('all' reescribe todo)	https://playwright.dev/docs/release-notes#version-150
waitUntil: 'networkidle'	Espera automática y aserciones web-first	https://playwright.dev/docs/puppeteer#automation-example
@playwright/experimental-ct-* con JSX mount(<C />)	Stories + mount('Story/Id', props) de @playwright/test	https://playwright.dev/docs/test-components#migration-from-the-experimental-packages
Navegadores descargados por npm install	npx playwright install --with-deps	https://playwright.dev/docs/release-notes#version-138

Archivos de referencia

Archivo	Léalo para
references/locators.md	Prioridad de localizadores, coincidencia de texto, estrictez, filter, within, and / or, visible(), shadow DOM, frames, selectores heredados
references/actions-and-events.md	Verificaciones de accionabilidad por acción, force, entrada, arrastrar y soltar, diálogos, descargas, subidas, popups, navegación, hidratación, evaluate, scripts de inicialización, handles
references/assertions.md	Matchers web-first versus genéricos, tiempos de espera de aserciones, expect.poll, toPass, aserciones suaves, matchers personalizados, test.step
references/snapshots-and-accessibility.md	Modos de actualización de instantáneas, instantáneas aria, tolerancias y nombres de toHaveScreenshot, instantáneas no de imagen, escaneos axe
references/configuration.md	Estructura de configuración, alcances y valores predeterminados de use, proyectos y dependencias, dispositivos y emulación, manejo de TypeScript, webServer
references/timeouts-retries-annotations.md	Cada tiempo de espera y su valor predeterminado, reintentos y reinicios de workers, modo serial, skip / fail / fixme, tags, pruebas y proyectos parametrizados
references/fixtures-and-auth.md	Aislamiento, fixtures personalizados, alcances, opciones, orden de ejecución, hooks globales, proyectos de configuración, page objects, autenticación storageState, roles, cuentas por worker
references/network-and-mocking.md	route, reglas glob, encabezados y redirecciones que una ruta no puede tocar, grabación y reproducción HAR, mocks WebSocket, mocks de API del navegador, service workers
references/api-testing-and-clock.md	Fixture request, cookies compartidas versus aisladas, eliminación de contextos, métodos y orden de page.clock
references/ci-parallel-sharding.md	Línea base de CI, GitHub Actions y otros proveedores, workers, fullyParallel, bloqueos de prueba, fragmentación (sharding), fusión de informes blob
references/browsers-and-docker.md	Instalación y caché de navegadores, canales de Chromium, proxies y mirrors, imagen Docker, extensiones de Chrome, WebView2, Selenium Grid
references/debugging-and-reporting.md	Banderas de CLI, --debug, Inspector, modos de traza y vídeo, visor de trazas, modo UI, reporters
references/component-testing-and-migration.md	Pruebas de componentes con stories y galería, migración desde paquetes ct experimentales, Testing Library, Protractor, Puppeteer
references/codegen-and-agent-tooling.md	Codegen, Library versus Test, canales de lanzamiento, Agentes de prueba, playwright-cli, Playwright MCP
references/version-changes.md	Cambios de comportamiento disruptivos, APIs eliminadas y obsoletas con reemplazos, cambios de soporte de plataforma

Las fuentes y los detalles de obtención se enumeran en SOURCES.md.