fn_registry/python/functions/browser/cdp_eval.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params_schema, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params_schema	tested	tests	test_file_path	file_path
cdp_eval	function	py	browser	1.0.0	impure	def cdp_eval(expression: str, *, port: int = 9222, target_url_substr: str = '', await_promise: bool = False, timeout_s: float = 10.0) -> dict	Evalua una expresion JavaScript en una pestana de un Chrome con remote debugging, eligiendo el target por substring de su URL. Primitiva de transport CDP reutilizable para operar el navegador diario por codigo sin abrir ventana nueva.	cdp browser automation python navegator				false	error_go_core	json urllib.request websocket	params output name desc expression Expresion JavaScript a evaluar en el contexto de la pagina (ej. 'document.title', 'document.querySelector(".x").click()'). name desc port Puerto de remote debugging de Chrome. Default 9222. name desc target_url_substr Substring que debe contener la URL del target (pestana). Si vacio, usa el primer target de tipo 'page'. name desc await_promise Si True, espera a que la expresion resuelva una Promise antes de devolver el valor (awaitPromise de CDP). Default False. name desc timeout_s Timeout en segundos para la conexion WebSocket. Default 10.0. dict {ok: bool, value: <valor Python serializable o None>, error: str, target_url: str}. ok=True si la evaluacion produjo valor sin excepcion. Nunca lanza: errores de red/conexion/excepcion JS se devuelven en 'error'.	true	test_golden_selecciona_target_por_substr_y_devuelve_value test_edge_substr_sin_match_devuelve_ok_false test_error_urlopen_lanza_devuelve_ok_false	python/functions/browser/cdp_eval_test.py	python/functions/browser/cdp_eval.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from browser.cdp_eval import cdp_eval

# Requiere un Chrome lanzado con --remote-debugging-port=9222
# y una pestana de WhatsApp Web abierta.
res = cdp_eval("document.title", port=9222, target_url_substr="whatsapp")
print(res["value"])   # -> "WhatsApp" (o None si no hay target)
print(res["ok"], res["target_url"])

O directo por CLI: python3 python/functions/browser/cdp_eval.py "document.title" "whatsapp".

Cuando usarla

Cuando quieras leer datos o ejecutar JS (focus, querySelector, element.click(), scroll) sobre una pestana ya abierta del navegador diario sin abrir ventana nueva ni darle foco al sistema. Es la primitiva de transport sobre la que se construyen las funciones whatsapp_*_py_browser y cualquier script que opere una pestana existente via CDP.

Gotchas

• Requiere un Chrome lanzado con --remote-debugging-port=9222 (o el puerto que pases). Sin remote debugging, GET /json falla y devuelve ok=False.
• target_url_substr hace match de substring sobre la URL del target (no regex). El primer page que contenga el substring gana.
• returnByValue solo serializa valores JSON (str, num, bool, list, dict, None). Los nodos del DOM NO son serializables: devuelve la expresion ya reducida a un valor (ej. el.textContent, no el).
• Para escribir en inputs o contenteditable NO uses document.execCommand ni el.value = ...: editores como React/Lexical (WhatsApp Web) ignoran esos cambios programaticos. Usa cdp_type_chars_py_browser (teclea caracter a caracter via CDP Input.dispatchKeyEvent).
• Nunca lanza: errores de red, conexion WS o excepciones de la propia evaluacion JS se reportan en el campo error con ok=False.