feat(browser): auto-commit con 60 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-07 11:42:31 +02:00
parent 37aacfcfa9
commit 8742cb25be
71 changed files with 5660 additions and 192 deletions
@@ -0,0 +1,58 @@
+---
+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.