Skip to content

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

fix: six inspect endpoints return 500 for a semantic selector that simply did not match, so an agent reads a bad selector as a server fault (PIN-175)

Luigi Agosti20043791733c
diff --git a/internal/handlers/action_selector_resolution.go b/internal/handlers/action_selector_resolution.go
index 527eed5e..56e64e10 100644
--- a/internal/handlers/action_selector_resolution.go
+++ b/internal/handlers/action_selector_resolution.go
@@ -90,7 +90,7 @@ func (h *Handlers) resolveActionRequestSelectorInScope(
if handled, err := h.applySemanticActionSelectorInScope(ctx, tabID, frameID, modalNodeID, sel, req); handled {
if err != nil {
- return actionSelectorResolution{status: semanticSelectorHTTPStatus(err)}, err
+ return actionSelectorResolution{status: statusForElementErr(err)}, err
}
return actionSelectorResolution{}, nil
}
diff --git a/internal/handlers/count.go b/internal/handlers/count.go
index f0472ffa..bd2b8f08 100644
--- a/internal/handlers/count.go
+++ b/internal/handlers/count.go
@@ -125,7 +125,7 @@ func (h *Handlers) countSemantic(ctx context.Context, tabID string, sel selector
return 0, fmt.Errorf("selector %q is not a semantic query", sel.String())
}
if h.Matcher == nil {
- return 0, fmt.Errorf("semantic selectors require a matcher (not configured)")
+ return 0, ErrSemanticMatcherUnavailable
}
frameID := h.selectorFrameID(tabID)
diff --git a/internal/handlers/element_resolve.go b/internal/handlers/element_resolve.go
index 66b3f553..a62e991d 100644
--- a/internal/handlers/element_resolve.go
+++ b/internal/handlers/element_resolve.go
@@ -4,12 +4,19 @@ import (
"context"
"errors"
"fmt"
+ "net/http"
"github.com/pinchtab/pinchtab/internal/bridge"
)
var ErrElementNotFound = errors.New("element not found")
+// ErrSemanticMatcherUnavailable is the one server fault in the semantic selector path:
+// the feature is not configured, which is not the caller's mistake and not a missing
+// element. It carries its own sentinel so the mapping below can keep answering 501 for
+// it without asking what the message says.
+var ErrSemanticMatcherUnavailable = errors.New("semantic selectors require a matcher (not configured)")
+
func (h *Handlers) resolveElementNodeID(ctx context.Context, tabID, sel string) (int64, error) {
nodeID, err := h.resolveSelectorNodeID(ctx, tabID, sel)
if err != nil {
@@ -27,9 +34,22 @@ func (h *Handlers) resolveElementNodeID(ctx context.Context, tabID, sel string)
return nodeID, nil
}
+// statusForElementErr is the ONE owner of the selector-failure status, for the inspect
+// endpoints and the action path alike. It reads SENTINELS, never message text: a status
+// keyed on wording changes the moment someone rewrites a sentence, and the semantic
+// messages are rewritten often — the out-of-range one was reworded while this mapping
+// was being unified.
+//
+// A selector that matched nothing is the caller's problem (404: re-snapshot and pick
+// another). Everything else is the server's (500: retrying may help). Getting that
+// backwards on a read endpoint sends retry storms at a page that is fine.
func statusForElementErr(err error) int {
- if errors.Is(err, ErrElementNotFound) {
- return 404
+ switch {
+ case errors.Is(err, ErrSemanticMatcherUnavailable):
+ return http.StatusNotImplemented
+ case errors.Is(err, ErrElementNotFound):
+ return http.StatusNotFound
+ default:
+ return http.StatusInternalServerError
}
- return 500
}
diff --git a/internal/handlers/semantic_selectors.go b/internal/handlers/semantic_selectors.go
index fa80de6a..65866637 100644
--- a/internal/handlers/semantic_selectors.go
+++ b/internal/handlers/semantic_selectors.go
@@ -3,8 +3,6 @@ package handlers
import (
"context"
"fmt"
- "net/http"
- "strings"
"github.com/pinchtab/pinchtab/internal/bridge"
"github.com/pinchtab/pinchtab/internal/selector"
@@ -25,7 +23,7 @@ func (h *Handlers) applySemanticActionSelectorInScope(ctx context.Context, tabID
return false, nil
}
if h.Matcher == nil {
- return true, fmt.Errorf("semantic selectors require a matcher (not configured)")
+ return true, ErrSemanticMatcherUnavailable
}
var (
@@ -91,7 +89,10 @@ func (h *Handlers) applySemanticActionSelectorInScope(ctx context.Context, tabID
}
target, ok := cache.Lookup(result.BestRef)
if !ok || target.BackendNodeID == 0 {
- return true, fmt.Errorf("semantic selector %q matched ref %s but no node is available", query, result.BestRef)
+ // The snapshot named a ref the cache no longer holds: from the caller's side
+ // that is a stale selector, not a broken server, so it carries the not-found
+ // sentinel like the other misses.
+ return true, fmt.Errorf("%w: semantic selector %q matched ref %s but no node is available", ErrElementNotFound, query, result.BestRef)
}
req.Ref = result.BestRef
req.NodeID = target.BackendNodeID
@@ -129,26 +130,6 @@ func scopeSemanticNodesByFrame(nodes []bridge.A11yNode, frameID string) []bridge
return filtered
}
-func semanticSelectorHTTPStatus(err error) int {
- if err == nil {
- return http.StatusOK
- }
- msg := strings.ToLower(err.Error())
- switch {
- case strings.Contains(msg, "not configured"):
- return http.StatusNotImplemented
- case strings.Contains(msg, "no matching element found"),
- strings.Contains(msg, "is out of range"),
- strings.Contains(msg, "no node is available"):
- return http.StatusNotFound
- case strings.Contains(msg, "no snapshot available"),
- strings.Contains(msg, "no elements found"):
- return http.StatusInternalServerError
- default:
- return http.StatusInternalServerError
- }
-}
-
// emptySemanticMatchError distinguishes an empty page from an index nobody can satisfy.
// A positional nth: wrapper that runs off the end of the match set otherwise reports
// "no matching element found" while the elements are plainly there, which reads as a
@@ -158,13 +139,13 @@ func semanticSelectorHTTPStatus(err error) int {
func (h *Handlers) emptySemanticMatchError(ctx context.Context, sel selector.Selector, query string, descs []semantic.ElementDescriptor) error {
index, base, ok := sel.SemanticNthBase()
if !ok {
- return fmt.Errorf("semantic selector %q: no matching element found", query)
+ return fmt.Errorf("%w: semantic selector %q: no matching element found", ErrElementNotFound, query)
}
matches := h.countSemanticMatches(ctx, base, descs)
if matches == 0 {
- return fmt.Errorf("semantic selector %q: no matching element found", sel.String())
+ return fmt.Errorf("%w: semantic selector %q: no matching element found", ErrElementNotFound, sel.String())
}
- return fmt.Errorf("semantic selector %q: index %d is out of range, %q matched %d element(s)", sel.String(), index, base, matches)
+ return fmt.Errorf("%w: semantic selector %q: index %d is out of range, %q matched %d element(s)", ErrElementNotFound, sel.String(), index, base, matches)
}
func (h *Handlers) countSemanticMatches(ctx context.Context, base string, descs []semantic.ElementDescriptor) int {
diff --git a/internal/handlers/semantic_status_test.go b/internal/handlers/semantic_status_test.go
new file mode 100644
index 00000000..7adc3ea9
--- /dev/null
+++ b/internal/handlers/semantic_status_test.go
@@ -0,0 +1,211 @@
+package handlers
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/srccensus"
+)
+
+// semanticInspectHandlers serves three same-named buttons through the accessibility
+// snapshot, which is all a semantic selector needs — no browser, so these run in CI.
+func semanticInspectHandlers(t *testing.T, withMatcher bool) *Handlers {
+ t.Helper()
+
+ cache := &bridge.RefCache{
+ Nodes: []bridge.A11yNode{
+ {Ref: "e0", Role: "button", Name: "Save"},
+ {Ref: "e1", Role: "button", Name: "Save"},
+ {Ref: "e2", Role: "button", Name: "Save"},
+ },
+ Refs: map[string]int64{"e0": 1, "e1": 2, "e2": 3},
+ }
+ h := New(&findMockBridge{refCache: cache}, &config.RuntimeConfig{ActionTimeout: 10 * time.Second}, nil, nil, nil)
+ if !withMatcher {
+ // New always installs a matcher, so an unconfigured one has to be arranged
+ // deliberately — see TestAnUnconfiguredMatcherIsNotAMissingElement.
+ h.Matcher = nil
+ }
+ return h
+}
+
+// inspectEndpoints are the read surfaces that accept a semantic selector. The defect
+// this covers is that the status mapping had one caller — the action path — so all six
+// of these answered 500 for a selector that simply did not match, telling an agent to
+// retry a page that is fine instead of to re-snapshot and pick another selector.
+var inspectEndpoints = []struct {
+ name string
+ path string
+ // countsMatches marks the endpoint whose answer to "nothing matched" is a NUMBER
+ // rather than a refusal: /count reports zero, which is the correct answer to how
+ // many elements match, not an error. Every other endpoint has to return an element.
+ countsMatches bool
+ serve func(*Handlers, http.ResponseWriter, *http.Request)
+}{
+ {name: "attr", path: "/attr?name=id&selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetAttr(w, r) }},
+ {name: "value", path: "/value?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetValue(w, r) }},
+ {name: "enabled", path: "/enabled?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetEnabled(w, r) }},
+ {name: "visible", path: "/visible?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetVisible(w, r) }},
+ {name: "checked", path: "/checked?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetChecked(w, r) }},
+ {name: "count", path: "/count?selector=", countsMatches: true, serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleCount(w, r) }},
+}
+
+func serveInspect(t *testing.T, h *Handlers, index int, selectorValue string) *httptest.ResponseRecorder {
+ t.Helper()
+ endpoint := inspectEndpoints[index]
+ req := httptest.NewRequest("GET", endpoint.path+strings.ReplaceAll(selectorValue, " ", "%20"), nil)
+ w := httptest.NewRecorder()
+ endpoint.serve(h, w, req)
+ return w
+}
+
+// A selector that matched nothing is the caller's problem, so it must read as 404 on
+// every read surface — asserted through the HANDLER, because the mapper being right is
+// what the previous test proved while five callers never reached it.
+func TestASemanticSelectorThatMatchesNothingIs404OnEveryInspectEndpoint(t *testing.T) {
+ for index, endpoint := range inspectEndpoints {
+ t.Run(endpoint.name, func(t *testing.T) {
+ w := serveInspect(t, semanticInspectHandlers(t, true), index, "role:slider Volume")
+
+ if endpoint.countsMatches {
+ if w.Code != http.StatusOK || !strings.Contains(w.Body.String(), `"count":0`) {
+ t.Fatalf("status = %d body %s, want 200 with a count of 0 — zero is the answer to how many matched", w.Code, w.Body.String())
+ }
+ return
+ }
+ if w.Code != http.StatusNotFound {
+ t.Fatalf("status = %d, want 404; a 5xx tells an agent to retry a page that is fine (body %s)", w.Code, w.Body.String())
+ }
+ if !strings.Contains(w.Body.String(), "no matching element found") {
+ t.Errorf("body %s does not say the selector matched nothing", w.Body.String())
+ }
+ })
+ }
+}
+
+// The out-of-range refusal keeps naming the caller's zero-based index and the bare
+// selector's match count, at 404, on every read surface.
+func TestAnOutOfRangeWrapperIndexIs404OnEveryInspectEndpoint(t *testing.T) {
+ for index, endpoint := range inspectEndpoints {
+ t.Run(endpoint.name, func(t *testing.T) {
+ w := serveInspect(t, semanticInspectHandlers(t, true), index, "nth:7:role:button Save")
+
+ if w.Code != http.StatusNotFound {
+ t.Fatalf("status = %d, want 404 (body %s)", w.Code, w.Body.String())
+ }
+ body := w.Body.String()
+ for _, needle := range []string{"index 7", "out of range", "3 element(s)"} {
+ if !strings.Contains(body, needle) {
+ t.Errorf("body %s does not carry %q", body, needle)
+ }
+ }
+ if strings.Contains(body, "nth:8") {
+ t.Errorf("body %s names the translated one-based index instead of what the caller sent", body)
+ }
+ })
+ }
+}
+
+// Criterion five: do not blanket-404 the inspect path. An unconfigured matcher is a
+// server-side gap, not a bad selector, and it keeps its own code on every surface.
+func TestAnUnconfiguredMatcherIsNotAMissingElement(t *testing.T) {
+ for index, endpoint := range inspectEndpoints {
+ t.Run(endpoint.name, func(t *testing.T) {
+ w := serveInspect(t, semanticInspectHandlers(t, false), index, "role:button Save")
+
+ if w.Code != http.StatusNotImplemented {
+ t.Fatalf("status = %d, want 501 for an unconfigured matcher (body %s)", w.Code, w.Body.String())
+ }
+ })
+ }
+}
+
+// The action path and the inspect path must reach the SAME mapping. A second copy of
+// the switch is how they drifted apart, so this asserts agreement per outcome rather
+// than trusting that both call the same name today.
+func TestBothPathsAgreeOnTheStatusForTheSameFailure(t *testing.T) {
+ h := semanticInspectHandlers(t, true)
+
+ for _, tc := range []struct {
+ name string
+ selector string
+ want int
+ }{
+ {"no match", "role:slider Volume", http.StatusNotFound},
+ {"out of range", "nth:7:role:button Save", http.StatusNotFound},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ // The in-scope resolver, not resolveActionRequestSelector: the outer one
+ // probes the topmost dialog through CDP, which no mock can answer.
+ req := bridge.ActionRequest{Selector: tc.selector}
+ resolution, err := h.resolveActionRequestSelectorInScope(context.Background(), "tab1", "", 0, false, &req)
+ if err == nil {
+ t.Fatal("the action path accepted a selector the inspect path refuses")
+ }
+ if resolution.status != tc.want {
+ t.Errorf("action path status = %d, want %d", resolution.status, tc.want)
+ }
+ if w := serveInspect(t, h, 0, tc.selector); w.Code != resolution.status {
+ t.Errorf("inspect /attr answered %d while the action path answered %d for the same failure", w.Code, resolution.status)
+ }
+ })
+ }
+}
+
+// The status must come from the sentinel, not from the wording. The out-of-range
+// message was being reworded while this mapping was unified, and a status keyed on text
+// silently changes with it.
+func TestTheStatusSurvivesRewordingTheMessage(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ err error
+ want int
+ }{
+ {"reworded miss keeps its 404", fmt.Errorf("%w: absolutely nothing like that on the page", ErrElementNotFound), http.StatusNotFound},
+ {"reworded unavailable keeps its 501", fmt.Errorf("%w: turn the matcher on", ErrSemanticMatcherUnavailable), http.StatusNotImplemented},
+ {"the old wording alone buys nothing", errors.New("no matching element found"), http.StatusInternalServerError},
+ {"out-of-range wording alone buys nothing", errors.New(`index 7 is out of range, "role:button Save" matched 3 element(s)`), http.StatusInternalServerError},
+ {"not-configured wording alone buys nothing", errors.New("semantic selectors require a matcher (not configured)"), http.StatusInternalServerError},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ if got := statusForElementErr(tc.err); got != tc.want {
+ t.Errorf("statusForElementErr(%v) = %d, want %d", tc.err, got, tc.want)
+ }
+ })
+ }
+}
+
+// Criterion three, structurally: both paths must REACH the one mapper. The inspect path
+// and the action path each mapped selector failures themselves, and the two switches
+// drifted — semantic misses answered 404 on /action and 500 on all six read endpoints.
+//
+// This pins the call sites; TestBothPathsAgreeOnTheStatusForTheSameFailure pins the
+// outcome. Both are needed: a census cannot see a second mapper under a new name, and an
+// agreement test cannot see a caller that stops mapping at all.
+func TestOneMapperServesBothTheInspectAndActionPaths(t *testing.T) {
+ pkg := srccensus.Load(t, ".", 20)
+
+ callers := map[string]bool{}
+ for _, site := range pkg.Calls(t, "statusForElementErr") {
+ callers[site.Func] = true
+ }
+ for _, required := range []string{"inspectElement", "resolveActionRequestSelectorInScope"} {
+ if !callers[required] {
+ t.Errorf("%s no longer maps its selector failures through statusForElementErr; a second copy of the status switch is how the inspect and action paths drifted apart", required)
+ }
+ }
+
+ // The string-matching mapper is gone on purpose: a status keyed on message text
+ // changes whenever a sentence is reworded, and these messages are reworded often.
+ if _, found := pkg.Func("semanticSelectorHTTPStatus"); found {
+ t.Error("semanticSelectorHTTPStatus is back; the semantic statuses come from sentinels now, so a message-matching mapper would silently re-key them on wording")
+ }
+}
diff --git a/internal/handlers/semantic_wrapper_index_test.go b/internal/handlers/semantic_wrapper_index_test.go
index 260b4640..fe3aa205 100644
--- a/internal/handlers/semantic_wrapper_index_test.go
+++ b/internal/handlers/semantic_wrapper_index_test.go
@@ -3,6 +3,7 @@ package handlers
import (
"context"
"encoding/base64"
+ "errors"
"fmt"
"os"
"strings"
@@ -93,8 +94,12 @@ func TestAnOutOfRangeWrapperIndexSaysSoInsteadOfNoMatch(t *testing.T) {
if strings.Contains(msg, "nth:8") {
t.Errorf("refusal %q names the translated one-based index; it must name what the caller sent", msg)
}
- if status := semanticSelectorHTTPStatus(err); status != 404 {
- t.Errorf("out-of-range refusal maps to HTTP %d, want 404 rather than a 500 that reads as a server fault", status)
+ // The status itself is asserted at the HTTP boundary in semantic_status_test.go —
+ // a mapper can be correct while nobody calls it, which is exactly what happened
+ // here. What this layer owns is that the refusal CARRIES the sentinel every caller
+ // maps from.
+ if !errors.Is(err, ErrElementNotFound) {
+ t.Errorf("out-of-range refusal does not wrap ErrElementNotFound, so every caller has to recognise it by wording")
}
}