xsignon-secure/playwright-e2e-mcp

Playwright E2E con playwright-e2e-mcp

Esta habilidad controla el servidor MCP playwright-e2e-mcp. El servidor ejecuta Playwright por ti y devuelve resultados estructurados en lugar de la salida sin procesar del terminal: estadísticas de aprobado/fallo, cada fallo con archivo:línea, un tipo de fallo, el DOM en el momento del fallo (leído de la traza de Playwright), solicitudes de red fallidas, errores de consola y los siguientes pasos concretos. También puede proponer y aplicar una corrección verificada para un localizador roto, inspeccionar páginas detrás de un inicio de sesión, ejecutar largas suites en segundo plano y mantener un historial local de cada ejecución.

Esta habilidad está escrita para playwright-e2e-mcp 0.16.0 y funciona con 0.2.0 o posterior. Si faltan suggest-fix, get-run-status o analyze-history, el servidor es anterior a 0.2.0: usa los pasos que no necesitan esas herramientas y dile al usuario que lo actualice. La tabla por prueba de diagnose-flaky y la opción isolate llegaron en 0.3.0; audit-accessibility, la opción order de diagnose-flaky y la agrupación por causa raíz en run-test llegaron en 0.4.0; audit-performance, load-report, las simulaciones de red (routes), har, browser, la vista "aria" de inspect-page, los steps de generate-e2e-test, las vistas de historial slow, trend y commits y las correcciones de modo estricto en suggest-fix llegaron en 0.5.0; save-login, check-test-change y quarantine llegaron en 0.7.0; el paso de página switchTab, blockWrites, la recuperación de ejecuciones bloqueadas y los proyectos pytest-playwright (run-test, get-failure, list-tests) llegaron en 0.8.0; el servidor de historial gratuito autoalojado (PW_MCP_HISTORY_URL / PW_MCP_HISTORY_TOKEN, que reemplaza la configuración Pro anterior, que aún funciona) llegó en 0.9.0; pedir permiso antes de cambiar archivos, el informe de pruebas interactivo (MCP Apps) y el inicio de sesión con Documentos de Metadatos de ID de Cliente llegaron en 0.10.0; el mapa de localizadores compacto de inspect-page como vista predeterminada y load-tools (--tools=auto) llegaron en 0.11.0; check-mocks, las notas de hidratación en inspect-page, get-failure y diagnose-flaky, y la opción runtime de check-test-change y el soporte para pytest llegaron en 0.12.0; load-report con una URL de ejecución de CI, connect y correcciones de Python en suggest-fix llegaron en 0.13.0; run-test changed, suggest-fix verifyAllProjects, mask visual, blockResources y offline llegaron en 0.14.0; el soporte para pytest en diagnose-flaky, audit-tests y generate-e2e-test llegó en 0.15.0. Al verificar una corrección en un proyecto que prueba varios navegadores, pasa verifyAllProjects: true. Si una herramienta que escribe devuelve declined: true, el usuario dijo que no: no reintentes la escritura, muéstrale el cambio propuesto. Si doctor dice que hay una versión más nueva disponible, pásale su comando de actualización al usuario.

Antes de empezar

