fn_registry/functions/browser/cdp_find_ref_by_text.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, 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	output	tested	tests	test_file_path	file_path
cdp_find_ref_by_text	function	go	browser	1.0.0	impure	func CdpFindRefByText(c *CDPConn, text string, opts FindByTextOpts) (int, int, error)	Busca el primer elemento cuyo innerText matchea el texto dado y devuelve su backendDOMNodeId (#ref estable) en vez de un selector CSS. Resuelve el nodo JS a RemoteObject (Runtime.evaluate returnByValue=false) y de ahi al nodo DOM (DOM.describeNode), unificando la identidad con page_perceive y CdpClickRef. Devuelve tambien el numero de matches para detectar ambiguedad. Prefiere elementos hoja (leafmost).	browser cdp find locator ref accessibility navegator	cdp_evaluate_go_browser			false	error_go_core	encoding/json fmt strconv strings	name desc c Conexion CDP activa obtenida con CdpConnect. name desc text Texto visible a buscar. Comparacion contra innerText/textContent normalizado (whitespace colapsado). name desc opts FindByTextOpts: Tag (filtro por tag, vacio = cualquiera), Exact (default false), CaseSensitive (default false).	(backendNodeID, count, error): backendNodeID es el #ref del primer match listo para CdpClickRef; count es el numero total de matches (>1 = ambiguo); error si conexion nula, texto vacio, eval JS falla o no hay match (count==0).	true	TestCdpFindRefByText_guards TestParseBackendNodeID	functions/browser/cdp_find_ref_by_text_test.go	functions/browser/cdp_find_ref_by_text.go

Ejemplo

c, _ := browser.CdpConnect(9222)
defer browser.CdpClose(c, 0)

// Encontrar el botón "Login" por su texto y clicar por #ref (sin selector CSS).
ref, count, err := browser.CdpFindRefByText(c, "Login", browser.FindByTextOpts{Tag: "button"})
if err != nil {
    log.Fatal(err)
}
if count > 1 {
    log.Printf("aviso: %d elementos matchean 'Login', usando el primero", count)
}
_ = browser.CdpClickRef(c, ref, browser.MouseProfileForMode("human"))

Cuando usarla

Cuando quieras clicar/hacer hover sobre un elemento identificándolo por su texto visible y operar después por #ref (backendDOMNodeId) en vez de por un selector CSS frágil. Es el puente entre "lo veo por su texto" y el bucle percibir→actuar de page_perceive + CdpClickRef. Preferible a cdp_find_by_text (que devuelve selector nth-of-type) cuando el frontend cambia sus clases/estructura con cada build pero el texto es estable.

Gotchas

• count > 1 = ambigüedad: la función devuelve el primer match pero te avisa con count cuántos hay. Refina con opts.Tag o opts.Exact si el texto aparece en varios sitios.
• Elemento volátil: si el DOM muta entre el conteo y la resolución del nodo (SPA re-renderizando), el objectId puede venir vacío y la función devuelve error "elemento volátil" en vez de un #ref inválido. Reintenta tras CdpWaitIdle.
• El #ref es efímero por documento: el backendDOMNodeId es estable mientras el nodo viva, pero se invalida tras navegar o recargar. No lo persistas entre páginas.
• Tests sin Chrome: el núcleo puro (parseBackendNodeID) y los guards se testean sin navegador. El flujo completo (eval + describeNode contra DOM real) requiere Chrome y se valida por e2e.