opencode-browser-tool-installer/docs/manual_de_uso_heramienta.md

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:

{
  "ok": true,
  "tool": "browser_<tool>",
  "data": {},
  "state": {
    "isOpen": true,
    "currentUrl": "https://..."
  }
}

Respuesta con error:

{
  "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:

{}

---

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:

{
  "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:

{
  "action": "get"
}

Ejemplo cambio persistente:

{
  "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:

{
  "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.

{}

---

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:

{
  "screenshot": true,
  "label": "mid-flow-check"
}

---

browser_handle_consent

Intenta pulsar botones comunes de consentimiento.

Parametros:

• action (string, opcional): reject (default) o accept

Ejemplo:

{
  "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.

{}

---

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:

{
  "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:

{}

---

browser_navigate

Navega la pagina activa a una URL.

Parametros:

• url (string, requerido)
• waitUntil (string, opcional): load, domcontentloaded, networkidle (default domcontentloaded)

Ejemplo:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "y": 700
}

Ejemplo elemento:

{
  "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:

{
  "for": "selector",
  "value": ".toast-success",
  "timeoutMs": 10000
}

Ejemplo por tiempo:

{
  "for": "timeout",
  "timeoutMs": 1500
}

---

browser_snapshot

Toma screenshot y lo guarda en artifacts/.

Parametros:

• label (string, opcional)
• fullPage (boolean, opcional, default true)

Ejemplo:

{
  "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:

{
  "script": "(arg) => ({ title: document.title, arg })",
  "arg": { "source": "qa" }
}

Ejemplo con expresion directa:

{
  "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:

{
  "selector": "#email",
  "mode": "value"
}

{
  "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:

{
  "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 }).