feat: --by label — resolve a form control by its visible label text

From the record-engage run: native <select>s (Category/Type) and the Notes
textarea had no accessible name — their labels were separate text nodes — so
they couldn't be addressed by --by name and needed an eval to find a CSS
selector. --by label resolves the control from its visible label: a
<label for>/wrapping label, else a label-ish element (span/div/dt/legend/th)
whose text matches, then the control after it in its nearest container. Defaults
to contains matching; resolves via querySelector (not the a11y tree, so it works
on a hidden tab too). Composes with fill/select/click/type/value.

Test: <label for> input, wrapping-label textarea, sibling-span -> native select
(the Engage pattern), and a sibling-div -> textarea.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: sanketsudake

internal/chrome/cdp.go

@@ -564,6 +564,8 @@ func byFor(selector string, q QueryOpts) []chromedp.QueryOption {
 		return []chromedp.QueryOption{chromedp.ByFunc(axRefQuery(selector))}
 	case "cell":
 		return []chromedp.QueryOption{chromedp.ByFunc(cellQuery(selector))}
+	case "label":
+		return []chromedp.QueryOption{chromedp.ByFunc(labelQuery(selector, q.Match))}
 	}
 	return byOptions(q)
 }
@@ -588,6 +590,11 @@ func query(selector string, q QueryOpts) []chromedp.QueryOption {
 			chromedp.ByFunc(cellQuery(selector)),
 			waitOption(q.Wait),
 		}
+	case "label":
+		return []chromedp.QueryOption{
+			chromedp.ByFunc(labelQuery(selector, q.Match)),
+			waitOption(q.Wait),
+		}
 	}
 	return queryOptions(q)
 }
@@ -664,6 +671,91 @@ const cellLocatorJS = `(() => {
   return cands[0] || null;
 })()`
 
+// labelQuery resolves a FORM CONTROL by its visible label text — for forms whose
+// labels are visible to a human but not wired to the control (no `aria-label`, no
+// `<label for>`), which would otherwise force an eval to find a CSS selector. It
+// matches a `<label for>`/wrapping label, else a label-ish element (span/div/dt/
+// legend/th) whose text matches, then returns the control after it in its
+// container. match defaults to contains (labels are often verbose).
+func labelQuery(label, match string) func(context.Context, *cdp.Node) ([]cdp.NodeID, error) {
+	return func(ctx context.Context, _ *cdp.Node) ([]cdp.NodeID, error) {
+		mode := match
+		if mode == "" {
+			mode = "contains"
+		}
+		labelJSON, _ := json.Marshal(label)
+		modeJSON, _ := json.Marshal(mode)
+		expr := fmt.Sprintf(labelLocatorJS, string(labelJSON), string(modeJSON))
+		res, exc, err := cdpruntime.Evaluate(expr).Do(ctx)
+		if err != nil {
+			return nil, err
+		}
+		if exc != nil {
+			return nil, fmt.Errorf("label locator: %s", exc.Text)
+		}
+		if res == nil || res.ObjectID == "" {
+			return nil, nil
+		}
+		nid, err := dom.RequestNode(res.ObjectID).Do(ctx)
+		if err != nil || nid == 0 {
+			return nil, err
+		}
+		return []cdp.NodeID{nid}, nil
+	}
+}
+
+// labelLocatorJS finds the form control described by a visible label. Args: %[1]s
+// label JSON, %[2]s match-mode JSON (exact|contains|regex).
+const labelLocatorJS = `(() => {
+  const want = %[1]s, mode = %[2]s;
+  const norm = s => (s || "").replace(/\s+/g, " ").trim();
+  const cmp = (a, b) => {
+    a = norm(a);
+    if (mode === "exact") return a.toLowerCase() === b.toLowerCase();
+    if (mode === "regex") { try { return new RegExp(b).test(a); } catch (e) { return false; } }
+    return a.toLowerCase().includes(b.toLowerCase());
+  };
+  const CTL = "input:not([type=hidden]),select,textarea,[contenteditable=true],[role=textbox],[role=combobox],[role=spinbutton],[role=listbox]";
+  const vis = el => {
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) return false;
+    const cs = getComputedStyle(el);
+    return cs.visibility !== "hidden" && cs.display !== "none";
+  };
+  // Given a matching label element, return the control it labels: a control it
+  // wraps, else the first visible control in the nearest ancestor that has one,
+  // preferring one that follows the label in document order.
+  const controlFor = lab => {
+    let node = lab;
+    for (let i = 0; i < 4 && node; i++) {
+      const ctls = [...node.querySelectorAll(CTL)].filter(vis);
+      if (ctls.length) {
+        const after = ctls.find(c => lab.compareDocumentPosition(c) & Node.DOCUMENT_POSITION_FOLLOWING);
+        return after || ctls[0];
+      }
+      node = node.parentElement;
+    }
+    return null;
+  };
+  // 1. A real <label> (for= or wrapping) — the authoritative case.
+  for (const lab of document.querySelectorAll("label")) {
+    if (!cmp(lab.textContent, want)) continue;
+    const f = lab.getAttribute("for");
+    const ctl = f ? document.getElementById(f) : lab.querySelector(CTL);
+    if (ctl && vis(ctl)) return ctl;
+  }
+  // 2. A label-ish element whose text matches -> the control near it. Prefer the
+  // tightest (shortest-text) match so "Notes" beats a paragraph containing it.
+  const labelish = [...document.querySelectorAll("label,span,div,dt,legend,th,p,strong,b")]
+    .filter(e => e.childElementCount <= 2 && cmp(e.textContent, want));
+  labelish.sort((a, b) => norm(a.textContent).length - norm(b.textContent).length);
+  for (const lab of labelish) {
+    const c = controlFor(lab);
+    if (c) return c;
+  }
+  return null;
+})()`
+
 // axRefQuery resolves a snap-issued element ref ("e<backendNodeId>") back to a
 // frontend node, so a caller acts on the exact element snap reported without
 // re-resolving it by name. The backend id is stable for the document's lifetime.

