Tu primer flujo E2E con un agente

Objetivo

Al terminar tendrás un test end-to-end (E2E) de un flujo crítico de tu proyecto, escrito por tu agente a partir de un plan que tú revisaste, en verde, y comprobado como capaz de fallar cuando la app se rompe.

La regla de trabajo de esta guía: el agente ejecuta el test y reporta; tú decides qué se corrige.

Prerrequisitos

Playwright instalado en tu proyecto (ver la guía de instalación), con baseURL y webServer configurados.
Un agente de código conectado a tu proyecto. Esta guía usa Claude Code.
Un lugar donde el flujo pueda escribir datos sin riesgo: una base de datos local o una rama de desarrollo de tu base de datos. Nunca tus datos de producción.

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

Pasos

1. Elegir un flujo crítico

Elige un flujo corto, importante para el negocio y estable. Ejemplos: registrarse, iniciar sesión, reservar una cita, completar una compra. Escribe su resultado esperado en una frase, por ejemplo: "un visitante puede reservar una cita y ve una confirmación".

Un flujo es suficiente para esta guía. Los tests E2E son lentos y costosos de mantener, por eso se reservan para lo que nunca debe romperse.

2. Pedirle al agente un plan, no código

Quiero un test E2E de este flujo: un visitante reserva una cita
desde la página de reservas.
No escribas código todavía. Explora la app y escribe un plan en
lenguaje natural: el estado inicial, cada paso que da el usuario,
qué debe ver al final y qué datos crea el flujo.
Espera mi aprobación.

Lee el plan con atención. Corrígelo si un paso está mal o falta un resultado. Este es tu punto de revisión: es mucho más barato corregir un plan que un test.

3. Generar el test a partir del plan aprobado

Escribe el test de Playwright a partir del plan aprobado.
Usa localizadores por rol y texto visible, aserciones que esperan
solas, sin esperas fijas, y un flujo en un test.
Después corre el test.

El resultado debería verse así (ilustrativo, tus textos serán distintos):

import { test, expect } from '@playwright/test';
 
test('a visitor can book an appointment', async ({ page }) => {
  await page.goto('/booking');
  await page.getByRole('button', { name: 'Baño' }).click();
  await page.getByLabel('Nombre').fill('Ana');
  await page.getByRole('button', { name: 'Confirmar' }).click();
  await expect(page.getByText('Tu cita está confirmada')).toBeVisible();
});

4. Ejecutar el test y hacer que el agente reporte

Corre `npx playwright test`.
Si falla, no cambies ningún archivo. Reporta: qué paso falló,
qué muestran el screenshot y el trace, si crees que el test está
desactualizado o que la app tiene un bug, y el arreglo que propondrías.

El agente solo reporta. Tú decides qué pasa después.

5. Decidir qué se corrige

Cuando un test falla, hay dos diagnósticos posibles:

El test quedó desactualizado (cambió un texto, una etiqueta o un paso a propósito): actualiza el test, después de confirmar que la intención realmente cambió.
La app tiene un bug: corrige el código de la aplicación y no toques el test. El test es el juez. Si lo editas para que pase, deja de protegerte.

Luego vuelve a correr el test.

6. Comprobar que el test detecta un bug

Un test que siempre pasa no vale nada. Rompe la app a propósito, por ejemplo cambiando el nombre de un campo en la petición que tu frontend envía al API, y corre el test: debe fallar. Después revierte el cambio y comprueba que vuelve a pasar.

Resultado esperado

Un test E2E de un flujo crítico de tu proyecto, en verde.
El mismo test fallando cuando rompes la app a propósito, con un reporte claro del agente.
Un plan en lenguaje natural guardado en tu proyecto o en tus notas.

Troubleshooting

Problemas comunes

El test pasa la primera vez y falla la segunda: el flujo crea datos (por ejemplo un horario reservado) que chocan en la siguiente ejecución. Usa datos distintos en cada corrida, o limpia después del test. Corre contra una base de datos de pruebas, no contra una real.
El agente editó el test para que pase: rechaza el cambio y revisa el diff. Un test "arreglado" sin que tú decidieras que la intención cambió puede estar escondiendo un bug real.
El test nunca falla, ni siquiera cuando rompes la app: sus aserciones son demasiado débiles. Pídele al agente que compruebe lo que el usuario debe ver al final del flujo.
El test falla al azar: busca esperas fijas y localizadores frágiles. Prefiere localizadores por rol y texto visible, y aserciones que esperan solas.
La app no arranca para el test: revisa webServer y baseURL en playwright.config.ts.

Siguiente paso

Agrega un segundo flujo, cuando el primero sea estable. Si quieres ir más lejos, Playwright (desde la v1.56) incluye tres definiciones de agente que puedes generar para Claude Code con npx playwright init-agents --loop=claude: un planner que explora la app y escribe un plan en Markdown, un generator que convierte el plan en tests y un healer que repara los tests que fallan. Vuelve a generarlas cada vez que actualices Playwright. Ten en cuenta que el healer trabaja en bucle hasta que el test pasa, así que revisa cada cambio que hace.