Playwright incluye tres agentes desde la versión 1.56: planner explora la aplicación y produce un plan de pruebas en Markdown, generator convierte ese plan en archivos de Playwright Test verificando localizadores en vivo, y healer ejecuta la suite y repara los tests que fallan. Se instalan con npx playwright init-agents --loop=<tu herramienta> y funcionan con VS Code, Claude Code, Codex y OpenCode. La pieza que decide el resultado no es el modelo: es el test semilla, el archivo que deja la aplicación lista y que sirve de ejemplo de estilo para todo lo generado. Y lo que no delegan: decidir qué probar y revisar cada parche.
Ver índice de contenidos
Qué son y qué no son
Conviene empezar por lo que no son, porque el nombre confunde. Los agentes de Playwright no son un modelo de lenguaje, ni un servicio en la nube, ni una herramienta que genera tests sola. Son definiciones de agente: archivos de instrucciones que Playwright instala en tu repositorio para guiar a un modelo de lenguaje —el de tu herramienta de IA— a través del proceso de construir un test.
La documentación oficial los presenta así, y son tres:
- 🎭 planner explora la aplicación y produce un plan de pruebas en Markdown.
- 🎭 generator transforma ese plan en archivos de Playwright Test.
- 🎭 healer ejecuta la suite y repara automáticamente los tests que fallan.
Se pueden usar por separado, en secuencia o encadenados en un bucle agéntico. Usarlos en secuencia es lo que produce cobertura del producto.
Playwright aporta las instrucciones, el conocimiento de sus propias APIs y las herramientas para manejar el navegador e inspeccionar la página. Vos aportás el modelo, a través de tu herramienta de IA, y el criterio. Esa división explica por qué el resultado varía tanto según el modelo que uses y, sobre todo, según lo que le des como punto de partida.
Instalación de las definiciones
Si ya tenés Playwright en el proyecto —si no, está en la guía de cómo instalar y usar Playwright— agregar los agentes es un comando, con la variante de tu herramienta:
# Genera los archivos de agente para cada bucle agéntico
# Visual Studio Code
npx playwright init-agents --loop=vscode
# Claude Code
npx playwright init-agents --loop=claude
# Codex
npx playwright init-agents --loop=codex
# OpenCode
npx playwright init-agents --loop=opencodeDos requisitos y una advertencia que conviene no saltear:
- Los agentes llegaron en Playwright 1.56. En versiones anteriores el comando no existe.
- En VS Code hace falta la versión 1.105 o posterior para que la experiencia agéntica funcione correctamente.
- Regenerá las definiciones cada vez que actualices Playwright. La documentación lo pide explícitamente: las definiciones traen las instrucciones y la lista de herramientas de esa versión, y quedarse con las viejas es pedirle al modelo que use un mapa desactualizado.
El test semilla: la pieza que decide
Acá está la diferencia entre un flujo que funciona y uno que produce ruido, y es la parte que casi nadie prepara. El test semilla es un test que ya deja tu aplicación en el estado necesario para poder interactuar con ella.
// tests/seed.spec.ts
import { test, expect } from './fixtures';
test('seed', async ({ page }) => {
// este test usa las fixtures propias de ./fixtures
});Parece trivial y no lo es, porque cumple dos funciones al mismo tiempo:
- Lo ejecuta para llegar al estado inicialEl planificador corre este test para disparar toda la inicialización que tu suite necesita: la configuración global, las dependencias entre proyectos, las fixtures y los hooks. Sin eso, un agente que abre tu aplicación se queda en la pantalla de inicio de sesión.
- Lo usa como ejemplo de todo lo que genereY esta es la parte que cambia el resultado. El estilo, las importaciones, las fixtures y las convenciones del semilla se propagan a cada test generado.
La consecuencia práctica, dicha sin vueltas
Los agentes no van a inventar una arquitectura de tests mejor que la que les mostrás. Si tu semilla usa fixtures propias, page objects y datos controlados, lo generado va a seguir ese patrón. Si es un test improvisado con selectores frágiles, vas a recibir veinte tests improvisados con selectores frágiles, más rápido que antes. Invertir una hora en el semilla rinde más que cualquier ajuste al prompt.
El planificador
El planificador explora tu aplicación y produce un plan de pruebas para uno o varios escenarios y flujos de usuario. Recibe tres cosas:
- Un pedido claro. La documentación usa como ejemplo «generá un plan para la compra como invitado». Cuanto más acotado, mejor: un pedido del tipo «probá toda la aplicación» produce un plan enorme y superficial.
- El test semilla. Mencionado en el contexto o por nombre de archivo.
- Opcionalmente, un documento de requisitos del producto, que le da el contexto de qué comportamiento es el correcto.
La salida es un archivo Markdown en specs/, y este es el punto más interesante del diseño: el plan es legible por personas pero lo bastante preciso para generar tests. Ese doble carácter es lo que lo vuelve el lugar natural para revisar antes de que se escriba una sola línea de código.
Un plan típico incluye una descripción de la aplicación, la lista de escenarios y, para cada uno, los pasos numerados y los resultados esperados. Si algo está mal en el plan, corregirlo cuesta editar un párrafo; si el error llega al código generado, cuesta revisar veinte archivos. El plan es el punto de control barato.
El generador
El generador toma el plan en Markdown y produce los tests ejecutables. Su característica distintiva es la que más lo separa de pedirle tests a un modelo cualquiera: verifica localizadores y aserciones en vivo mientras ejecuta los escenarios.
Esa diferencia es grande y vale explicarla. Un modelo escribiendo tests «a ciegas» inventa selectores plausibles que fallan cuando se ejecutan. El generador, en cambio, va probando: si un localizador no encuentra el elemento, lo descubre en el momento y busca otro. Playwright además le ofrece pistas de generación y un catálogo de aserciones para validaciones estructurales y de comportamiento.
El resultado es un test que, en el buen caso, se parece bastante a uno escrito a mano por alguien que conoce las buenas prácticas de Playwright:
// tests/add-valid-todo.spec.ts
// spec: specs/basic-operations.md
// seed: tests/seed.spec.ts
import { test, expect } from '../fixtures';
test.describe('Adding New Todos', () => {
test('Add Valid Todo', async ({ page }) => {
const todoInput = page.getByRole('textbox', { name: 'What needs to be done?' });
await todoInput.fill('Buy groceries');
await todoInput.press('Enter');
await expect(page.getByText('Buy groceries')).toBeVisible();
await expect(page.getByText('1 item left')).toBeVisible();
await expect(todoInput).toHaveValue('');
});
});Fijate en las dos primeras líneas de comentario: el test generado deja registrada su procedencia —de qué plan salió y con qué semilla—. Es un detalle chico con valor real cuando dentro de tres meses hay que entender por qué existe ese test.
La documentación es explícita en algo que conviene esperar: los tests generados pueden incluir errores iniciales, y esos son los que el siguiente agente repara.
El sanador
Cuando un test falla, el healer hace cuatro cosas en orden: repite los pasos que fallaron, inspecciona la interfaz actual para localizar elementos o flujos equivalentes, propone un parche —actualizar un localizador, ajustar una espera, corregir un dato— y vuelve a ejecutar el test hasta que pasa o hasta que sus límites detienen el bucle.
Su salida es un test que pasa o, y esto es importante, un test omitido si el agente cree que la funcionalidad está rota. Ese comportamiento está bien diseñado: reconoce que hay fallos que no son del test.
El sanador está diseñado para reparar el test, no para cuestionar si la aplicación está bien. Si el test fallaba porque encontró un defecto real, un parche que ajusta el localizador o agrega una espera silencia el hallazgo: la suite vuelve al verde y el defecto sigue ahí. Por eso cada parche del sanador tiene que pasar por revisión humana con una pregunta concreta: ¿esto era un test desactualizado o era un problema del producto?
La regla práctica que se desprende: usá el sanador con generosidad sobre tests recién generados —donde los errores son casi siempre de generación— y con desconfianza sobre tests que venían pasando y de golpe fallan, porque ahí la probabilidad de estar tapando un defecto es mucho más alta.
La estructura de archivos
Los artefactos siguen una estructura simple y auditable, lo que permite tratarlos como código normal: revisarlos, versionarlos y discutirlos en una revisión de cambios.
| Artefacto | Qué es | Quién lo produce |
|---|---|---|
| Definiciones de agente | Los archivos de instrucciones que instala init-agents | Playwright; se regeneran al actualizar |
tests/seed.spec.ts | El test semilla que prepara el entorno | Vos, a mano |
specs/*.md | Los planes de prueba legibles | El planificador; los revisás vos |
tests/*.spec.ts | Los tests ejecutables | El generador; los revisás vos |
Que el plan sea un archivo Markdown versionado tiene una ventaja que se aprecia con el tiempo: cuando alguien pregunta «¿por qué probamos esto así?», la respuesta está escrita en lenguaje natural al lado del código, y no hay que reconstruirla leyendo aserciones.
Los agentes y el servidor MCP
Es la confusión más común, porque son dos cosas distintas que llegaron con pocas versiones de diferencia. Desde Playwright 1.62, Playwright incluye su servidor MCP, ejecutable con npx playwright mcp.
| Agentes (1.56) | Servidor MCP (1.62) | |
|---|---|---|
| Qué es | Definiciones de flujo de trabajo para escribir tests | Un canal genérico para que un modelo controle un navegador |
| Para qué sirve | Planificar, generar y reparar una suite | Cualquier tarea con navegador: explorar, extraer datos, verificar algo puntual |
| Produce | Archivos versionados en tu repositorio | Acciones y observaciones en la sesión |
Dicho de otro modo: el MCP le da a un modelo manos para operar un navegador; los agentes le dan un método para construir tests. Se complementan, y para el objetivo de esta guía —automatizar pruebas— el punto de entrada son los agentes.
Qué no resuelven
Una lectura honesta, porque el entusiasmo alrededor de esto suele omitir la mitad:
- No deciden qué vale la pena probar. Un plan generado cubre lo que la aplicación hace; cuál de esos comportamientos es crítico para el negocio y cuál es accesorio lo decidís vos. Eso es estrategia de prueba, y no se delega.
- No distinguen un comportamiento correcto de un defecto. Si la aplicación tiene un error, el planificador puede documentarlo como comportamiento esperado y el generador escribir un test que lo consagra. Un documento de requisitos en el contexto reduce el riesgo; no lo elimina.
- No garantizan buenas aserciones. Un test puede pasar comprobando algo trivial. La pregunta al revisar no es «¿pasa?» sino «¿fallaría si la funcionalidad se rompiera?».
- No eliminan la inestabilidad. Los tests generados pueden ser inestables como cualquier otro, y el sanador tiende a resolver la inestabilidad agregando esperas, que es el parche que más la esconde. El tema completo está en cómo detectar y solucionar flaky tests.
- No son gratis. Cada ejecución consume tokens del modelo que uses, y el bucle del sanador puede reintentar varias veces. Conviene medirlo antes de dejarlo suelto en integración continua.
- Ven tu aplicación. El modelo procesa el contenido de las pantallas por las que pasa, así que valen las precauciones de datos de siempre: entornos de prueba y datos que no sean reales.
Cuándo conviene y cuándo no
| Situación | ¿Conviene? | Por qué |
|---|---|---|
| Cubrir con tests una aplicación que ya funciona y no tiene ninguno | Sí, mucho | Es el caso ideal: hay comportamiento estable que documentar y el volumen es el problema |
| Ampliar cobertura de flujos secundarios ya conocidos | Sí | Trabajo mecánico y repetitivo con criterio ya definido |
| Reparar una suite que se rompió por un rediseño de la interfaz | Sí, con revisión | Es exactamente lo que hace el sanador, pero cada parche se revisa |
| Escribir los tests de una funcionalidad que todavía se está discutiendo | No | Sin comportamiento definido, el agente documenta lo que encuentra, no lo que debería ser |
| Validar reglas de negocio complejas o cálculos | No | Necesita conocimiento del dominio que no está en la pantalla |
| Un equipo sin nadie que sepa leer Playwright | No todavía | Todo el flujo depende de revisar lo generado; sin eso, la suite se vuelve un pasivo |
Errores frecuentes
- Empezar sin test semilla. Es el error que arruina el resultado y el más común. El agente se queda en la pantalla de inicio de sesión o genera tests con un estilo que no es el de tu proyecto.
- Pedir «probá toda la aplicación». Produce un plan larguísimo y superficial. Un pedido por flujo, acotado, produce planes que se pueden revisar.
- No revisar el plan y saltar al código. Corregir el Markdown cuesta un párrafo; corregir veinte archivos generados cuesta una tarde.
- Aceptar los parches del sanador sin mirar. Es la vía más rápida para tener una suite verde que no detecta nada.
- No regenerar las definiciones al actualizar Playwright. El agente queda trabajando con instrucciones y herramientas de una versión anterior.
- Medir el éxito por cantidad de tests. Veinte tests generados que comprueban lo trivial valen menos que tres que fallarían si la funcionalidad se rompe.
- Correrlos contra datos reales. El modelo ve el contenido de las pantallas por las que pasa.
Preguntas frecuentes
¿Qué son exactamente los agentes de Playwright?
No son un modelo ni un servicio: son tres definiciones de agente que Playwright instala en tu proyecto para guiar a un modelo de lenguaje a través del proceso de construir un test. El planner explora la aplicación y produce un plan en Markdown, el generator convierte ese plan en archivos de Playwright Test, y el healer ejecuta la suite y repara los tests que fallan. El modelo lo aportás vos a través de tu herramienta de IA; Playwright aporta las instrucciones y las herramientas que ese modelo puede usar.
¿Desde qué versión de Playwright están disponibles?
Los agentes llegaron en Playwright 1.56, con el comando npx playwright init-agents. Después, en la versión 1.62, Playwright empezó a incluir su propio servidor MCP, ejecutable con npx playwright mcp. Son dos cosas distintas y conviene no confundirlas: los agentes son definiciones de flujo de trabajo específicas para escribir tests, y el servidor MCP es la vía genérica para que un modelo controle un navegador. La documentación recomienda regenerar las definiciones cada vez que actualizás Playwright.
¿Qué es el test semilla y por qué importa tanto?
Es un test que ya deja la aplicación en el estado necesario para interactuar con ella: fixtures propias, configuración global, inicio de sesión, datos de partida. El planificador lo ejecuta para llegar a ese estado, y además lo usa como ejemplo de todos los tests que va a generar. Ahí está su doble papel y por eso decide el resultado: si tu semilla usa page objects y fixtures propias, lo generado también; si es un test improvisado, vas a recibir tests improvisados en la misma medida.
¿El healer puede dejar un test roto pareciendo que funciona?
Puede dejar un test que pasa sin comprobar lo que debía, sí, y es el riesgo principal de todo el flujo. El healer está diseñado para reparar el test, no para cuestionar si la aplicación está bien: si el fallo era un defecto real, un parche que ajusta el localizador o la espera silencia el hallazgo. La documentación aclara que, cuando cree que la funcionalidad está rota, marca el test como omitido en lugar de forzarlo, pero eso no reemplaza la revisión humana de cada parche.
¿Reemplazan a una persona de QA?
No, y conviene ver qué desplazan. Los agentes reducen mucho el costo de escribir y mantener el código de los tests, que era la parte mecánica. Lo que no hacen es decidir qué vale la pena probar, cuál es el riesgo del negocio, qué comportamiento es correcto y qué comportamiento es un defecto disfrazado. El cuello de botella se mueve de teclear a decidir y revisar, y esas dos son justamente las tareas donde el criterio de una persona de QA no tiene sustituto.
¿Sirven si mi aplicación no es pública o necesita inicio de sesión?
Sí, y es el caso normal: para eso existe el test semilla. Todo lo que necesite la aplicación para quedar utilizable —autenticación, datos precargados, variables de entorno, dependencias entre proyectos— se resuelve ahí, y los agentes trabajan a partir de ese estado. Lo que conviene tener presente es que el modelo va a ver el contenido de tu aplicación, así que valen las mismas precauciones de datos que con cualquier herramienta de IA: entornos de prueba y datos que no sean reales.
Fuentes
Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 27 de julio de 2026.
Aportes de la comunidad Underc0de
- Underc0de, foro. Curso completo de Playwright desde cero, por ANTRAX, sección QA y Testing, 3 de agosto de 2024.
- Underc0de, foro. Playc0de: ejecutando pruebas con Playwright desde 0, por Mavis, 14 de julio de 2023.
- Underc0de, foro. Sección QA y Testing. Hilos de la comunidad sobre automatización de pruebas.
Documentación oficial
- Playwright. Playwright Test Agents. Los tres agentes, sus entradas y salidas, el papel del test semilla, los comandos de
init-agents, el requisito de VS Code 1.105 y la estructura de artefactos. - Playwright. Release notes. Versión 1.56, que introdujo los agentes, y versión 1.62, que incorporó el servidor MCP ejecutable con
npx playwright mcp.