internal/chrome/label_test.go

@@ -0,0 +1,76 @@
+package chrome
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// --by label resolves a form control by its visible label text, across the
+// common patterns: <label for>, a wrapping <label>, and a sibling label element
+// next to the control (the Engage case, where the <select> has no accessible name).
+func TestLabelAddressing(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping live-Chrome integration in -short mode")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	b, err := launch(true, tmpProfile(t), 0)
+	if err != nil {
+		t.Skipf("cannot launch a managed headless Chrome here: %v", err)
+	}
+	defer b.Close()
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		fmt.Fprint(w, `<!doctype html><title>Label</title><body>
+<label for="em">Email</label><input id="em">
+<label>Comments <textarea id="cm"></textarea></label>
+<div class="field"><span>Activity Category</span>
+  <select id="cat"><option>Select…</option><option>Direct Revenue</option><option>Recruiting</option></select></div>
+<div class="field"><div class="lbl">Notes</div><textarea id="nt"></textarea></div>
+</body>`)
+	}))
+	defer srv.Close()
+
+	id := firstTab(ctx, t, b)
+	if _, err := b.Navigate(ctx, id, srv.URL); err != nil {
+		t.Fatalf("Navigate: %v", err)
+	}
+
+	// <label for> input.
+	if _, err := b.Fill(ctx, id, "Email", "a@b.com", QueryOpts{By: "label"}); err != nil {
+		t.Fatalf("Fill --by label Email: %v", err)
+	}
+	if v := evalString(ctx, t, b, id, "document.getElementById('em').value"); v != "a@b.com" {
+		t.Errorf("Email = %q, want a@b.com", v)
+	}
+
+	// Wrapping <label> around a textarea.
+	if _, err := b.Fill(ctx, id, "Comments", "hello", QueryOpts{By: "label"}); err != nil {
+		t.Fatalf("Fill --by label Comments: %v", err)
+	}
+	if v := evalString(ctx, t, b, id, "document.getElementById('cm').value"); v != "hello" {
+		t.Errorf("Comments = %q, want hello", v)
+	}
+
+	// Sibling label next to a native <select> with no accessible name (Engage
+	// pattern) — resolve it and select an option via `select --by label`.
+	if _, err := b.Select(ctx, id, "Activity Category", "Direct Revenue", SelectOpts{Query: QueryOpts{By: "label"}}); err != nil {
+		t.Fatalf("Select --by label Activity Category: %v", err)
+	}
+	if v := evalString(ctx, t, b, id, "(() => { const s=document.getElementById('cat'); return s.options[s.selectedIndex].text; })()"); v != "Direct Revenue" {
+		t.Errorf("Category = %q, want Direct Revenue", v)
+	}
+
+	// Sibling non-<label> element (a div) labelling a textarea.
+	if _, err := b.Fill(ctx, id, "Notes", "note text", QueryOpts{By: "label"}); err != nil {
+		t.Fatalf("Fill --by label Notes: %v", err)
+	}
+	if v := evalString(ctx, t, b, id, "document.getElementById('nt').value"); v != "note text" {
+		t.Errorf("Notes = %q, want 'note text'", v)
+	}
+}

internal/cli/commands.go

@@ -52,7 +52,7 @@ func (a *App) newRoot() *cobra.Command {
 	pf.BoolVar(&a.noDaemon, "no-daemon", d.NoDaemon, "connect directly instead of via the shared daemon")
 	pf.StringVar(&a.profileDir, "profile-dir", d.ProfileDir, "managed-launch Chrome profile dir (else $CHROME_CDP_PROFILE or ~/.cache/chrome-cdp/profile)")
 	pf.IntVar(&a.port, "port", d.Port, "explicit Chrome debug port to attach to / launch with (0 = auto)")
-	pf.StringVar(&a.byFlag, "by", d.By, "selector syntax: css|id|search|jspath|css-all|name|ref|cell (name = ARIA accessible name; ref = snap e<id>; cell = grid input by [row|]column header)")
+	pf.StringVar(&a.byFlag, "by", d.By, "selector syntax: css|id|search|jspath|css-all|name|ref|cell|label (name = ARIA accessible name; ref = snap e<id>; cell = grid input by [row|]column header; label = form control by visible label text)")
 	pf.StringVar(&a.waitFlag, "wait", d.Wait, "selector wait condition: visible|ready|enabled")
 	pf.StringVar(&a.roleFlag, "role", "", "with --by name: constrain to an ARIA role (button|link|textbox|…)")
 	pf.IntVar(&a.nthFlag, "nth", 0, "with --by name: pick the Nth (1-based) match among visible candidates")