High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix(selector): let an exact text label break ties between controls instead of outranking them
Luigi Agosti969bdbf09abe
diff --git a/docs/commands.md b/docs/commands.mdindex 127fc741..5d9e41eb 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -143,7 +143,7 @@ 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.+`text:` prefers an **exact label over containment**. On a page offering both `Save` and `Save and exit`, `text:Save` is the button labelled exactly `Save`, wherever either sits in the document. For a bare `text:` the exact label only breaks ties between equally control-like matches: a heading reading `Sign in` does not take the click from a `Sign in with Google` button, and a label inside a control counts as that control. Positional wrappers index the exact matches when there are any, and all containing matches otherwise, 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.diff --git a/internal/bridge/action_resolve.go b/internal/bridge/action_resolve.goindex d76955f4..145d2b10 100644--- a/internal/bridge/action_resolve.go+++ b/internal/bridge/action_resolve.go@@ -517,11 +517,22 @@ const resolveSelectorAtFn = `function(kind, value, index, fromEnd, positional) {// has to pick the maximum weight EXPLICITLY: reading element zero of a// weight-sorted list is what made nth:1 resolve earlier in the document than// nth:0. Ties keep the first, so equal weights still mean document order.- const bestRanked = (items) => {+ // A label that IS the query breaks a tie between equally control-like matches+ // — "Save" over "Save and exit" — but never outranks control-likeness: a+ // heading reading "Sign in" must not take the click from a "Sign in with+ // Google" button. A leaf inside a control weighs as that control, so the+ // <span>Save</span> of a button is not beaten by a bare "Save changes" button.+ const exactBonus = 0.01;+ const controlSelector = "button, a, input, [role=button], [role=link], [role=textbox]";+ const textWeight = (el, query) => {+ const control = (el.closest && el.closest(controlSelector)) || el;+ return semanticWeight(control) + (normalize(el.textContent || "") === query ? exactBonus : 0);+ };+ const bestRanked = (items, query) => {let best = items[0];- let bestWeight = semanticWeight(best);+ let bestWeight = textWeight(best, query);for (const el of items) {- const weight = semanticWeight(el);+ const weight = textWeight(el, query);if (weight > bestWeight) {best = el;bestWeight = weight;@@ -529,7 +540,7 @@ const resolveSelectorAtFn = `function(kind, value, index, fromEnd, positional) {}return best;};- const textCandidates = (query) => {+ const textCandidates = (query, exactFirst) => {if (!query) return [];// textContent, not innerText: innerText forces a synchronous layout per// element and is O(N^2) on large pages.@@ -547,8 +558,14 @@ const resolveSelectorAtFn = `function(kind, value, index, fromEnd, positional) {// 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);+ //+ // The rung applies to the positional wrappers, which index what it+ // returns. The bare selector takes every containing match and lets+ // bestRanked weigh exactness below control-likeness.+ if (exactFirst) {+ 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);@@ -578,9 +595,9 @@ const resolveSelectorAtFn = `function(kind, value, index, fromEnd, positional) {return pick(items);}case "text": {- const items = unique(textCandidates(needle));+ const items = unique(textCandidates(needle, positional));if (!items.length) return null;- return positional ? pick(items) : bestRanked(items);+ return positional ? pick(items) : bestRanked(items, needle);}default:return null;diff --git a/internal/bridge/action_resolve_text_exact_test.go b/internal/bridge/action_resolve_text_exact_test.goindex 1acf069e..c99d3c47 100644--- a/internal/bridge/action_resolve_text_exact_test.go+++ b/internal/bridge/action_resolve_text_exact_test.go@@ -27,6 +27,11 @@ const textPrefixFixtureHTML = `<!doctype html></body></html>`func newTextPrefixFixture(t *testing.T) context.Context {+ t.Helper()+ return newTextFixture(t, textPrefixFixtureHTML, "#save")+}++func newTextFixture(t *testing.T, html, waitFor string) context.Context {t.Helper()chromePath := testbrowser.Path(t)@@ -45,10 +50,10 @@ func newTextPrefixFixture(t *testing.T) context.Context {cancelAlloc()})- dataURL := "data:text/html;base64," + base64.StdEncoding.EncodeToString([]byte(textPrefixFixtureHTML))+ dataURL := "data:text/html;base64," + base64.StdEncoding.EncodeToString([]byte(html))if err := chromedp.Run(ctx,chromedp.Navigate(dataURL),- chromedp.WaitVisible("#save", chromedp.ByID),+ chromedp.WaitVisible(waitFor, chromedp.ByQuery),); err != nil {t.Fatal(err)}@@ -110,3 +115,43 @@ func TestExactPreferenceAppliesUnderPositionalWrappers(t *testing.T) {describeNode(t, ctx, got), describeNode(t, ctx, want))}}++// Plain text whose words ARE the query sits beside a control whose label only+// contains it: a dialog heading over its sign-in button, a column header over a+// bulk action, a section title over its save button. The exact label must not+// outrank the control — clicking the heading does nothing and reports OK, the+// same silent miss the exact rule exists to prevent. Where the exact label is+// itself inside a control, it still wins over a longer control label.+const textControlFixtureHTML = `<!doctype html>+<html><body>+<h2 id="signinheading">Sign in</h2>+<button id="signin">Sign in with Google</button>+<table><tr><th id="deleteheader">Delete</th></tr></table>+<button id="deleteselected">Delete selected</button>+<h3 id="savetitle">Save</h3>+<button id="savechanges">Save changes</button>+<button id="publishall">Publish all</button>+<button id="publish"><span id="publishlabel">Publish</span></button>+</body></html>`++func TestTextSelectorPrefersAControlOverPlainTextThatIsTheQuery(t *testing.T) {+ ctx := newTextFixture(t, textControlFixtureHTML, "#publish")++ for _, tc := range []struct {+ query string+ wantX string+ }{+ {query: "text:Sign in", wantX: "css:#signin"},+ {query: "text:Delete", wantX: "css:#deleteselected"},+ {query: "text:Save", wantX: "css:#savechanges"},+ {query: "text:Publish", wantX: "css:#publishlabel"},+ } {+ t.Run(tc.query, func(t *testing.T) {+ want := resolve(t, ctx, tc.wantX)+ if got := resolve(t, ctx, tc.query); got != want {+ t.Errorf("%s resolved to %s, want %s",+ tc.query, describeNode(t, ctx, got), describeNode(t, ctx, want))+ }+ })+ }+}