web_scraping/demo_e2e/RESUMEN.md

Ejercicio e2e — validación de capacidades del browser_mcp

Fecha: 06/06/2026. Objetivo: comprobar, ejecutando de verdad contra sitios reales, que el servidor browser_mcp (control de navegador vía CDP) puede hacer tareas distintas de recopilación de datos — de simples a complejas. No "compila", sino "funciona".

Montaje

• Servidor: projects/web_scraping/apps/browser_mcp/browser_mcp (36 tools, pool de conexiones).
• Navegador: Chrome/Chromium 148 aislado en el puerto CDP 9333 (no el 9222 del navegador diario), user-data-dir dedicado. Lanzado headless para la batería y luego sin headless (ventana visible) para inspección humana — ambos con 5/5.
• Cliente: mcp_client.py — cliente JSON-RPC stdio secuencial (espera la respuesta de cada tool antes de mandar la siguiente, como hace un cliente MCP real). Un primer intento mandando todos los mensajes de golpe falló por una race: el servidor procesa requests de forma concurrente.
• Runner: run_demo.py — ejecuta las 5 pruebas, guarda pasos/respuestas/veredicto en results/.

Resultado: 9/9 PASS (headless y con ventana visible)

Las pruebas 1-5 son la batería inicial; 6-9 se añadieron para validar las tandas de fixes (A/D/E, B, y gap #1).

#	Prueba	Sitio sandbox	Capacidades ejercitadas	Resultado
1	Extraer citas estructuradas	quotes.toscrape.com	navigate, wait_load, eval → JSON real	PASS — 10 citas {text,author,tags}
2	Percibir página como agente	the-internet.herokuapp.com	page_perceive (AX outline)	PASS — outline 4021 chars con #ref accionables
3	Submit de formulario con teclado	the-internet.herokuapp.com/login	dom_click, dom_type, press_key Enter, wait_element	PASS — "You logged into a secure area!"
4	Login + sesión persistente	the-internet.herokuapp.com	form, storage_save/load, cookie_clear	PASS — sesión restaurada sin re-login
5	Scraping paginado + dedup	books.toscrape.com	navegación multi-página, eval, composición	PASS — 60 libros únicos (3 páginas)
6	sessionStorage en storage_state	the-internet.herokuapp.com	set→save→clear→load→get	PASS — clear=null, restore=demo_v (fix D)
7	find_by_text honesto	quotes.toscrape.com	dom_find_by_text presente vs inexistente	PASS — texto inexistente devuelve error, no vacío (fix E)
8	Verificación post-acción	quotes.toscrape.com	dom_click sobre oculto / dom_type sin foco	PASS — ambos devuelven error en vez de actuar al vacío (fix B)
9	Bucle percibir→actuar por #ref	the-internet.herokuapp.com/login	page_perceive → dom_type_ref/dom_click_ref + auto-observe	PASS — login solo por #ref (sin selector); cada acción devuelve el outline nuevo (gap #1)

Cobertura conjunta: lanzar/atar navegador, navegar, esperar carga, evaluar JS con JSON real, percibir (AX outline), leer texto, teclado, formularios, cookies, estado de sesión, y composición multi-página.

Valor del ejercicio: 3 bugs reales encontrados y arreglados

Ejecutar de verdad reveló defectos que "compila" jamás habría detectado:

1. page_perceive roto (bug de integración del MCP). Invocaba fn run cdp_perceive_outline --debug-port 9333 ... con flags, pero fn run pasa los argumentos posicionalmente a la función del pipeline → int('--debug-port') reventaba. Toda la percepción AX caía. Fix: argumentos posicionales en el orden de la firma. (tools_read.go)

2. cdp_save_storage_state guardaba cookies de todos los dominios. Usaba Network.getAllCookies (global), así que el storage_state arrastraba cookies de sitios visitados antes en la misma sesión (en la prueba, cookies de Wikipedia contaminaban la sesión de the-internet). Fix: filtrar por el host actual (location.hostname). (cdp_save_storage_state.go)

3. cdp_load_storage_state no restauraba la sesión httpOnly. Network.setCookies no aplicaba de forma fiable la cookie de sesión (rack.session, httpOnly) porque a cada cookie le faltaba el campo url. Fix: sintetizar url por cookie a partir de domain/secure/path. Con esto el login persistente (la pieza estrella) funciona de verdad. (cdp_load_storage_state.go)

Segunda tanda de fixes (A + D + E) — a partir del análisis de deuda

Tras la primera batería se atacaron tres deudas, cada una validada:

• A — Aislamiento robusto del navegador del agente (chrome_launch.go). El wrapper del sistema /etc/chromium.d/cdp inyecta --user-data-dir/--remote-debugging-port globales a todo chromium; el aislamiento dependía de que nuestros flags fueran al final (Chrome usa el último duplicado). Fix: findChrome prefiere el binario real (/usr/lib/chromium/chromium), que al ejecutarse directo no pasa por el wrapper y por tanto no hereda esos flags. Validado por construcción (el binario existe y va primero; browser_launch devuelve PID correcto); la inspección observable del cmdline choca con el exit-144 del entorno de pruebas al lanzar chromium desde el harness, no con el fix.
• D — sessionStorage en storage_state (cdp_save_storage_state.go, cdp_load_storage_state.go). Antes solo cookies + localStorage. Ahora también el "cajón temporal". Validado por la prueba 6.
• E — cdp_find_by_text honesto (cdp_find_by_text.go). Antes devolvía ("", nil) cuando no encontraba (el caller creía que había encontrado algo). Ahora devuelve error explícito. Validado por la prueba 7.

Gap #1 — bucle percibir→actuar por #ref (lo que cierra el loop del agente)

El cambio que más sube el nivel del agente. Un solo cambio resolvió tres cosas a la vez:

• #ref = backendDOMNodeId (no el nodeId efímero del AX tree). render_ax_outline ahora emite el id del nodo DOM real, estable mientras el nodo viva → el #ref que el LLM lee sigue válido cuando actúa un instante después. Resuelve "ref→acción" y "refs estables" de golpe, sin mantener mapa de estado en el MCP.
• Funciones por ref (cdp_click_ref, cdp_type_ref, cdp_hover_ref): resuelven backendDOMNodeId → bbox (DOM.getBoxModel) → centro → acción humanizada.
• Primitivo único cdp_click_xy_human: click humanizado por coordenadas, compartido por las tres vías (selector, #ref, y futura visión OCR/YOLO). cdp_click_human se refactorizó para usarlo (un solo camino).
• Auto-observe: cada tool _ref del MCP devuelve el outline AX actualizado tras la acción → el LLM ve el efecto sin pedir otra lectura = verificación implícita (como Playwright MCP).
• Defectos de calidad de render_ax_outline corregidos en la misma edición: guard de ciclo + límite de profundidad (evita RecursionError), se quitó el ljust(60) (gastaba tokens en relleno), y ahora renderiza el value de los inputs (texto escrito, estado).

Validado por la prueba 9: login completo en the-internet actuando solo por #ref (sin un solo selector CSS). Pendiente de esta familia: política de humanización por sesión (human/fast/instant) para scraping masivo.

Tercera tanda de fix (B) — verificación post-acción

• B — fin del "fire-and-forget" (cdp_click.go, cdp_type_text.go). cdp_click ahora verifica que el elemento es visible antes de clicar (display:none / tamaño 0 / opacity 0 → error, en vez de clicar en (0,0) sin efecto). cdp_type_text verifica que hay un campo editable enfocado (input/textarea/ select/contenteditable) antes de escribir (sin foco → error claro "usa CdpClick primero", en vez de escribir a la nada). Validado por la prueba 8. Pendiente de esta familia: cdp_scroll con target explícito (P1.5) y el puente percepción→acción por nodeId (P1.3).

Hallazgos secundarios

• press_key Enter no dispara widgets JS complejos. Contra el buscador de Wikipedia (typeahead Vue del skin Vector) el keyevent sintético se ejecutó sin error pero el widget no reaccionó. La prueba 3 se reorientó a un formulario HTML normal (login de the-internet), donde Enter sí envía el form. Deuda: para widgets JS-driven puede hacer falta disparar el evento del framework o submit explícito.
• Las pruebas comparten un mismo Chrome, por lo que el estado (cookies) se acumula entre ellas. Se añadió cookie_clear al inicio de las pruebas con login para aislarlas. Un harness más estricto usaría un contexto/perfil por prueba.

Deuda pendiente (no bloqueó el ejercicio)

• storage_state aún no captura sessionStorage (sí cookies + localStorage). Suficiente para sesiones basadas en cookie como the-internet; insuficiente para sitios que guardan el token en sessionStorage.
• Verificación post-acción (P1 del análisis LLM-readiness): dom_click/dom_type siguen siendo fire-and-forget. En estas pruebas se compensó con dom_wait_element y checks por eval, pero las tools no confirman su efecto por sí mismas.

Cómo reproducir

# 1. Chrome aislado en 9333 (headless)
systemd-run --user -q --unit=browser_demo \
  chromium --headless=new --remote-debugging-port=9333 \
  --user-data-dir=/tmp/browser_mcp_userdata about:blank

# 1-bis. O con ventana visible (Linux con sesión gráfica):
systemd-run --user -q --unit=browser_demo \
  --setenv=DISPLAY=:0 --setenv=XAUTHORITY=$HOME/.Xauthority \
  chromium --remote-debugging-port=9333 \
  --user-data-dir=/tmp/browser_mcp_visible --start-maximized about:blank

# 2. Compilar el MCP y ejecutar la batería
cd projects/web_scraping/apps/browser_mcp && go build -o browser_mcp .
cd ../../demo_e2e && python3 run_demo.py

# 3. Parar el navegador
systemctl --user stop browser_demo.service

Archivos

• mcp_client.py — cliente MCP stdio secuencial (reutilizable).
• run_demo.py — las 5 pruebas.
• results/prueba_N_*.json — pasos, respuestas y datos extraídos por prueba.
• results/run.log — log de la corrida.
• results/summary.json — veredicto agregado.
• results/mcp_stderr.log — stderr del servidor MCP.