Guía completa: Instalar y configurar Playwright paso a paso

¿Qué es Playwright y por qué usarlo en tus proyectos QA?

Playwright es una herramienta de automatización desarrollada por Microsoft que permite realizar pruebas end-to-end en aplicaciones web modernas. A diferencia de otras herramientas como Selenium, Playwright fue diseñado específicamente para manejar las aplicaciones web actuales con JavaScript, Single Page Applications (SPAs) y frameworks modernos como React, Angular y Vue.

Las principales ventajas de Playwright incluyen:

• Soporte multi-navegador nativo: Chrome, Firefox, Safari y Edge
• Velocidad superior: Hasta 3 veces más rápido que Selenium
• Auto-waiting inteligente: Espera automáticamente que los elementos estén listos
• Paralelización: Ejecuta pruebas en paralelo por defecto
• Interceptación de red: Mockea APIs y controla requests
• Depuración visual: Grabación de videos y screenshots automáticos

Como QA Engineer, he implementado Playwright en múltiples proyectos y puedo asegurar que reduce significativamente el tiempo de configuración y mantenimiento de las pruebas automatizadas.

Prerrequisitos

Antes de comenzar con la instalación, asegúrate de tener:

• Node.js: Versión 16 o superior (recomendado 18+)
• npm o yarn: Gestor de paquetes (viene con Node.js)
• Sistema operativo: Windows, macOS o Linux
• Memoria RAM: Mínimo 4GB (recomendado 8GB+)
• Espacio en disco: Al menos 1GB libre para navegadores

Para verificar tu versión de Node.js, ejecuta:

node --version

Paso 1: Crear el proyecto base

Primero, creamos un nuevo directorio para nuestro proyecto de pruebas:

mkdir mi-proyecto-playwright
cd mi-proyecto-playwright
npm init -y

Este comando genera un archivo package.json básico que gestionará nuestras dependencias.

Paso 2: Instalar Playwright

Existen dos formas principales de instalar Playwright. Te recomiendo usar la instalación oficial que incluye todo lo necesario:

npm init playwright@latest

Este comando interactivo te preguntará:

• ¿En qué lenguaje quieres escribir las pruebas? (Selecciona TypeScript o JavaScript)
• ¿Dónde ubicar las pruebas? (por defecto: tests/)
• ¿Agregar un workflow de GitHub Actions? (recomendado: sí)
• ¿Instalar navegadores de Playwright? (obligatorio: sí)

Alternativamente, puedes instalar manualmente:

npm install -D @playwright/test
npx playwright install

Paso 3: Estructura del proyecto generada

Después de la instalación, tendrás una estructura similar a esta:

mi-proyecto-playwright/
├── tests/
│   └── example.spec.js
├── tests-examples/
│   └── demo-todo-app.spec.js
├── playwright.config.js
├── package.json
└── package-lock.json

Analicemos los archivos principales:

• playwright.config.js: Configuración principal de Playwright
• tests/: Directorio donde escribirás tus pruebas
• tests-examples/: Ejemplos de pruebas para aprender

Paso 4: Configurar playwright.config.js

El archivo de configuración es el corazón de tu setup. Aquí tienes una configuración optimizada para proyectos QA reales:

// playwright.config.js
const { defineConfig, devices } = require('@playwright/test');

module.exports = defineConfig({
  // Directorio de pruebas
  testDir: './tests',
  
  // Tiempo máximo por prueba
  timeout: 30 * 1000,
  
  // Configuración de expect
  expect: {
    timeout: 5000
  },
  
  // Configuración de ejecución
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  
  // Configuración de reportes
  reporter: [
    ['html'],
    ['json', { outputFile: 'test-results.json' }],
    ['junit', { outputFile: 'test-results.xml' }]
  ],
  
  // Configuración global
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    headless: true
  },
  
  // Proyectos por navegador
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    // Pruebas móviles
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
  ],
  
  // Servidor local para desarrollo
  webServer: {
    command: 'npm start',
    url: 'http://127.0.0.1:3000',
    reuseExistingServer: !process.env.CI,
  },
});

Paso 5: Crear tu primera prueba

Creemos una prueba básica en tests/mi-primera-prueba.spec.js:

// tests/mi-primera-prueba.spec.js
const { test, expect } = require('@playwright/test');

test('verificar título de la página', async ({ page }) => {
  // Navegar a la página
  await page.goto('https://mundoqa.com');
  
  // Verificar que el título contiene "Mundo QA"
  await expect(page).toHaveTitle(/Mundo QA/);
});

