Cómo escribir tu primer test automatizado con Playwright

El 34,1% de las ofertas de QA activas en España pide Playwright como parte de los requisitos técnicos. Es la herramienta de automatización más solicitada del mercado, por delante de Selenium y Cypress.

Pero pedir Playwright en una oferta no es lo mismo que saber usarlo. Si vienes del testing manual y nunca has escrito un test automatizado, el salto puede dar respeto: no sabes por dónde empezar, ni qué es realmente un "selector estable", ni cómo organizar los archivos sin que la suite se convierta en un caos a las dos semanas.

Esta guía es ese primer paso. Vas a instalar Playwright, escribir un test real de principio a fin, entender por qué unos selectores se rompen y otros no, y dejar la base para organizar tu primera suite.

Fuente del primer dato: 17lab, análisis de 82 ofertas de QA activas en España (9 de agosto de 2026). Detalle completo en qué piden las ofertas de QA en España.

Qué necesitas antes de instalar Playwright

Playwright funciona sobre Node.js, así que necesitas tenerlo instalado (versión 18 o superior). Si vienes de testing manual y nunca has tocado una terminal, este es el único requisito real: todo lo demás lo instala Playwright por ti.

La instalación es un único comando. Ábrelo en una terminal, dentro de la carpeta de tu proyecto:

npm init playwright@latest

El instalador pregunta tres cosas: si quieres usar TypeScript o JavaScript, dónde guardar los tests (por defecto, una carpeta tests/) y si quieres añadir un workflow de GitHub Actions. Para empezar, JavaScript y las opciones por defecto son suficientes. El comando descarga también los tres navegadores que Playwright controla: Chromium, Firefox y WebKit.

Tu primer test, línea a línea

Playwright genera un archivo de ejemplo, pero vamos a escribir uno desde cero para entender cada parte. Este test abre una página de login, rellena el formulario y comprueba que el acceso funciona:

const { test, expect } = require('@playwright/test');

test('el login funciona con credenciales validas', async ({ page }) => {
  await page.goto('https://miapp.com/login');

  await page.getByLabel('Correo electronico').fill('usuario@example.com');
  await page.getByLabel('Contrasena').fill('password123');
  await page.getByRole('button', { name: 'Entrar' }).click();

  await expect(page.getByText('Bienvenido')).toBeVisible();
});

Cuatro conceptos, uno por línea de acción:

• page.goto() navega a la URL que le pases. Es siempre el primer paso.
• page.getByLabel() busca un campo de formulario por su etiqueta visible, no por su ID interno. Si el equipo de desarrollo cambia el ID, el test no se rompe.
• page.getByRole() busca por el rol de accesibilidad del elemento (botón, enlace, campo de texto). Es la forma más estable de localizar cosas.
• expect().toBeVisible() es la aserción: lo que de verdad decide si el test pasa o falla.

Para ejecutarlo y verlo correr en un navegador de verdad (útil mientras aprendes):

npx playwright test --headed

Selectores: por qué unos tests se rompen solos y otros no

El error más común de quien empieza en automatización no es de sintaxis, es de selectores. Un test que localiza elementos por una clase CSS generada automáticamente se rompe cada vez que el equipo de frontend toca el diseño, aunque la funcionalidad no haya cambiado en nada.

El primero depende de la estructura exacta del HTML y de una clase que probablemente genera una herramienta de build (Webpack, Vite) de forma distinta en cada compilación. El segundo depende de algo que casi nunca cambia sin motivo: el rol del elemento y el texto que ve la persona usuaria.

Playwright recomienda un orden de preferencia para elegir selectores: primero getByRole, luego getByLabel y getByText, después getByTestId (si el equipo de desarrollo añade atributos data-testid a propósito para testing) y, como último recurso, selectores CSS o XPath.

Aserciones: qué comprobar en cada test

Una aserción es la línea que decide si el test pasa o falla. Sin aserciones, un test solo hace clics: no comprueba nada.

• toBeVisible(). Comprueba que un elemento está visible en pantalla.
• toHaveText(). Comprueba que un elemento contiene un texto exacto.
• toHaveURL(). Comprueba que la navegación llevó a la URL esperada.
• toBeEnabled() / toBeDisabled(). Comprueba si un botón o campo se puede interactuar.
• toHaveCount(). Comprueba cuántos elementos coinciden con un selector, útil en listas y tablas.

Una regla que ahorra dolores de cabeza: cada test debería comprobar una sola cosa. Si un test hace login, crea un pedido y comprueba el envío de un email, cuando falle no vas a saber cuál de las tres partes se rompió sin leer el log entero.

Cómo organizar tu primera suite sin liarla

Con un test ya funcionando, la tentación es escribir veinte más en el mismo archivo. No lo hagas. La estructura que mejor escala es un archivo por funcionalidad:

tests/
  login.spec.js
  registro.spec.js
  carrito.spec.js
  checkout.spec.js
playwright.config.js

Para ejecutar toda la suite:

npx playwright test

Y para revisar qué pasó, con capturas y vídeo de cada paso que falló:

npx playwright show-report

Cuando la suite crezca más allá de cuatro o cinco archivos, el siguiente paso natural es el patrón Page Object (separar la lógica de cada pantalla en su propia clase) y conectar la ejecución a un pipeline de CI/CD para que los tests corran solos en cada cambio de código. Eso ya no es contenido de "primer test": es lo que se trabaja en profundidad en automatización avanzada.

Lo que Playwright no resuelve por ti

Aprender la sintaxis de Playwright en una tarde es posible. Saber qué merece la pena automatizar, no.

Automatizar un flujo que cambia cada semana es tiempo perdido: acabas dedicando más horas a arreglar el test que las que ahorra. Automatizar un flujo crítico y estable (login, checkout, un formulario que da negocio) sí compensa desde el primer día.

Esa decisión, qué automatizar y qué no, sigue siendo un criterio de testing manual: partición de equivalencia, valores límite, prioridad de negocio. Playwright ejecuta el test que tú decides que hay que ejecutar, no decide por ti. Si esa parte todavía no la tienes afianzada, conviene reforzarla antes de automatizar a ciegas: la base está en cómo escribir casos de prueba en QA.