Skip to content

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.md
index 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.go
index 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.go
index 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))
+ }
+ })
+ }
+}