Playwright CLI: el repositorio para probar apps web con agentes de IA

La documentación oficial muestra cómo abrir páginas, inspeccionar snapshots accesibles, interactuar con elementos y guardar capturas. En esta guía usaremos el demo público TodoMVC para probar un flujo simple sin login ni datos personales.

En este artículo verás:

• Para qué sirve Playwright CLI y cómo se diferencia de MCP.
• Cómo instalar la CLI y, opcionalmente, la skill del proyecto.
• Cómo pedirle a un agente que recorra un flujo y registre lo que observó.
• Cuidados con sesiones, cookies y entornos de producción.

Qué hace Playwright CLI

Playwright CLI controla un navegador mediante comandos de terminal. Un agente puede abrir una página, leer el snapshot de la interfaz, hacer clic o completar campos y capturar una imagen. Después de cada acción, la herramienta devuelve el estado observado; el agente puede usar las referencias actualizadas para continuar.

El repositorio oficial incluye una skill que explica los comandos y enlaza a guías más detalladas. Las instrucciones de instalación mencionan Claude Code, GitHub Copilot y otros agentes compatibles con skills locales. Incluso sin instalar la skill, se puede pedir al agente que consulte playwright-cli --help y use los comandos disponibles.

Requisitos previos e instalación

La documentación de instalación de Playwright CLI pide Node.js 20 o más reciente. Hay una diferencia respecto a los metadatos del paquete más reciente en npm, que declaran compatibilidad con Node.js 18 o más reciente. Para evitar sorpresas, usa Node 20+ y revisa la documentación antes de instalar.

Instala la CLI globalmente y revisa los comandos:

$ npm install -g @playwright/cli@latest
$ playwright-cli --help

Si el proyecto ya tiene Playwright como dependencia, la documentación también muestra cómo revisar la instalación local y llamar a la CLI mediante npx playwright cli.

Para inicializar el espacio de trabajo e instalar el navegador necesario, sigue la etapa de inicialización del workspace:

$ playwright-cli install

Ese comando crea la carpeta .playwright, añade esa carpeta al .gitignore y descarga el navegador configurado cuando es necesario. La documentación explica que el navegador también puede descargarse automáticamente en el primer uso.

Para instalar las instrucciones de la skill en el patrón compartido .agents/skills, usa:

$ playwright-cli install --skills=agents

En Claude Code, playwright-cli install --skills usa por defecto la carpeta .claude/skills. La ruta .agents/skills solo será descubierta automáticamente por agentes que soporten ese patrón; de lo contrario, pídele al agente que ejecute la CLI directamente. Ver detalles en la página oficial de instalación de skills.

Haz una prueba segura en TodoMVC

El quick start oficial usa una demo pública de TodoMVC. Abre el navegador visible y pide una inspección inicial:

$ playwright-cli open https://demo.playwright.dev/todomvc/ --headed
$ playwright-cli snapshot

El snapshot muestra el árbol accesible de la página y referencias que pueden usarse en los siguientes comandos. Esas referencias se generan para la sesión: no copies un identificador de un tutorial antiguo. Lee el snapshot más reciente antes de hacer clic o completar un campo.

Puedes pedirle al agente:

Usa el Playwright CLI para probar https://demo.playwright.dev/todomvc/. Inspecciona el snapshot antes de interactuar. Agrega dos tareas, marca una como completada y revisa en el snapshot el estado de cada elemento. Guarda una captura de pantalla e informa solo las verificaciones que observaste. No inicies sesión ni navegues a otros dominios.

Cuando termines, la captura puede guardarse con playwright-cli screenshot --filename=todo-flow.png y la sesión cerrarse con:

$ playwright-cli close

La demostración prueba solo el flujo recorrido en ese momento. Una captura no demuestra que se hayan probado todos los requisitos de tu producto. Para probar tu aplicación, cambia la dirección por el entorno de staging, define antes los criterios de aceptación e incluye estados de error que importen para tu caso.

CLI o MCP: ¿cuál elegir?

Playwright CLI y Playwright MCP son formas diferentes de conectar automatización de navegador a un agente. En la CLI, el agente ejecuta comandos de terminal; en el MCP, llama a herramientas estructuradas. La documentación oficial compara estos dos modos y sugiere la CLI para flujos de coding agents y el MCP para exploraciones que se benefician de una sesión larga e introspección continua. Esta es la orientación del mantenedor, no un benchmark independiente que pruebe que una opción es siempre más rápida.

Si tu necesidad es conectar un servidor de navegador al chat de VS Code, consulta también nuestra guía de configuración de MCP en VS Code. Para organizar tareas y revisar el código después de las pruebas, consulta los seis pasos para trabajar con agentes de programación.

Seguridad: usa datos de prueba y cuida la sesión

Comienza por una página pública o por un entorno de prueba. La CLI puede hacer clic, completar formularios y enviar acciones; por lo tanto, no la apunte a producción con permisos de escritura sin definir límites y supervisión.

Por defecto, la sesión mantiene cookies y almacenamiento mientras el navegador está abierto, pero el estado se pierde cuando se cierra. La opción --persistent guarda el perfil en disco. La documentación de almacenamiento y autenticación advierte que los archivos generados por playwright-cli state-save pueden contener tokens de autenticación: no los envíes al agente sin necesidad y nunca los comitees en el repositorio.

La CLI ayuda a explorar un flujo y registrar evidencias. Para una suite repetible en CI, usa también el Playwright Test, que incluye ejecutor de pruebas, assertions, aislamiento e informes. La propia documentación de Playwright presenta la CLI y el framework de pruebas como opciones distintas.