Modo de automatización

El modo de automatización está pensado para bancos de pruebas automatizados que necesitan iniciar Guida, conectarse a WebView2 mediante CDP, abrir un espacio de trabajo, crear pestañas, esperar a que estén listas y cerrar la aplicación de forma determinista.

Está separado de la API del panel operativo y de la API Remote Ops. Los endpoints del panel son endpoints de monitorización en sola lectura. Remote Ops es una API de control por canal de confianza, habilitada explícitamente, para nodos en vivo. Los endpoints de automatización son para bancos de pruebas deterministas y solo están disponibles cuando Guida se inicia con --automation.

Opciones de inicio

Las opciones exclusivas de automatización solo se aceptan cuando --automation está presente.

Opción	Propósito
`--automation`	Habilita el modo de automatización
`--workspace <path>`	Abre un espacio de trabajo al arrancar
`--webview-user-data-dir <path>`	Usa un directorio específico de perfil WebView2
`--cdp-port <port>`	Expone Chrome DevTools Protocol de WebView2 en el puerto indicado
`--dashboard-host <address>`	Sobrescribe la dirección de enlace del servidor integrado
`--dashboard-port <port>`	Sobrescribe el puerto del servidor integrado
`--automation-token <token>`	Define el token requerido por las solicitudes `/api/automation/*`

Si no se proporciona un directorio de datos de usuario de WebView2, Guida crea un perfil temporal aislado para automatización. Si no se proporciona token de automatización, Guida genera uno y lo escribe en la consola.

Ejemplo:

Guida.exe --automation `
  --workspace C:\dev\btbrowser-workspace `
  --webview-user-data-dir C:\temp\guida-webview `
  --cdp-port 9222 `
  --dashboard-host 127.0.0.1 `
  --dashboard-port 9315 `
  --automation-token test-token

Passthrough CDP

Use --cdp-port cuando un banco de pruebas de estilo Playwright necesite conectarse al navegador WebView2 subyacente mediante Chrome DevTools Protocol.

CDP da al banco de pruebas inspección y automatización a nivel de navegador. La API de automatización de Guida cubre operaciones específicas de Guida, como abrir espacios de trabajo, crear pestañas de Guida, activar pestañas, esperar a que estén listas y cerrar la aplicación.

Autenticación

Los endpoints de automatización requieren una de estas formas de cabecera:

X-Guida-Automation-Token: test-token

Authorization: Bearer test-token

Cuando el modo de automatización está deshabilitado, los endpoints /api/automation/* devuelven 404. Cuando el modo está habilitado pero falta el token o es incorrecto, las solicitudes se rechazan.

Endpoints

Todos los endpoints están bajo /api/automation.

Endpoint	Propósito
`GET /api/automation/status`	Devuelve espacio de trabajo, flujo activo, pestaña activa y número de pestañas
`GET /api/automation/session`	Abre un flujo SSE de latido para comprobaciones de ciclo de vida del banco de pruebas
`POST /api/automation/workspace`	Abre un espacio de trabajo desde `{ "path": "..." }`
`GET /api/automation/tabs`	Lista las pestañas de Guida visibles para el banco de pruebas
`POST /api/automation/tabs`	Crea una pestaña desde `{ "name": "...", "url": "...", "activate": true, "waitForLoad": true }`
`POST /api/automation/tabs/{tabId}/activate`	Activa una pestaña existente
`GET /api/automation/tabs/active/ready`	Espera a que la pestaña activa esté lista; admite `timeoutMs`
`POST /api/automation/shutdown`	Solicita el cierre de Guida

Flujo típico del banco de pruebas

Iniciar Guida con --automation, un puerto de panel y un token de automatización conocido.
Llamar a GET /api/automation/status hasta que Guida sea accesible.
Abrir un espacio de trabajo si no se proporcionó al iniciar.
Crear o activar una pestaña de Guida.
Esperar a GET /api/automation/tabs/active/ready.
Conectar el banco de pruebas del navegador al puerto CDP cuando se necesite automatización a nivel de navegador.
Llamar a POST /api/automation/shutdown durante el desmontaje.

Notas de seguridad

Mantenga el modo de automatización local o dentro de un entorno de pruebas de confianza. A diferencia de la API del panel, los endpoints de automatización pueden abrir espacios de trabajo, crear y activar pestañas, y cerrar Guida.

El acceso remoto por red privada sin control debe usar la API del panel operativo en sola lectura. El control remoto por red privada para herramientas de operador debe usar la API Remote Ops, no el modo de automatización.

Siguientes pasos

API del panel operativo - endpoints de monitorización en sola lectura
API Remote Ops - control remoto por canal de confianza para nodos Guida en vivo
Integración MCP - acceso local de herramientas de IA, autorizaciones y registro de trazabilidad
API Navegador y DOM - automatización del navegador desde scripts de Guida