Instalar Playwright: guía básica

Objetivo

Al terminar tendrás Playwright instalado en tu proyecto, un test corriendo contra tu app local y las herramientas para ver por qué falló un test (un screenshot y un trace).

Playwright es un framework de pruebas end-to-end (E2E). Controla un navegador real (Chromium, Firefox o WebKit) como lo haría un usuario y comprueba lo que muestra la página.

Prerrequisitos

• Node.js (una versión LTS reciente) y npm.
• Un proyecto web que puedas correr en local.
• Una terminal abierta en la raíz de ese proyecto.

Esta guía cubre Playwright al estado de octubre de 2026.

Pasos

1. Agregar Playwright a tu proyecto

Desde la raíz del proyecto:

npm init playwright@latest

Hace algunas preguntas. Confirma o elige:

• TypeScript o JavaScript (por defecto: TypeScript).
• La carpeta de tests (por defecto: tests, o e2e si tests ya existe).
• Si agregar un workflow de GitHub Actions (opcional, puedes omitirlo).
• Si instalar los navegadores de Playwright (por defecto: sí).

En un proyecto existente agrega las dependencias a tu package.json, crea un archivo playwright.config.ts y añade un test de ejemplo (example.spec.ts). Puedes volver a ejecutarlo después: no pisa tus tests existentes.

2. Correr los tests

npx playwright test

Por defecto el navegador corre sin ventana (headless).

3. Abrir el reporte

npx playwright show-report

Sirve el reporte HTML en local. Ábrelo con este comando, no con doble clic sobre el archivo.

4. Ver el navegador trabajando

npx playwright test --headed   # abre una ventana del navegador
npx playwright test --ui       # modo UI: pasos en vivo y depuración en el tiempo

5. Apuntar Playwright a tu app

Agrega estas opciones al playwright.config.ts que se generó. Ajusta el comando y el puerto a tu proyecto:

import { defineConfig } from '@playwright/test';
 
export default defineConfig({
  retries: 1,
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

• webServer levanta tu servidor de desarrollo antes de correr los tests, y reutiliza uno que ya esté corriendo.
• baseURL permite usar rutas relativas en los tests: page.goto('/login') abre http://localhost:3000/login.

6. Guardar la evidencia cuando un test falla

Las opciones de arriba ya lo hacen:

• screenshot: 'only-on-failure' guarda un screenshot cuando un test falla.
• trace: 'on-first-retry' graba un trace (una línea de tiempo paso a paso del test) cuando un test se reintenta. Por eso está retries: 1.

Abre un trace con:

npx playwright show-trace trace.zip

Esta evidencia es la que te permite a ti, o a un agente, diagnosticar un fallo sin adivinar.

7. Escribir una comprobación mínima de tu propia app

import { test, expect } from '@playwright/test';
 
test('home page loads', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle(/.+/);
});

Corre con npx playwright test. Cuando pase, puedes borrar el test de ejemplo que se generó.

Resultado esperado

• npx playwright test termina con tests en verde.
• npx playwright show-report abre el reporte.
• Tu configuración tiene baseURL, webServer, trace y screenshot.

Troubleshooting

Siguiente paso

Escribe tu primer flujo end-to-end con un agente: elige un flujo crítico de tu proyecto, haz que el agente lo planifique, genere el test y reporte el resultado.