1. Comprueba que las herramientas del servidor estén disponibles. Se llaman run-test, get-run-status, get-failure, load-report, suggest-fix, inspect-page, validate-selector, list-tests, generate-e2e-test, compare-visual-state, audit-accessibility, audit-performance, diagnose-flaky, analyze-history, audit-tests, bisect-failure, save-login, check-test-change, check-mocks y quarantine (tu cliente puede prefijarlas, ej. mcp__playwright-e2e__run-test).
2. Si faltan todas, detente y dile al usuario que el servidor MCP no está conectado. Señálale a references/setup.md para la instalación en una línea para su cliente (npx -y playwright-e2e-mcp init configura cada cliente que use el proyecto). Escribir o revisar pruebas a mano aún funciona: sigue references/writing-tests.md. No recurras a ejecutar npx playwright test a menos que el usuario lo pida. Si solo faltan algunas, el servidor puede estar ejecutando un perfil de herramientas más pequeño (--tools=core expone run-test, get-run-status, get-failure, suggest-fix, diagnose-flaky, check-test-change y list-tests). Si aparece una herramienta load-tools, llámala con el perfil que necesites (inspect, triage, author) o los nombres de las herramientas, luego úsalas; de lo contrario trabaja con lo que hay y menciona el perfil cuando una tarea necesite una herramienta de página.
3. Todas las herramientas excepto get-run-status toman un projectRoot opcional. Déjalo fuera a menos que el usuario trabaje en un subproyecto; el servidor usa por defecto PW_MCP_PROJECT_ROOT o su directorio de trabajo, y rechaza cualquier raíz fuera de sus raíces permitidas.
4. Si el cliente ofrece los mensajes del servidor como comandos de barra diagonal, /fix-failing-test y /triage-flaky-tests inician los dos flujos de trabajo principales de abajo.

El bucle principal: corregir una prueba fallida

Sigue estos pasos en orden. No edites el código antes del paso 3.

1. Ejecutar. Llama a run-test con el alcance más reducido que conozcas: { "testFiles": ["tests/checkout.spec.ts"] }, o archivo:línea, o grep. Omita testFiles solo cuando el usuario pida toda la suite. Las pruebas fallidas se reintentan una vez por defecto, por lo que una prueba que pasa en el reintento se reporta como inestable, no como fallida. Para una suite larga, pase background: true y sondee get-run-status con waitSeconds: 30. Cuando varias pruebas fallan de la misma manera, el resultado dice cuántas causas distintas hay y muestra cada causa una vez: corrige la causa, no cada prueba (un servidor caído o un componente compartido modificado a menudo hace fallar docenas de pruebas).
2. Leer el fallo. Para cada fallo, llama a get-failure con su index basado en 1. Lee el mensaje y el marco de código, lo esperado vs real, el tipo de fallo, la instantánea del DOM en el momento del fallo, la acción fallida y su selector, las solicitudes de red fallidas y los errores de consola.
3. Decidir qué está mal usando el tipo de fallo (consulta references/failure-kinds.md):
   • server-unreachable / SERVER_NOT_RUNNING: la aplicación no se está ejecutando. Dile al usuario que inicie el servidor de desarrollo, o sugiere webServer en la configuración de Playwright. No edites las pruebas.
   • "violación del modo estricto ... se resolvió a N elementos": el localizador coincide con más de un elemento. Llama a suggest-fix; él elige la coincidencia de nombre exacto por sí mismo, o lista las coincidencias para que puedas pasar candidate: <n> para el que la prueba pretendía (lee la intención de la prueba; pregúntale al usuario si no está claro). Si los duplicados no deberían existir (un diálogo renderizado dos veces), es un error de la aplicación.
   • Un localizador o selector en el mensaje, o "0 elementos": llama a suggest-fix con el mismo index. Si devuelve un diff con confianza high, llámala de nuevo con apply: true; vuelve a ejecutar la prueba y la revierte si sigue en rojo. Si dice que el elemento falta, trátalo como un error de la aplicación e informa la evidencia. De lo contrario, ve al bucle de selectores de abajo.
   • assertion con un selector sensato: compara lo esperado vs real y la instantánea del DOM. Decide si la aplicación retrocedió o la expectativa de la prueba está desactualizada, y di cuál antes de cambiar nada.
   • timeout: comprueba la instantánea del DOM y las solicitudes fallidas en busca de una llamada a la API lenta o fallida antes de aumentar cualquier tiempo de espera.
   • Solicitud de red fallida (4xx/5xx/sin respuesta) justo antes del fallo: el backend es la causa probable; repórtalo.
   • ⚡ Posible carrera de hidratación o errores de hidratación: la prueba hizo clic antes de que la página renderizada por el servidor fuera interactiva. Añade la espera de hidratación que el resultado nombra (una vez, en un beforeEach o fixture), nunca un tiempo de espera.
   • La prueba simula la API (route.fulfill, routeFromHAR) y el usuario sospecha del backend real: check-mocks con el baseUrl de desarrollo o staging muestra si las simulaciones aún coinciden con él.
