Notas prácticas: Creación de un complemento Agentic Playwright para interfaces de usuario empresariales

Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: crear una herramienta Agentic Playwright destinada a la automatización de interfaces de usuario empresariales. El enfoque está en pasos operativos claros, verificaciones explícitas y código que se puede incorporar directamente a un repositorio sin necesidad de adivinar su propósito. En la etapa de descripción general, se definen las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Se registran los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de una demostración a entornos compartidos.

El problema que resolvíamos

Al trabajar en la etapa “El problema con el que nos enfrentamos”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin ese registro desperdicia horas.

Use the harness to add manager role CRM coverage.

check MCP access,
inspect existing coverage,
use Playwright Agents or capture workflows,
reuse framework layers,
run focused tests,
update the graph,
and report evidence.

El flujo de trabajo diario

Al trabajar en la etapa del Flujo de Trabajo Diario, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar ciclos del agente sin esa huella desperdicia horas.

Prompt: create tests for manager role flow
  -> check whether MCP is available and allowed
  -> if yes, use official Playwright Agents for exploration or healing
  -> if no, use capture workflows and Playwright CLI evidence
  -> in both paths, follow the same harness standards
  -> verify with npx playwright test

Modo 1: MCP disponible

Al trabajar en la fase Mode 1 MCP Available, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Prefiera unidades pequeñas y probables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin ese registro desperdicia horas. Al trabajar en la fase Mode 1 MCP Available, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Anote los tiempos de ejecución y el costo del token o la consulta junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos.

Official Playwright Agents
  + MCP browser context
  + Harness standards
  + Playwright test verification
  = faster generation with team governance

Modo 2: MCP no disponible

La etapa de MCP no disponible en el Modo 2 funciona mejor cuando se trata como una superficie medible. Capture un registro de éxito, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

Prompt
  + local context files
  + capture workflows
  + playwright-cli snapshots
  + npx playwright test
  + trace/report evidence
  = no-MCP agentic Playwright workflow

Flujos de captura: la capa CLI práctica

Los flujos de trabajo de captura: la etapa práctica funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente. Exponga herramientas con esquemas limitados y etiquetas explícitas sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

playwright-cli open http://127.0.0.1:4173/login
playwright-cli localstorage-set ...
playwright-cli goto http://127.0.0.1:4173/crm/accounts
playwright-cli snapshot --filename=contexts/captures/crm-manager-accounts-loaded.yml

npm run capture:recipes:generate
npm run capture:recipe -- --list
npm run capture:crm:manager -- --dry-run
npm run capture:crm:manager

Día 1, Día 2 y después

La etapa Día 1 Día 2 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. La etapa Día 1 Día 2 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos.

Día 1: Agregar un nuevo flujo

Para la etapa del Día 1, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

Create manager role flow tests and assert which buttons are accessible and not
accessible.

Día 2: Ejecutar las pruebas existentes

Para la fase de ejecución del Día 2, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

npm test
npm run test:smoke
APP_BASE_URL=http://127.0.0.1:4173 npm run sample:crm:test

Más adelante: Actualice solo lo que haya cambiado

Solo para actualizaciones posteriores: en qué etapa definir las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado. Autentique en la pasarela de entrada y vuelva a autorizarlo en el plano de datos. Un token de portador por sí solo no constituye un límite entre entornos. Solo para actualizaciones posteriores: en qué etapa definir las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo de los tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos.

Failure on manager reports page
  -> inspect Playwright output and trace
  -> check existing reports capture
  -> refresh manager reports capture if stale
  -> fix the owning layer
  -> rerun the focused test

Las capas del framework

Al trabajar en la etapa de Las capas del framework, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin esa huella desperdicia horas.

