Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix(selector): text: clicked a longer label that merely contained the query

Darshan Jain1a91c692e1a9
diff --git a/docs/commands.md b/docs/commands.md
index c1c84d85..127fc741 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -143,6 +143,8 @@ Most element commands accept a unified selector:
Positional wrappers index the candidates in **document order** for every selector kind, so `nth:0:` is the first match in the page and `nth:1:` always comes after it. A bare `text:` selector is the one form that does not index: it picks the most control-like match among the smallest ones, so `text:Save` prefers a `<button>` over a `<div>` carrying the same label — which means `text:X` and `first:text:X` can resolve to different elements. A wrapper only ever chooses among the matches a bare selector would find; it never changes which matches exist.
+`text:` matches by **exact label first, containment second**. On a page offering both `Save` and `Save and exit`, `text:Save` is the button labelled exactly `Save`, wherever either sits in the document; containment only answers when no label is exactly the query, which is what lets `text:Sign` reach `Sign in with Google`. This is the same ladder [`select`](./reference/select.md) uses for option text. Prefer the full label when controls share a prefix — `Delete` and `Delete all` are one typo apart in effect.
+
Selector prefixes are case-insensitive, so `CSS:#login` and `css:#login` mean the same thing. Only the prefix is case-folded; the value after it is passed through unchanged.
Structured forms such as `role:`, `label:`, and `testid:` are matched by the semantic engine against enriched snapshot descriptors. CSS, XPath, refs, the existing `text:` action selector, and bare CSS/text wrappers remain browser-side selector resolution.
diff --git a/internal/bridge/action_resolve.go b/internal/bridge/action_resolve.go
index b11c9f69..d76955f4 100644
--- a/internal/bridge/action_resolve.go
+++ b/internal/bridge/action_resolve.go
@@ -536,8 +536,21 @@ const resolveSelectorAtFn = `function(kind, value, index, fromEnd, positional) {
const elements = deepQueryAll("*", root.body || root)
.filter((el) => !nonRendered.has((el.tagName || "").toLowerCase()));
const measured = elements.map((el) => ({ el, text: normalize(el.textContent || ""), size: el.getElementsByTagName("*").length }));
- const exact = measured.filter((item) => item.text && item.text.includes(query));
- if (exact.length) return smallestMatches(exact);
+ // An element whose label IS the query beats one that merely contains it.
+ // Without this rung the two were one filter — named exact, testing
+ // includes — so "Save" and "Save and exit" were equally good answers to
+ // text:Save, both leaf-most, both weighted as buttons, and the tie fell to
+ // document order. A page listing the longer label first therefore sent
+ // text:Delete to "Delete all" and reported OK.
+ //
+ // Containment still answers when nothing matches outright, so the
+ // shorthand that reaches "Sign in" by text:Sign is untouched. This is the
+ // ladder the select-option matcher already documents in
+ // docs/reference/select.md: exact visible text, then substring.
+ const equals = measured.filter((item) => item.text === query);
+ if (equals.length) return smallestMatches(equals);
+ const contains = measured.filter((item) => item.text && item.text.includes(query));
+ if (contains.length) return smallestMatches(contains);
const tokens = query.split(" ").filter(Boolean);
if (!tokens.length) return [];
const fuzzy = measured.filter((item) => {
diff --git a/internal/bridge/action_resolve_text_exact_test.go b/internal/bridge/action_resolve_text_exact_test.go
new file mode 100644
index 00000000..1acf069e
--- /dev/null
+++ b/internal/bridge/action_resolve_text_exact_test.go
@@ -0,0 +1,112 @@
+package bridge
+
+import (
+ "context"
+ "encoding/base64"
+ "testing"
+ "time"
+
+ "github.com/chromedp/chromedp"
+ "github.com/pinchtab/pinchtab/internal/testbrowser"
+)
+
+// Labels that share a prefix, with the LONGER one first in document order —
+// which is the arrangement that decides the bug, because a tie between equally
+// specific matches falls to document order.
+//
+// "Delete"/"Delete all" is the pair worth naming: an agent told to delete one
+// record and handed the control that deletes every record has not made a
+// near-miss.
+const textPrefixFixtureHTML = `<!doctype html>
+<html><body>
+<button id="saveexit">Save and exit</button>
+<button id="save">Save</button>
+<button id="deleteall">Delete all</button>
+<button id="delete">Delete</button>
+<button id="signin">Sign in with Google</button>
+</body></html>`
+
+func newTextPrefixFixture(t *testing.T) context.Context {
+ t.Helper()
+ chromePath := testbrowser.Path(t)
+
+ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(
+ chromedp.DefaultExecAllocatorOptions[:],
+ chromedp.ExecPath(chromePath),
+ chromedp.UserDataDir(testbrowser.ProfileDir(t)),
+ chromedp.Flag("headless", true),
+ chromedp.Flag("no-sandbox", true),
+ )...)
+ ctx, cancelBrowser := chromedp.NewContext(alloc)
+ ctx, cancelTimeout := context.WithTimeout(ctx, 30*time.Second)
+ t.Cleanup(func() {
+ cancelTimeout()
+ cancelBrowser()
+ cancelAlloc()
+ })
+
+ dataURL := "data:text/html;base64," + base64.StdEncoding.EncodeToString([]byte(textPrefixFixtureHTML))
+ if err := chromedp.Run(ctx,
+ chromedp.Navigate(dataURL),
+ chromedp.WaitVisible("#save", chromedp.ByID),
+ ); err != nil {
+ t.Fatal(err)
+ }
+ return ctx
+}
+
+// A label that IS the query beats one that merely contains it.
+//
+// The candidate filter was one rung — named exact, testing includes — so "Save"
+// and "Save and exit" were equally good answers to text:Save. Both are
+// leaf-most, both weigh as controls, and the tie fell to document order, so a
+// page listing the longer label first took the click. Measured through a real
+// browser before this: text:Save clicked "Save and exit" and text:Delete
+// clicked "Delete all", both reporting OK.
+func TestTextSelectorPrefersTheLabelThatIsTheQuery(t *testing.T) {
+ ctx := newTextPrefixFixture(t)
+
+ for _, tc := range []struct {
+ query string
+ wantX string
+ }{
+ {query: "text:Save", wantX: "css:#save"},
+ {query: "text:Delete", wantX: "css:#delete"},
+ } {
+ t.Run(tc.query, func(t *testing.T) {
+ want := resolve(t, ctx, tc.wantX)
+ got := resolve(t, ctx, tc.query)
+ if got != want {
+ t.Errorf("%s resolved to %s, want %s — the control whose label is exactly the query",
+ tc.query, describeNode(t, ctx, got), describeNode(t, ctx, want))
+ }
+ })
+ }
+}
+
+// Containment still answers when nothing matches outright, so the shorthand that
+// reaches a longer label by a fragment of it keeps working. Removing that would
+// trade one silent wrong answer for a class of missing ones.
+func TestTextSelectorStillReachesALongerLabelByAFragment(t *testing.T) {
+ ctx := newTextPrefixFixture(t)
+
+ want := resolve(t, ctx, "css:#signin")
+ if got := resolve(t, ctx, "text:Sign"); got != want {
+ t.Errorf("text:Sign resolved to %s, want button#signin (%s); no label is exactly \"Sign\", so containment is the only rung that can answer",
+ describeNode(t, ctx, got), describeNode(t, ctx, want))
+ }
+}
+
+// The exact rung reduces the match set like the size rule does; it must not
+// change what a positional wrapper indexes into beyond that. first: over a query
+// with an exact match still lands on that match rather than on an earlier
+// element that merely contains it.
+func TestExactPreferenceAppliesUnderPositionalWrappers(t *testing.T) {
+ ctx := newTextPrefixFixture(t)
+
+ want := resolve(t, ctx, "css:#delete")
+ if got := resolve(t, ctx, "first:text:Delete"); got != want {
+ t.Errorf("first:text:Delete resolved to %s, want button#delete (%s)",
+ describeNode(t, ctx, got), describeNode(t, ctx, want))
+ }
+}