Instalando Playwright: Guía de Configuración Paso a Paso (2026)

Playwright necesita un solo prerequisito: Node.js. El instalador (npm init playwright@latest) se encarga de todo lo demás: descarga Chromium, Firefox y WebKit como binarios aislados, crea el archivo de configuración, configura un test de ejemplo y genera el .gitignore. Esta guía recorre cada paso, explica qué hace cada archivo instalado, y cubre el único cambio de configuración (baseURL) que hace la escritura de tests menos repetitiva desde el primer día.

Qué necesitás antes de empezar

Una sola cosa: Node.js. Verifica si lo tienes:

node --version
npm --version

Si obtenés números de versión (Node 18 o superior, npm 9 o superior), estás listo. Si no, ve a nodejs.org y descarga la versión LTS. Instálala y vuelve.

No necesitás instalar un navegador por separado. Playwright descarga sus propios binarios de navegador durante la configuración: Chromium, Firefox y WebKit. Están aislados de los navegadores que tengas instalados en tu sistema.

Crear el proyecto

Elige una ubicación para la carpeta y ejecuta:

mkdir playwright-tests
cd playwright-tests
npm init playwright@latest

El instalador hace cuatro preguntas:

Do you want to use TypeScript or JavaScript? › TypeScript
Where to put your end-to-end tests? › tests
Add a GitHub Actions workflow? › false
Install Playwright browsers? › true

Usa TypeScript. Es el estándar profesional y el soporte de TypeScript en Playwright es excelente. Deja la carpeta de tests como tests. Salta GitHub Actions por ahora (puedes agregarlo después). Sí a instalar los navegadores.

La descarga de los navegadores tarda entre 1 y 3 minutos según tu conexión. Playwright descarga Chromium, Firefox y WebKit, aproximadamente 300MB en total.

Qué se instaló

Después de la configuración, el proyecto queda así:

playwright-tests/
  tests/
    example.spec.ts        ← test de ejemplo
  playwright.config.ts     ← configuración
  package.json             ← dependencias
  package-lock.json
  node_modules/            ← paquetes instalados
  .gitignore               ← preconfigurado para Playwright

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Configuraciones clave para entender:

node_modules/
playwright-report/
test-results/

No hagas commit de estas carpetas. Son grandes y se regeneran en cada ejecución.

Ejecutar el test de ejemplo

Antes de escribir cualquier cosa, ejecuta lo que vino con el instalador:

npx playwright test

Salida:

Running 6 tests using 6 workers

  6 passed (8s)

Seis tests porque el ejemplo corre en tres navegadores × dos casos de prueba. Abre el reporte:

npx playwright show-report

Se abre un navegador con un desglose detallado: qué tests corrieron, cuánto tardó cada uno, en qué navegador, y capturas de pantalla. Haz clic en cualquier test para expandirlo.

Configurar para tu proyecto

Los valores por defecto están bien, pero dos cambios mejoran el desarrollo diario. Abre playwright.config.ts y agrega un baseURL:

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'https://lab.becomeqa.com',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Con baseURL configurado, los tests pueden usar page.goto('/') en lugar de la URL completa. Cuando cambies de entorno (dev → staging → producción), cambias una línea en la config en lugar de cada test.

Escribir tu primer test real

Elimina el test de ejemplo y crea tests/login.spec.ts:

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

test('el usuario puede iniciar sesión', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button', { name: 'Login' }).click();
  await page.getByLabel('Username').fill('admin@becomeqa.com');
  await page.getByLabel('Password').fill('testpass123');
  await page.getByRole('button', { name: 'Submit' }).click();

  await expect(page.getByText('My Travel Items')).toBeVisible();
});

Ejecutalo solo en Chromium para mantenerlo rápido:

npx playwright test tests/login.spec.ts --project=chromium

Salida:

Running 1 test using 1 worker

  1 passed (3s)

Comandos útiles de la CLI

# Ejecutar todos los tests
npx playwright test

# Ejecutar un archivo específico
npx playwright test tests/login.spec.ts

# Ejecutar solo en Chromium
npx playwright test --project=chromium

# Ejecutar en modo headed (el navegador se abre visiblemente)
npx playwright test --headed

# Ejecutar en modo debug (pausa en cada paso)
npx playwright test --debug

# Ejecutar tests que coincidan con un patrón de nombre
npx playwright test --grep "login"

# Mostrar el último reporte HTML
npx playwright show-report

# Abrir el modo UI interactivo
npx playwright test --ui

Usar el generador de código

Si no estás seguro de qué locator usar para un elemento, deja que Playwright lo genere por ti:

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

Se abre un navegador. Haz clic por la página y Playwright registra tus acciones y genera el código del test correspondiente en un panel a la derecha. No siempre es perfecto, pero es la forma más rápida de encontrar locators sobre los que no estás seguro.

Entender la estructura del test

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

test('descripción de qué testea esto', async ({ page }) => {
  // tu código de test acá
});

Estructura del proyecto a medida que crece

La estructura por defecto funciona para un puñado de tests. Cuando el suite crece:

playwright-tests/
  tests/
    auth/
      login.spec.ts
      logout.spec.ts
    items/
      items-list.spec.ts
  pages/              ← Las clases Page Object van acá
    LoginPage.ts
    DashboardPage.ts
  fixtures/           ← Los fixtures custom van acá
    auth.fixture.ts
  playwright.config.ts
  package.json

Empieza con tests/ plano. Agrega subcarpetas cuando tengas más de 5 o 6 archivos de tests. Agrega pages/ cuando empieces a repetir los mismos locators en varios tests.

FAQ

Siempre la última. npm init playwright@latest se encarga de esto. Playwright publica versiones frecuentemente y los cambios que rompen la compatibilidad son raros. Mantenerse actualizado es más fácil que ponerse al día después de quedarse atrás.

Cualquiera funciona. npm está bien para aprender. Algunos equipos prefieren pnpm por la eficiencia de espacio en disco en CI. No pienses demasiado en esto.

Ejecuta npx playwright install para reintentar. Si falla un navegador específico, instálalo individualmente: npx playwright install chromium.

No. Playwright es una biblioteca de Node.js. Existen bindings para Python, Java y .NET, pero todos requieren que sus respectivos runtimes estén instalados.

Generalmente es un error de configuración de baseURL o un problema de red. Agrega --timeout=10000 para fallar más rápido durante la depuración: npx playwright test --timeout=10000.