686 lines
16 KiB
Markdown
686 lines
16 KiB
Markdown
# Manual de uso de la herramienta Browser
|
|
|
|
Este manual explica que tools expone la herramienta browser, como usarlas y que puedes pedirle a OpenCode en la practica.
|
|
|
|
## Alcance actual
|
|
|
|
- Browser: `Chromium` controlado por `Playwright`
|
|
- Integracion: `MCP` por `stdio`
|
|
- Modo por defecto: visible (`headless: false`)
|
|
- Artefactos: capturas en `opencode-browser-tool/artifacts/`
|
|
|
|
## Esquema de respuesta estandar
|
|
|
|
Todas las tools devuelven ahora un formato unificado.
|
|
|
|
Respuesta OK:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"tool": "browser_<tool>",
|
|
"data": {},
|
|
"state": {
|
|
"isOpen": true,
|
|
"currentUrl": "https://..."
|
|
}
|
|
}
|
|
```
|
|
|
|
Respuesta con error:
|
|
|
|
```json
|
|
{
|
|
"ok": false,
|
|
"tool": "browser_<tool>",
|
|
"error": {
|
|
"code": "TOOL_EXECUTION_ERROR",
|
|
"message": "detalle del error"
|
|
},
|
|
"state": {
|
|
"isOpen": false,
|
|
"currentUrl": null
|
|
}
|
|
}
|
|
```
|
|
|
|
## Flujo recomendado de uso
|
|
|
|
1. Abrir sesion de navegador con `browser_open`
|
|
2. Navegar con `browser_navigate`
|
|
3. Interactuar con `browser_click`, `browser_type`, `browser_press`, `browser_scroll`
|
|
4. Esperar estados estables con `browser_wait`
|
|
5. Capturar evidencia con `browser_snapshot`
|
|
6. Inspeccionar estado dinamico con `browser_evaluate`
|
|
7. Cerrar sesion con `browser_close`
|
|
|
|
Importante: todas las tools excepto `browser_open` y `browser_close` requieren sesion abierta. Si no hay sesion, devuelve error.
|
|
|
|
## Espera automatica nativa (comportamiento actual)
|
|
|
|
La herramienta ya incorpora estabilizacion automatica despues de acciones clave.
|
|
|
|
Que significa en la practica:
|
|
|
|
- despues de `browser_navigate`, `browser_click`, `browser_type`, `browser_press`, `browser_scroll` y `browser_evaluate`, la herramienta intenta esperar estado estable por si sola
|
|
- combina `domcontentloaded`, intento de `networkidle` y una ventana de "quietud" de actividad de red
|
|
- si no logra estado estable, aplica salida segura por tiempo maximo para evitar bucles de espera infinita
|
|
|
|
Resultado:
|
|
|
|
- normalmente no necesitas pedir `wait` manual para casos comunes
|
|
- `browser_wait` sigue disponible cuando quieras una condicion explicita (selector/texto/url/timeout)
|
|
|
|
---
|
|
|
|
## Tools disponibles
|
|
|
|
### `browser_help`
|
|
|
|
Devuelve un resumen operativo de la herramienta: capacidades, defaults, notas y ejemplos.
|
|
|
|
Cuando usarla:
|
|
|
|
- al empezar una sesion nueva con un agente que no conoce la tool
|
|
- para recordar comportamiento por defecto (modo visible, timeouts, auto-wait)
|
|
|
|
Parametros: ninguno.
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_health`
|
|
|
|
Devuelve estado operativo actual del runtime browser y artifacts recientes.
|
|
|
|
Incluye:
|
|
|
|
- estado de sesion (`isOpen`, `currentUrl`)
|
|
- actividad de red interna (`inflight`, `lastActivityAgoMs`)
|
|
- comportamiento activo (`verbose`, overlay, delay humano)
|
|
- pasos recientes (`recentSteps`) para diagnostico rapido en vivo
|
|
- lista de artifacts recientes (ruta, fecha, tamano)
|
|
|
|
Parametros:
|
|
|
|
- `limit` (number, opcional): cantidad maxima de artifacts a devolver (default `5`, max `20`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"limit": 5
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_config`
|
|
|
|
Permite leer o cambiar configuracion persistente de la herramienta (guardada en `config/browser-tool.config.json`).
|
|
|
|
Parametros:
|
|
|
|
- `action` (string, opcional): `get` o `set` (default `get`)
|
|
- `browserDefaultKind` (string, opcional): `testing` o `system`
|
|
- `browserSystemExecutablePath` (string, opcional): ruta del navegador del sistema (ej. `/usr/bin/google-chrome`)
|
|
- `browserDefaultPersistentProfile` (boolean, opcional): si `true`, `browser_open` usa perfil persistente por defecto
|
|
- `browserDefaultUserDataDir` (string, opcional): ruta de perfil persistente por defecto
|
|
- `browserDefaultVerbose` (boolean, opcional): modo verbose por defecto (`true` recomendado para operacion)
|
|
- `browserDefaultVerboseOverlay` (boolean, opcional): overlay visual de estado en navegador visible
|
|
- `browserDefaultInteractionDelayMinMs` (number, opcional): minimo de delay humano en acciones interactivas
|
|
- `browserDefaultInteractionDelayMaxMs` (number, opcional): maximo de delay humano en acciones interactivas
|
|
- `reportDefaultSaveToFile` (boolean, opcional): default persistente de `browser_report.saveToFile`
|
|
- `reportDefaultFormat` (string, opcional): `json`, `markdown`, `both`
|
|
|
|
Ejemplo lectura:
|
|
|
|
```json
|
|
{
|
|
"action": "get"
|
|
}
|
|
```
|
|
|
|
Ejemplo cambio persistente:
|
|
|
|
```json
|
|
{
|
|
"action": "set",
|
|
"browserDefaultKind": "system",
|
|
"browserSystemExecutablePath": "/usr/bin/google-chrome",
|
|
"browserDefaultPersistentProfile": true,
|
|
"browserDefaultUserDataDir": "/home/pancho/.chrome-perfil-google-real",
|
|
"browserDefaultVerbose": true,
|
|
"browserDefaultVerboseOverlay": true,
|
|
"browserDefaultInteractionDelayMinMs": 1000,
|
|
"browserDefaultInteractionDelayMaxMs": 3000,
|
|
"reportDefaultSaveToFile": false,
|
|
"reportDefaultFormat": "json"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_diagnostics`
|
|
|
|
Devuelve eventos recientes de diagnostico capturados durante la sesion:
|
|
|
|
- `console` (log, warn, error, etc.)
|
|
- `pageerror` (errores JS no capturados)
|
|
- `requestfailed` (peticiones de red fallidas)
|
|
|
|
Parametros:
|
|
|
|
- `limit` (number, opcional): maximo de eventos devueltos (default `20`, max `200`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"limit": 20
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_diagnostics_clear`
|
|
|
|
Limpia el buffer interno de diagnostico.
|
|
|
|
Uso recomendado: antes de arrancar una prueba nueva para leer solo eventos de ese flujo.
|
|
|
|
Parametros: ninguno.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_observe`
|
|
|
|
Toma una "foto de estado" de la pagina durante el flujo y, opcionalmente, una captura.
|
|
|
|
Uso recomendado:
|
|
|
|
- cuando el flujo parece bloqueado
|
|
- cuando no avanza tras una accion
|
|
- antes de abortar una prueba para entender que esta viendo el navegador
|
|
|
|
Parametros:
|
|
|
|
- `screenshot` (boolean, opcional, default `true`)
|
|
- `label` (string, opcional)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"screenshot": true,
|
|
"label": "mid-flow-check"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_handle_consent`
|
|
|
|
Intenta pulsar botones comunes de consentimiento.
|
|
|
|
Parametros:
|
|
|
|
- `action` (string, opcional): `reject` (default) o `accept`
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"action": "reject"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_handle_human_check`
|
|
|
|
Intenta resolver controles comunes de verificacion humana (incluyendo checkbox de reCAPTCHA cuando es clicable).
|
|
|
|
Estrategia actual:
|
|
|
|
- intenta clic en checkboxs dentro de iframes comunes de reCAPTCHA
|
|
- intenta selectores de captcha tambien en pagina principal
|
|
- usa fallback por coordenadas para controles detectados por texto
|
|
|
|
Uso recomendado:
|
|
|
|
- cuando aparece bloqueo tipo `sorry/index`
|
|
- cuando el flujo queda detenido en "comprueba que eres humano"
|
|
|
|
Parametros: ninguno.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_open`
|
|
|
|
Abre una sesion de `Chromium`.
|
|
|
|
Parametros:
|
|
|
|
- `headless` (boolean, opcional): por defecto `false`
|
|
- `startUrl` (string, opcional)
|
|
- `width` (number, opcional, default `1440`)
|
|
- `height` (number, opcional, default `900`)
|
|
- `browserKind` (string, opcional): `testing` (Playwright managed) o `system` (browser del sistema)
|
|
- `executablePath` (string, opcional): ruta binaria explicita del navegador
|
|
- `persistentProfile` (boolean, opcional): activar perfil persistente
|
|
- `userDataDir` (string, opcional): ruta del perfil persistente (requerido si `persistentProfile=true`)
|
|
- `verbose` (boolean, opcional, default `true`): muestra estado paso a paso en respuestas
|
|
- `verboseOverlay` (boolean, opcional, default `true`): muestra estado en overlay visual en navegador visible
|
|
- `interactionDelayMinMs` (number, opcional, default `1000`)
|
|
- `interactionDelayMaxMs` (number, opcional, default `3000`)
|
|
- `recordVideo` (boolean, opcional, default `false`)
|
|
- `recordTrace` (boolean, opcional, default `false`)
|
|
- `recordLabel` (string, opcional, default `session`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"headless": false,
|
|
"startUrl": "http://localhost:3000",
|
|
"width": 1440,
|
|
"height": 900,
|
|
"browserKind": "system",
|
|
"persistentProfile": true,
|
|
"userDataDir": "/home/pancho/.chrome-perfil-google-real",
|
|
"verbose": true,
|
|
"verboseOverlay": true,
|
|
"interactionDelayMinMs": 1000,
|
|
"interactionDelayMaxMs": 3000,
|
|
"recordVideo": true,
|
|
"recordTrace": true,
|
|
"recordLabel": "case-123"
|
|
}
|
|
```
|
|
|
|
Notas:
|
|
|
|
- `recordVideo` sigue desactivado por defecto para evitar consumo innecesario.
|
|
- si activas `recordVideo` o `recordTrace`, los artifacts se generan al cerrar sesion con `browser_close`.
|
|
- con `verbose=true`, la tool muestra estado actual y aplica guardas de estabilidad antes de pasos sensibles.
|
|
|
|
---
|
|
|
|
### `browser_close`
|
|
|
|
Cierra la sesion activa de navegador.
|
|
|
|
Parametros: ninguno.
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_navigate`
|
|
|
|
Navega la pagina activa a una URL.
|
|
|
|
Parametros:
|
|
|
|
- `url` (string, requerido)
|
|
- `waitUntil` (string, opcional): `load`, `domcontentloaded`, `networkidle` (default `domcontentloaded`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"url": "http://localhost:3000/login",
|
|
"waitUntil": "domcontentloaded"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_click`
|
|
|
|
Hace click sobre un selector CSS.
|
|
|
|
Nota: antes del click intenta mover el puntero al centro del elemento para hacer la interaccion mas natural.
|
|
|
|
Parametros:
|
|
|
|
- `selector` (string, requerido)
|
|
- `timeoutMs` (number, opcional, default `10000`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"selector": "button[type='submit']",
|
|
"timeoutMs": 10000
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_hover`
|
|
|
|
Hace hover sobre un elemento por selector.
|
|
|
|
Parametros:
|
|
|
|
- `selector` (string, requerido)
|
|
- `timeoutMs` (number, opcional, default `10000`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"selector": ".menu-item-settings",
|
|
"timeoutMs": 10000
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_type`
|
|
|
|
Escribe texto en un elemento por selector.
|
|
|
|
Nota: antes de escribir intenta mover puntero y enfocar el campo con click.
|
|
|
|
Parametros:
|
|
|
|
- `selector` (string, requerido)
|
|
- `text` (string, requerido)
|
|
- `clear` (boolean, opcional, default `true`)
|
|
- `timeoutMs` (number, opcional, default `10000`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"selector": "input[name='email']",
|
|
"text": "usuario@dominio.com",
|
|
"clear": true,
|
|
"timeoutMs": 10000
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_select`
|
|
|
|
Selecciona una opcion en un elemento `<select>` por valor.
|
|
|
|
Parametros:
|
|
|
|
- `selector` (string, requerido)
|
|
- `value` (string, requerido)
|
|
- `timeoutMs` (number, opcional, default `10000`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"selector": "#tipoConsentimiento",
|
|
"value": "quirurgico",
|
|
"timeoutMs": 10000
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_press`
|
|
|
|
Envia una tecla al contexto de teclado de la pagina.
|
|
|
|
Parametros:
|
|
|
|
- `key` (string, requerido). Ejemplos: `Enter`, `Escape`, `Tab`, `Control+A`.
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"key": "Enter"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_scroll`
|
|
|
|
Hace scroll en pagina completa o dentro de un elemento.
|
|
|
|
Parametros:
|
|
|
|
- `x` (number, opcional, default `0`)
|
|
- `y` (number, opcional, default `400`)
|
|
- `selector` (string, opcional): si se envia, el scroll se aplica al elemento
|
|
|
|
Nota: cuando el scroll es de pagina, se aplica en varios pasos cortos para que el desplazamiento sea visible y progresivo.
|
|
Si no hay desplazamiento por rueda, aplica fallback `window.scrollBy`.
|
|
|
|
La salida incluye metricas utiles:
|
|
|
|
- `startY`, `endY`, `maxY`, `movedY` para scroll de pagina
|
|
- `movedX`, `movedY` para scroll de elemento
|
|
|
|
Ejemplo pagina:
|
|
|
|
```json
|
|
{
|
|
"y": 700
|
|
}
|
|
```
|
|
|
|
Ejemplo elemento:
|
|
|
|
```json
|
|
{
|
|
"selector": ".lista-scroll",
|
|
"y": 500
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_wait`
|
|
|
|
Espera a que se cumpla una condicion.
|
|
|
|
Nota: en esta version es opcional para muchos flujos, porque la herramienta ya aplica espera automatica nativa tras acciones comunes.
|
|
|
|
Parametros:
|
|
|
|
- `for` (string, requerido): `selector`, `text`, `url`, `timeout`
|
|
- `value` (string, requerido para `selector`, `text`, `url`)
|
|
- `timeoutMs` (number, opcional, default `10000`)
|
|
|
|
Nota para `for: timeout`:
|
|
|
|
- si envias `value`, se interpreta como milisegundos de espera
|
|
- si no envias `value`, usa `timeoutMs`
|
|
|
|
Ejemplo por selector:
|
|
|
|
```json
|
|
{
|
|
"for": "selector",
|
|
"value": ".toast-success",
|
|
"timeoutMs": 10000
|
|
}
|
|
```
|
|
|
|
Ejemplo por tiempo:
|
|
|
|
```json
|
|
{
|
|
"for": "timeout",
|
|
"timeoutMs": 1500
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_snapshot`
|
|
|
|
Toma screenshot y lo guarda en `artifacts/`.
|
|
|
|
Parametros:
|
|
|
|
- `label` (string, opcional)
|
|
- `fullPage` (boolean, opcional, default `true`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"label": "post-login",
|
|
"fullPage": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_evaluate`
|
|
|
|
Ejecuta JavaScript en la pagina. Puede recibir una funcion en texto (con `arg`) o una expresion directa.
|
|
|
|
Importante: si, puede inyectar y ejecutar logica JavaScript en runtime. Eso incluye leer variables del DOM y tambien modificarlas temporalmente dentro de la sesion de prueba.
|
|
|
|
Parametros:
|
|
|
|
- `script` (string, requerido): funcion JS serializada
|
|
- `arg` (object, opcional): dato de entrada a la funcion
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"script": "(arg) => ({ title: document.title, arg })",
|
|
"arg": { "source": "qa" }
|
|
}
|
|
```
|
|
|
|
Ejemplo con expresion directa:
|
|
|
|
```json
|
|
{
|
|
"script": "document.title"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_query`
|
|
|
|
Lee estado DOM/UI por selector sin tener que escribir JavaScript para casos comunes.
|
|
|
|
Parametros:
|
|
|
|
- `selector` (string, requerido)
|
|
- `mode` (string, opcional): `text`, `html`, `value`, `exists`, `visible`, `enabled`, `count`, `attributes`
|
|
|
|
Ejemplos:
|
|
|
|
```json
|
|
{
|
|
"selector": "#email",
|
|
"mode": "value"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"selector": ".toast-success",
|
|
"mode": "exists"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `browser_report`
|
|
|
|
Genera un reporte consolidado de ejecucion a partir de pasos, diagnostico y artifacts.
|
|
|
|
Parametros:
|
|
|
|
- `format` (string, opcional): `json`, `markdown`, `both` (default `both`)
|
|
- `includeSteps` (boolean, opcional, default `true`)
|
|
- `includeDiagnostics` (boolean, opcional, default `true`)
|
|
- `includeArtifacts` (boolean, opcional, default `true`)
|
|
- `saveToFile` (boolean, opcional): por defecto usa configuracion persistente (`true` al instalar)
|
|
- `label` (string, opcional, default `report`)
|
|
- `limitSteps` (number, opcional, default `200`)
|
|
- `limitDiagnostics` (number, opcional, default `50`)
|
|
|
|
Ejemplo:
|
|
|
|
```json
|
|
{
|
|
"format": "both",
|
|
"saveToFile": true,
|
|
"label": "consent-flow",
|
|
"includeSteps": true,
|
|
"includeDiagnostics": true,
|
|
"includeArtifacts": true
|
|
}
|
|
```
|
|
|
|
Resultado esperado:
|
|
|
|
- reporte estructurado para uso del agente
|
|
- opcionalmente archivos `.json` y `.md` en `artifacts/`
|
|
|
|
Comportamiento recomendado:
|
|
|
|
- por defecto queda guardando a archivo (`saveToFile=true`) para no perder evidencia
|
|
- puedes desactivarlo temporalmente en una ejecucion concreta (`saveToFile=false`)
|
|
- para cambiar el default de forma persistente usa `browser_config`
|
|
|
|
---
|
|
|
|
## Que puede pedirle el usuario a OpenCode
|
|
|
|
Ejemplos utiles:
|
|
|
|
- "Abre el browser, entra a `http://localhost:3000` y valida que aparece el boton `Iniciar sesion`."
|
|
- "Rellena email y password, envia el formulario y espera una URL que contenga `/dashboard`."
|
|
- "Haz scroll hasta el final, toma captura y guardala con etiqueta `dashboard-final`."
|
|
- "Ejecuta un `browser_evaluate` para devolver cantidad de filas de la tabla `.orders-table`."
|
|
- "Usa `browser_query` para comprobar si `.btn-guardar` esta visible y habilitado."
|
|
- "Ejecuta `browser_health` y dime si hay sesion abierta y cuales son los ultimos artifacts."
|
|
- "Al terminar la prueba, genera `browser_report` en `both` y guardalo a archivo para revisar resultado y evidencia."
|
|
|
|
## Limites actuales de esta version
|
|
|
|
- El diagnostico actual es en memoria de sesion (no persiste historico entre reinicios del proceso).
|
|
- Video/trace se activan manualmente por ejecucion; todavia no hay politica automatica "solo en fallo".
|
|
- No hay politica de seguridad final para navegacion externa (pendiente de fases posteriores).
|
|
- El modo recomendado de v1 es `Chromium managed by Playwright`.
|
|
|
|
## Errores tipicos y recuperacion
|
|
|
|
- `Browser session is not open`: ejecuta `browser_open` antes de usar otras tools.
|
|
- `Timeout` en `browser_wait`: valida si ya cambio URL/estado con `browser_evaluate`; si ya estas dentro, continua.
|
|
- Si la pagina parece bloqueada: ejecuta `browser_observe` para capturar estado/screenshot antes de cortar.
|
|
- Si aparece banner de consentimiento: ejecuta `browser_handle_consent` (`reject` o `accept`) y continua.
|
|
- Si aparece verificacion humana: ejecuta `browser_handle_human_check`; si no desbloquea, dejar evidencia y hacer handoff manual.
|
|
- Selector no encontrado en `browser_click` o `browser_type`: confirma selector con `browser_evaluate` y reintenta con uno mas estable.
|
|
- Flujo lento de red: deja que actue la espera nativa; si no alcanza, usa `browser_wait` explicito por selector de estado final.
|
|
- Error al evaluar JS en `browser_evaluate`: envia una funcion valida en texto, por ejemplo `(arg) => ({ title: document.title, arg })`.
|