---
name: cdp_find_ref_by_text
kind: function
lang: go
domain: browser
version: "1.0.0"
purity: impure
signature: "func CdpFindRefByText(c *CDPConn, text string, opts FindByTextOpts) (int, int, error)"
description: "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)."
tags: [browser, cdp, find, locator, ref, accessibility, navegator]
uses_functions:
  - cdp_evaluate_go_browser
uses_types: []
returns: []
returns_optional: false
error_type: error_go_core
imports: [encoding/json, fmt, strconv, strings]
params:
  - name: c
    desc: "Conexion CDP activa obtenida con CdpConnect."
  - name: text
    desc: "Texto visible a buscar. Comparacion contra innerText/textContent normalizado (whitespace colapsado)."
  - name: opts
    desc: "FindByTextOpts: Tag (filtro por tag, vacio = cualquiera), Exact (default false), CaseSensitive (default false)."
output: "(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)."
tested: true
tests: ["TestCdpFindRefByText_guards", "TestParseBackendNodeID"]
test_file_path: "functions/browser/cdp_find_ref_by_text_test.go"
file_path: "functions/browser/cdp_find_ref_by_text.go"
---

## Ejemplo

```go
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.