Layer                                           Purpose
AGENTS.md and .github/copilot-instructions.md   Tell agents how to behave
contexts/*.yml                                  Store command, strategy, graph, loop, and capture rules
contexts/capture-recipes.yml                    Defines repeatable capture workflows as YAML recipes
contexts/captures/                              Stores curated page context
specs/                                          Human-readable flow plans
fixtures/                                       Shared setup, auth, browser context, page instantiation
pages/                                          Locators and user actions
assertions/                                     Reusable web-first expectations
data/                                           Test data builders
tests/                                          Executable Playwright specs
graphs/                                         Generated source, coverage, duplicate, and visual reports

Inteligencia de grafo consciente del código fuente

Al trabajar en la etapa de Inteligencia de Gráfico Consciente de la Fuente, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles del agente sin esa huella desperdicia horas.

npm run source:manifest -- --root=path/to/app --output=source-manifest.json --url=http://localhost:3000 --name=my-app

scripts/source-adapters/generic-source.mjs

generic scanner creates baseline manifest
  -> agent reviews source, tests, captures, and graph gaps
  -> agent enriches missing auth, roles, states, and workflow intent
  -> capture workflow becomes curated reusable page context
  -> Playwright tests verify behavior
  -> graph reports remaining gaps and duplicate risks

npm run source:manifest:crm
npm run source:manifest:crm:check

npm run graph:view

graphs/index.html#coverage
graphs/index.html#candidates
graphs/index.html#inputs

Ejemplo: Mejora en la cobertura del rol de administrador

Al trabajar en la etapa de cobertura de roles del Administrador de Ejemplos, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Mida el rendimiento en un conjunto fijo de preguntas antes de ajustar los prompts. El cambio constante de prompts rara vez soluciona un sistema de recuperación deficiente. Al trabajar en la etapa de cobertura de roles del Administrador de Ejemplos, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos.

Before graph
  -> identify missing manager coverage
  -> generate/update manager capture workflow
  -> capture manager page states
  -> add page-object and assertion helpers
  -> add manager role tests
  -> rerun graph

Aplicación de prueba de CRM de ejemplo:

La etapa de la aplicación de prueba de CRM de ejemplo funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

Cómo pueden adoptarlo los equipos

La etapa de “Cómo pueden adoptarlo los equipos” funciona mejor cuando se trata como una superficie medible. Capture un registro ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

Fase 1: Agregar instrucciones para el agente

La etapa de Fase 1 Add Agent funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente. La etapa de Fase 1 Add Agent funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos.

Fase 2: Alinear el Framework Playwright

En la Fase 2, antes de modificar el código, se debe definir la etapa a alinear, los insumos necesarios, el responsable de cada paso y los criterios de finalización. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Se debe mantener la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Se debe autenticar en la pasarela y volver a autorizar en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

specs/
tests/
fixtures/
pages/
assertions/
data/
contexts/captures/

Fase 3: Agregar flujos de trabajo de captura

Para la etapa de Captura Adicional de Fase 3, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Autentique en la pasarela y vuelva a autorizar en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.

npm install -g @playwright/cli@latest

npm run capture:recipes:generate
npm run capture:recipe -- --list
npm run capture:crm:manager -- --dry-run
npm run capture:crm:manager

Fase 4: Revisión del gráfico

En la fase 4 Add Graph, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado. Autentique en la pasarela de entrada y vuelva a autorizarlo en el plano de datos. Un token de portador por sí solo no constituye un límite entre entornos. En la fase 4 Add Graph, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo de los tokens o consultas junto con los resultados funcionales. Tener visibilidad sobre los costos desde el principio evita facturas inesperadas cuando la tarea pasa de un entorno de demostración a uno compartido.

npm run graph:view

Fase 5: Utilizar los mismos comandos en CI

Al trabajar en la Fase 5 “Utilizar la etapa”, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes sin ese historial desperdicia horas.

npm run typecheck
npm test
npm run test:smoke
npm run graph:view

Ejemplos de prompts que pueden usar los equipos

Al trabajar con los ejemplos de solicitudes que pueden utilizar los equipos, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Almacene en caché las instrucciones estables del sistema y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de agotamiento.

Use the harness to add coverage for this role-based business flow.

check MCP access
refresh or read the source manifest
inspect existing specs, tests, captures, and graph coverage
use MCP agents or the relevant capture workflow
reuse framework layers
run focused Playwright tests
update the graph
report evidence

Use the harness to debug this failing test.

inspect Playwright output, trace, and artifacts
check existing captures for the affected page or state
refresh source manifest or affected capture only if stale
fix the owning layer
rerun focused verification

Use the harness to review missing coverage.

refresh or read the source manifest
run graph view
identify missing role, state, route, capture, and assertion coverage
check duplicate risks
recommend next flows
avoid creating tests unless asked

Use the harness to refactor repeated selectors and assertions.

inspect existing tests, page objects, and assertion helpers
preserve behavior
move repeated selectors to page objects
move repeated expectations to assertion helpers
run typecheck and focused tests
update graph if coverage ownership changed

Qué obtienen los equipos

Al trabajar en la etapa de “What Teams Get”, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Prefiera unidades pequeñas y probables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin ese registro desperdicia horas. Al trabajar en la etapa de “What Teams Get”, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Anote los tiempos de ejecución y el costo del token o la consulta junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos.

Pensamiento final

La etapa de “Pensamiento final” funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

prompt
  -> mode router
  -> context
  -> capture workflow or MCP exploration
  -> framework layers
  -> Playwright verification
  -> evidence
  -> graph feedback

Referencias

La etapa de Referencias funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.

Lista de verificación operativa

La etapa de la Lista de verificación operativa funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance.

Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.

Exponga las herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores deben saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

Coloque la aprobación humana en las operaciones que generan gastos o modifican datos de producción. La conexión en tiempo de compilación no equivale a una solución completa para el negocio.

Escriba un manual breve: cómo rotar claves, cómo vaciar la cola y cómo revertir la última inserción.

Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.

Antes de promocionar la solución, congele las versiones, capture una transcripción de referencia para el camino crítico y confirme los pasos de reversión. Los entornos compartidos necesitan límites de velocidad, verificaciones de asignación y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.

Nota por lotes para fa507de22687: mantener las claves del proveedor fuera del repositorio, establecer un límite para los tokens por sesión y almacenar las transcripciones junto a los archivos de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.