test('buscar artículo específico', async ({ page }) => {
  await page.goto('https://mundoqa.com');
  
  // Buscar el campo de búsqueda
  await page.click('[aria-label="Buscar"]');
  
  // Escribir término de búsqueda
  await page.fill('input[type="search"]', 'Playwright');
  
  // Presionar Enter
  await page.press('input[type="search"]', 'Enter');
  
  // Verificar resultados
  await expect(page.locator('.search-results')).toBeVisible();
});

Paso 6: Ejecutar las pruebas

Para ejecutar tus pruebas, usa estos comandos:

# Ejecutar todas las pruebas
npx playwright test

# Ejecutar en modo headed (con interfaz gráfica)
npx playwright test --headed

# Ejecutar en un navegador específico
npx playwright test --project=chromium

# Ejecutar una prueba específica
npx playwright test mi-primera-prueba.spec.js

# Ejecutar en modo debug
npx playwright test --debug

Paso 7: Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto para manejar configuraciones sensibles:

# .env
BASE_URL=https://staging.miapp.com
USER_EMAIL=test@mundoqa.com
USER_PASSWORD=password123
API_KEY=abc123def456

E instala dotenv para cargar las variables:

npm install -D dotenv

Actualiza tu playwright.config.js:

require('dotenv').config();

module.exports = defineConfig({
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    // otras configuraciones...
  },
});

Casos de uso reales en proyectos QA

1. Pruebas de formularios complejos

Playwright es excelente para validar formularios con múltiples campos y validaciones:

test('validar formulario de registro', async ({ page }) => {
  await page.goto('/registro');
  
  // Llenar formulario
  await page.fill('#email', 'usuario@test.com');
  await page.fill('#password', 'MiPassword123!');
  await page.selectOption('#pais', 'Colombia');
  await page.check('#terminos');
  
  // Enviar formulario
  await page.click('button[type="submit"]');
  
  // Verificar redirección exitosa
  await expect(page).toHaveURL('/dashboard');
  await expect(page.locator('.welcome-message')).toBeVisible();
});

2. Pruebas con interceptación de API

Puedes mockear respuestas de API para probar diferentes escenarios:

test('manejar error de API', async ({ page }) => {
  // Interceptar llamada a API
  await page.route('**/api/users', route => {
    route.fulfill({
      status: 500,
      contentType: 'application/json',
      body: JSON.stringify({ error: 'Error interno del servidor' })
    });
  });
  
  await page.goto('/usuarios');
  
  // Verificar mensaje de error
  await expect(page.locator('.error-message')).toContainText('Error interno');
});

3. Pruebas visuales y de regresión

Playwright puede capturar screenshots para comparaciones visuales:

test('validar diseño de página principal', async ({ page }) => {
  await page.goto('/');
  
  // Capturar screenshot para comparación visual
  await expect(page).toHaveScreenshot('homepage.png');
  
  // Capturar elemento específico
  await expect(page.locator('.header')).toHaveScreenshot('header.png');
});

Mejores prácticas y consejos

• Page Object Model: Organiza tu código en clases para reutilizar localizadores
• Datos de prueba: Usa fixtures o archivos JSON para datos de prueba
• Esperas explícitas: Aprovecha el auto-waiting de Playwright
• Paralelización: Ejecuta pruebas en paralelo para mayor velocidad
• CI/CD: Integra con GitHub Actions, Jenkins o tu herramienta preferida

Conclusión y próximos pasos

Has completado exitosamente la instalación y configuración básica de Playwright. Con esta base sólida, puedes comenzar a crear pruebas automatizadas robustas para tus aplicaciones web.

Los siguientes pasos recomendados son:

1. Explorar selectores avanzados: Aprende a usar selectores por rol, texto y atributos
2. Implementar Page Object Model: Estructura tu código de manera escalable
3. Configurar CI/CD: Automatiza la ejecución de pruebas en tu pipeline
4. Pruebas móviles: Explora la emulación de dispositivos móviles
5. Debugging avanzado: Utiliza las herramientas de depuración visual

En próximos tutoriales de Mundo QA, cubriremos cada uno de estos temas en profundidad. Playwright será una herramienta invaluable en tu arsenal como QA Engineer, permitiéndote crear pruebas más confiables y mantenibles.

¿Tienes dudas sobre la configuración o quieres compartir tu experiencia con Playwright? Déjanos un comentario y continuemos aprendiendo juntos en la comunidad de Mundo QA.

---