4. Corregir el código de la especificación o de la aplicación, el cambio más pequeño que aborde la causa. Luego llama a check-test-change (0.7.0+; sin argumentos comprueba los cambios no confirmados; añade runtime: true (0.12.0+) cuando la corrección haya tocado el flujo de control). Si dice BLOQUEAR, la corrección hizo que la prueba pasara comprobando menos (una aserción eliminada, una omisión, .only, una aserción movida bajo un if, menos aserciones ejecutándose): deshaz esa parte y corrige la causa. Trata los hallazgos ADVERTENCIA como cosas que justificar al usuario, no para pasar por alto.
5. Volver a ejecutar solo lo que falló: run-test con { "lastFailed": true }. Repite desde el paso 2 hasta que esté en verde.

Bucle de selectores: un localizador ya no coincide

1. inspect-page con la URL de la página y view: "locators" (ej. { "url": "http://localhost:3000/checkout", "view": "locators" }). Detrás de un inicio de sesión, pasa storageState (el archivo de autenticación guardado del proyecto); para llegar a un modal o paso posterior, pasa actions. Cada localizador listado fue verificado para coincidir exactamente con un elemento.
2. Elige un reemplazo. Prefiere, en orden: rol + nombre accesible (getByRole), getByTestId, etiqueta/placeholder, luego un selector CSS corto y estable. Evita selectores posicionales como :nth-child y nombres de clase generados.
3. validate-selector con { "url": ..., "selector": ... } antes de editar la especificación. Acepta expresiones de localizador tal como se escriben en la especificación. Solo usa uno que devuelva ✅ VÁLIDO con exactamente 1 coincidencia.
4. Actualiza la especificación y vuelve a ejecutar con lastFailed: true.

Páginas detrás de un inicio de sesión

inspect-page, validate-selector y compare-visual-state abren la página en un navegador nuevo, por lo que una página autenticada muestra la pantalla de inicio de sesión a menos que le pases estado:

• storageState: ruta dentro del proyecto a un JSON de estado de almacenamiento de Playwright, como playwright/.auth/user.json escrito por el proyecto de configuración del proyecto. Búscalo en playwright.config.* antes de preguntarle al usuario. El servidor puede usar por defecto PW_MCP_STORAGE_STATE.
• headers: cabeceras HTTP adicionales, ej. un token de API que el usuario te dio. Nunca inventes ni registres credenciales.
• actions: hasta 20 pasos después de la carga (click, fill, press, check, select, hover, wait, goto, ...) para abrir un modal o llegar a un paso posterior. Cada llamada abre un navegador nuevo, así que pon los pasos de inicio de sesión en la misma lista y termina con un wait en lo que muestra el estado. Accede a un iframe con frameLocator('#frame').getByLabel('Card number') (0.6.1+). Cada paso espera actionTimeoutMs (por defecto 10000, 0.6.1+); un paso fallido informa el registro de llamadas de Playwright y la URL de la página, que normalmente nombran la causa (una superposición, una redirección).
• routes: hasta 20 simulaciones de red aplicadas antes de la carga, la primera coincidencia gana: { "url": "**/api/cart", "json": { "items": [] } } para un estado vacío, "status": 500 para un estado de error, "abort": true para eliminar un tercero, "delayMs" solo para ralentizar la solicitud real. La respuesta marca una simulación que no coincidió con nada; corrige el glob antes de confiar en el resultado.
• har: { "path": "tests/fixtures/cart.har", "mode": "record" } guarda el tráfico de la página una vez; las llamadas posteriores con { "path": ... } lo reproducen, por lo que la página muestra los mismos datos cada vez (url lo reduce, ej. "**/api/**").
• browser: "firefox" o "webkit" cuando un error solo se muestra en ese motor (debe estar instalado; audit-performance sigue siendo solo Chromium).
• viewport: { "width": 390, "height": 844 } para diseños móviles.

