Pruebas y Depuración de Frontend

¿Qué hace Pruebas y Depuración de Frontend?

Contrato de Invocación

Esta habilidad debe funcionar a partir de solicitudes de usuario normales. No obligue al usuario a especificar el enrutamiento del navegador, las capturas de pantalla, la forma del informe o la política de respaldo.

Use esta habilidad cuando el usuario solicite usar el plugin Build Web Apps, web dev, frontend dev, o la habilidad de pruebas/depuración de frontend para un cambio, prueba o investigación de errores en un frontend renderizado.

Ejemplos que deberían desencadenar este flujo de trabajo completo:

• por favor, haz una mejora en el área de búsqueda de transacciones del panel web y usa el plugin web dev
• usa el plugin frontend dev para pulir este panel
• depura esta UI con el plugin Build Web Apps
• prueba esta aplicación localhost y arregla la interacción rota

A partir de una breve solicitud, infiera la superficie objetivo a partir del repositorio, la URL de la aplicación/navegador actualmente abierta, los archivos cercanos o el servidor de desarrollo en ejecución. Si la URL objetivo no está clara, inspeccione los scripts del repositorio y los puertos locales en ejecución antes de preguntar al usuario.

Para cualquier cambio de código en una superficie frontend renderizada, realice el bucle de validación de forma predeterminada:

1. Identifique el flujo objetivo.
2. Elija la ruta del navegador a continuación.
3. Realice la edición útil más pequeña.
4. Valide el comportamiento renderizado.
5. Responda con el informe final de respuesta de control de calidad.

Elija la Ruta del Navegador

Primero, clasifique la disponibilidad del navegador:

• Disponible: el plugin Browser y su habilidad browser están listados en la sesión. Lea y siga esa habilidad antes de cualquier acción del navegador.
• Ausente: el plugin Browser o la habilidad browser no están listados. Use Playwright normal y registre Plugin Browser no disponible.
• Invocación fallida: Browser parece estar disponible, pero la habilidad/tiempo de ejecución, la configuración de JavaScript REPL de Node, la adquisición de pestañas o la navegación falla. Trate esto como un bloqueador de la ruta del navegador.

No use Playwright normal, Chrome externo o open de shell primero cuando Browser esté disponible.

Solo cambie de una invocación fallida de Browser a Playwright normal si el usuario ya permitió el respaldo o la tarea permite explícitamente la validación sin navegador. En ese caso, informe el error exacto de Browser y la decisión de respaldo.

Flujo Objetivo

Antes de la validación del navegador, defina el flujo objetivo en una oración:

El flujo bajo prueba es: [ruta de entrada] -> [acción o estado del usuario] -> [resultado renderizado esperado].

Si el usuario solicitó una prueba de humo general, use:

El flujo bajo prueba es: la aplicación se carga -> la primera pantalla significativa se renderiza -> los controles visibles principales responden sin errores de tiempo de ejecución.

Bucle del Plugin Browser

Ejecute los comandos del navegador a través de la herramienta REPL de JavaScript de Node descrita por la habilidad Browser. No invente una ruta de configuración del navegador separada. Mantenga el mismo enlace de pestaña a menos que la habilidad Browser indique lo contrario.

Secuencia requerida:

1. Cargue el tiempo de ejecución del navegador exactamente como lo indica la habilidad Browser.
2. Nombre la sesión con agent.browser.nameSession("...").
3. Adquiera una pestaña con agent.browser.tabs.selected() o agent.browser.tabs.new().
4. Navegue con tab.goto(url).
5. Ejecute las comprobaciones requeridas a continuación.
6. Interactúe con localizadores tab.playwright con ámbito o las API de interacción de la habilidad Browser.
7. Después de las ediciones, llame a await tab.reload(), luego repita las comprobaciones y la interacción fallida.

Para cada acción que cambie la UI, recopile la prueba más económica de que el siguiente estado es correcto: instantánea del DOM nueva, texto/estado visible, cambio de URL, control enfocado, toast, modal, captura de pantalla o registro de consola.

Comprobaciones Requeridas del Navegador

Ejecute estas comprobaciones antes de afirmar que la aplicación renderizada funciona:

1. Identidad de la página: await tab.url() y await tab.title() coinciden con la página prevista.
2. No está en blanco: await tab.playwright.domSnapshot() contiene contenido significativo de la aplicación, no un shell vacío.
3. Sin superposición del framework: la instantánea o captura de pantalla no muestra una superposición de error de Next.js, Vite, Webpack o del framework.
4. Salud de la consola: await tab.dev.logs({ levels: ["error", "warn"], limit: 50 }) no tiene errores relevantes de la aplicación, o cada error relevante está explicado.
5. Evidencia de captura de pantalla: await display(await tab.playwright.screenshot({ fullPage: false })) respalda las afirmaciones visuales.
6. Prueba de interacción: se ejercita al menos una interacción del flujo objetivo, seguida de una verificación de estado.

Para trabajo visual, agregue un viewport de escritorio más uno de tamaño móvil cuando sea práctico. Para trabajo basado en referencias, mantenga un breve registro de desajustes: evidencia de referencia, evidencia renderizada, corrección o desviación intencional.

Bucle de Playwright

Use esta rama cuando Browser no esté disponible, o cuando el usuario haya permitido el respaldo después de un error de invocación de Browser.

Use este orden:

1. Encuentre scripts en package.json.
2. Inicie la aplicación con el gestor de paquetes del repositorio y mantenga exacto el host solicitado.
3. Prefiera el script e2e del repositorio si está presente.
4. De lo contrario, ejecute pnpm exec playwright test o el equivalente del gestor de paquetes cuando Playwright esté configurado.
5. Si no hay un flujo de trabajo de Playwright en el proyecto, verifique Playwright con pnpm exec playwright --version, luego capture una captura de pantalla con pnpm exec playwright screenshot <url> /tmp/frontend-check.png.
6. Para una depuración más profunda, cree un pequeño script temporal de Playwright fuera del código fuente comprometido que abra la URL, capture errores de consola, capturas de pantalla y ejecute la interacción objetivo.
7. Después de las ediciones, vuelva a ejecutar el mismo comando o script.

No instale nuevas dependencias del navegador a menos que la tarea lo requiera y el usuario haya permitido cambios de dependencias.

Lista de Verificación de Validación

• Mantenga exacto el host solicitado.
• Verifique que los controles actualicen el estado real de la UI.
• Verifique el primer viewport antes de desplazarse, además de un viewport de escritorio y uno de tamaño móvil cuando sea práctico.
• Busque recortes, superposiciones, texto ilegible, ajuste de línea, desplazamiento de diseño, activos faltantes, problemas de z-index, trampas de desplazamiento, carga obsoleta y estados rotos.
• Para trabajo basado en referencias, compare la captura de pantalla renderizada con la referencia y mantenga un breve registro de desajustes.
• Una compilación exitosa no es suficiente cuando se solicitó validación renderizada.

Informe de Respuesta Final de Control de Calidad

Para cualquier ejecución de validación de UI renderizada no trivial, escriba la respuesta final como un ingeniero de QA que verifica un cambio de código. La respuesta debe facilitar que el usuario o el revisor del PR entiendan qué cambió, qué se probó, qué evidencia lo prueba y qué permanece sin probar.

Use esta forma:

• Resumen: uno o dos puntos que expliquen el cambio visible para el usuario y si la QA pasó.
• Entorno: URL, viewport(s), clasificación de disponibilidad del navegador y motivo del respaldo si se usó Playwright.
• Cambios Verificados: archivos o superficies modificadas, más el comportamiento específico orientado al usuario esperado.
• Comprobaciones: una tabla de aprobado/fallido para identidad de página, verificación de página en blanco, verificación de superposición del framework, salud de la consola, evidencia de captura de pantalla y prueba de interacción.
• Bucle de Interacción: ruta de interacción exacta probada, incluido el control o flujo de trabajo ejercitado y el cambio de estado observado.
• Evidencia: describa la evidencia de las capturas de pantalla en las secciones de QA, luego coloque las capturas de pantalla reales juntas al final de la respuesta como imágenes consecutivas. Incluya tantas capturas de pantalla como sean útiles para probar los estados relevantes anteriores, posteriores, de interacción, responsivos, de error o corregidos.
• Comandos / APIs del Navegador: enumere el comando clave y la secuencia de API del navegador utilizada, sin volcar registros ruidosos.
• Riesgo Restante: viewports, flujos, navegadores, estados de datos o limitaciones conocidas no probados.

Si se encontraron problemas, comience con Hallazgos antes del resumen. Cada hallazgo debe incluir lo que el usuario ve, pasos de reproducción, evidencia de captura de pantalla/DOM/consola, probable propietario o archivo cuando se conozca, y la corrección realizada o el bloqueador restante.

Cuando use capturas de pantalla de Browser que deban mostrarse al usuario, emita o muestre la captura de pantalla a través del tiempo de ejecución de Browser para que pueda ser referenciada en el chat. Cuando use capturas de pantalla de Playwright, guárdelas fuera del repositorio y refiéralas en el chat. Incluya múltiples capturas de pantalla cuando ayuden a verificar estados o flujos distintos.

No intercale capturas de pantalla en el informe escrito. Coloque una breve sección Capturas de Pantalla al final, y haga que sea una galería de imágenes consecutivas con una imagen por línea. Agregue etiquetas cortas solo cuando aclaren el estado, por ejemplo Antes, Después, Resultados filtrados, Estado vacío o Móvil.

No cree informes HTML separados de forma predeterminada. Solo cree un archivo de informe independiente cuando el usuario lo solicite explícitamente, y escríbalo fuera del repositorio a menos que el usuario solicite explícitamente artefactos comprometidos.

No escriba informes, capturas de pantalla, trazas o scripts temporales en el repositorio a menos que el usuario solicite explícitamente artefactos comprometidos.

Habilidades Relacionadas

• Use frontend-app-builder cuando la tarea sea creación de diseño, rediseño o fidelidad a un concepto aceptado.
• Use react-best-practices después de ediciones significativas de componentes React/Next.js.
• No invoque Generación de Imágenes para depuración ordinaria. Úselo solo cuando la tarea requiera crear o revisar activos visuales, o cuando frontend-app-builder ya esté impulsando un bucle de fidelidad de concepto a implementación.

Respuesta Final

Use el formato de informe de respuesta final de QA anterior. Manténgalo conciso, pero incluya suficiente evidencia concreta para que un revisor de PR pueda confiar en la validación sin tener que volver a ejecutarla inmediatamente.

Si Browser estuvo ausente y se usó Playwright, termine sugiriendo que el usuario instale el plugin Browser para una mejor experiencia de desarrollo frontend con navegación en la aplicación, capturas de pantalla, instantáneas del DOM, registros de consola y validación de interacciones.