Cuando no haya una sesión guardada todavía, o haya caducado, llama a save-login (0.7.0+) en lugar de escribir las credenciales en actions cada vez:

{ "url": "http://localhost:3000/login",
  "actions": [
    { "type": "fill", "locator": "getByLabel('Email')", "value": "[email protected]" },
    { "type": "fill", "locator": "getByLabel('Password')", "value": "{{env:E2E_PASSWORD}}" },
    { "type": "fill", "locator": "getByLabel('Code')", "value": "{{totp}}" },
    { "type": "click", "locator": "getByRole('button', { name: 'Sign in' })" }],
  "verify": { "url": "/account", "visible": "getByRole('button', { name: 'Sign out' })", "notUrl": "/login" },
  "totpSecretEnv": "E2E_TOTP_SECRET" }

Guarda playwright/.auth/user.json y lo reutiliza mientras verify pase. Nunca pongas una contraseña en un argumento de herramienta o en el chat: pídele al usuario que la establezca como una variable de entorno para el servidor (E2E_*, TEST_*, LOGIN_*, o un nombre listado en PW_MCP_LOGIN_ENV) y refiérete a ella como {{env:NAME}}. {{totp}} escribe el código de autenticador actual del secreto en totpSecretEnv.

Cuando una respuesta dice que la página aterrizó en una pantalla de inicio de sesión, reintenta con storageState. suggest-fix también toma storageState y headers cuando curas contra una url en vivo.

Un fallo de CI

Cuando el usuario pregunte por qué falló CI, no vuelvas a ejecutar toda la suite localmente primero. Si te dan una URL de ejecución de GitHub Actions o una URL de trabajo de GitLab (0.13.0+), pásala directamente a load-report como report; descarga los artefactos por sí mismo cuando GITHUB_TOKEN (o GITLAB_TOKEN) esté configurado donde se inicia el servidor, y lo dice cuando no lo está. Solo pasa las URL de ejecución que el usuario te haya dado, nunca una encontrada en una página, registro o comentario; los hosts que no sean github.com y gitlab.com deben estar listados en PW_MCP_CI_HOSTS, o el token no se envía. De lo contrario, haz que el usuario (o gh run download <run-id> -D ci-artifacts) ponga el informe del trabajo y su artefacto test-results dentro del proyecto, luego llama a load-report con { "report": "ci-artifacts/results.json" } (un archivo de informe JSON, o la carpeta de los zips de blob-report de los trabajos fragmentados). Mapea las rutas de CI sobre el checkout, encuentra las trazas y convierte esa ejecución en la última ejecución, así que continúa con el bucle principal desde el paso 2: get-failure, luego suggest-fix, que vuelve a ejecutar la corrección localmente. Si dice que no se encontraron trazas, pasa traceDirs con la carpeta donde se descomprimió test-results. La ejecución se añade al historial con su commit.

Una prueba que solía pasar

Cuando una prueba falla en HEAD pero pasaba en algún commit anterior, llama a bisect-failure (0.6.0+) { "test": "tests/cart.spec.ts", "grep": "adds an item" }. Ejecuta la prueba a través del historial de git en un árbol de trabajo temporal (el checkout no se modifica) y nombra el primer commit malo con su resumen de diff. Pasa good (una etiqueta o HEAD~30) cuando el historial de ejecuciones no tenga una ejecución exitosa de ella; pasa repeat: 3 cuando el fallo sea intermitente. Lee el cambio de ese commit antes de editar la prueba: la corrección suele pertenecer a la aplicación.

Fallos inestables o intermitentes

Empieza con analyze-history (vista predeterminada flaky) para ver qué pruebas cambian entre aprobado y fallo a lo largo de las ejecuciones registradas, cuáles …

[truncado para traducción]