Skip to content

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

fix: find prints nothing at all on no-match, so an agent cannot tell 'no such element' from a failed command (PIN-116)

Luigi Agosti977dd4a7b240
diff --git a/docs/reference/find.md b/docs/reference/find.md
index 27650fcf..371aad41 100644
--- a/docs/reference/find.md
+++ b/docs/reference/find.md
@@ -45,6 +45,12 @@ pinchtab find --threshold 0.5 --explain "primary submit button"
pinchtab find --ref-only "search input"
```
+When nothing matches, `find` prints `No elements matched "<query>"` and exits 0 — an empty
+result is an answer, the same way `console` and `errors` report having nothing to show.
+`--ref-only` prints that line to stderr and exits non-zero instead, deliberately: it is
+built for `REF=$(pinchtab find … --ref-only)`, where an empty `REF` spent on a click is
+worse than a failed command.
+
## Using `POST /find`
```bash
diff --git a/internal/cli/actions/actions_find.go b/internal/cli/actions/actions_find.go
index 12b2b917..80bade3e 100644
--- a/internal/cli/actions/actions_find.go
+++ b/internal/cli/actions/actions_find.go
@@ -10,6 +10,19 @@ import (
"github.com/spf13/cobra"
)
+// noElementsMatched is the one wording for the empty result, echoing the query so an agent
+// can see what was actually searched. Both empty states in this command render it: the
+// default path prints it and exits 0, the way `console` and `errors` state an empty result,
+// while --ref-only prints it to stderr and exits non-zero.
+//
+// The two contracts are deliberate, not a leftover. --ref-only exists so a caller can write
+// REF=$(pinchtab find … --ref-only) and spend the result on a click, and an empty REF is
+// worse than a failed command. Unifying them in either direction would break one of the two
+// callers, so what is shared is the sentence, not the exit code.
+func noElementsMatched(query string) string {
+ return fmt.Sprintf("No elements matched %q", query)
+}
+
func Find(client *http.Client, base, token string, query string, cmd *cobra.Command) {
tabID, _ := cmd.Flags().GetString("tab")
threshold, _ := cmd.Flags().GetString("threshold")
@@ -36,7 +49,7 @@ func Find(client *http.Client, base, token string, query string, cmd *cobra.Comm
fmt.Println(ref)
return
}
- cli.Fatal("No element found")
+ cli.Fatal("%s", noElementsMatched(query))
}
if jsonOutput {
@@ -53,7 +66,9 @@ func Find(client *http.Client, base, token string, query string, cmd *cobra.Comm
role, _ := result["role"].(string)
name, _ := result["name"].(string)
output.Value(fmt.Sprintf("%s\t%s\t%q", ref, role, name))
+ return
}
+ output.Value(noElementsMatched(query))
return
}
for _, m := range matches {
diff --git a/internal/cli/actions/actions_find_test.go b/internal/cli/actions/actions_find_test.go
index 7c8dcb7c..3d491ecf 100644
--- a/internal/cli/actions/actions_find_test.go
+++ b/internal/cli/actions/actions_find_test.go
@@ -2,6 +2,12 @@ package actions
import (
"encoding/json"
+ "errors"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "os/exec"
+ "strings"
"testing"
"github.com/spf13/cobra"
@@ -55,3 +61,117 @@ func TestFind_VisualQueryWithTabRoute(t *testing.T) {
t.Errorf("expected visual query passthrough, got %v", body["query"])
}
}
+
+const noMatchPayload = `{"best_ref":"","confidence":"low","matches":[]}`
+
+// find was the one read verb that said nothing when it had nothing to say, so an agent
+// could not tell "not on this page" from "the command failed" — three situations with three
+// different next actions.
+func TestFind_NoMatchPrintsTheEmptyStateNamingTheQuery(t *testing.T) {
+ m := newMockServer()
+ m.response = noMatchPayload
+ defer m.close()
+
+ cmd := newFindCmd()
+ out := captureStdout(t, func() {
+ Find(m.server.Client(), m.base(), "", "a unicorn that does not exist", cmd)
+ })
+
+ want := `No elements matched "a unicorn that does not exist"`
+ if strings.TrimSpace(out) != want {
+ t.Errorf("stdout = %q, want %q", out, want)
+ }
+}
+
+// A match must still print the match and nothing else: the empty state sits in the same
+// branch as the single-result format, so an else in the wrong place would print both.
+func TestFind_AMatchDoesNotPrintTheEmptyState(t *testing.T) {
+ m := newMockServer()
+ m.response = `{"best_ref":"e2","role":"textbox","name":"Password"}`
+ defer m.close()
+
+ cmd := newFindCmd()
+ out := captureStdout(t, func() {
+ Find(m.server.Client(), m.base(), "", "the password box", cmd)
+ })
+
+ if strings.Contains(out, "No elements matched") {
+ t.Errorf("stdout = %q, want the match line alone", out)
+ }
+ if !strings.Contains(out, `e2 textbox "Password"`) {
+ t.Errorf("stdout = %q, want the terse match line", out)
+ }
+}
+
+// --json is the machine contract: the renderer edit must not add a line to it.
+func TestFind_JSONOutputCarriesNoEmptyStateLine(t *testing.T) {
+ m := newMockServer()
+ m.response = noMatchPayload
+ defer m.close()
+
+ cmd := newFindCmd()
+ _ = cmd.Flags().Set("json", "true")
+ out := captureStdout(t, func() {
+ Find(m.server.Client(), m.base(), "", "a unicorn that does not exist", cmd)
+ })
+
+ if strings.Contains(out, "No elements matched") {
+ t.Fatalf("--json stdout = %q, want the payload alone", out)
+ }
+ var payload map[string]any
+ if err := json.Unmarshal([]byte(out), &payload); err != nil {
+ t.Fatalf("--json stdout is not the payload any more (%v): %q", err, out)
+ }
+ if payload["confidence"] != "low" {
+ t.Errorf("--json payload = %v, want the server's body unchanged", payload)
+ }
+}
+
+// The two no-match contracts, asserted as exit codes because that is the whole difference:
+// the default path answers 0 like every other empty read, and --ref-only fails so
+// REF=$(pinchtab find … --ref-only) never receives an empty string. Both are driven in a
+// child process, since cli.Fatal calls os.Exit.
+func TestFind_NoMatchExitsZeroByDefaultAndNonZeroForRefOnly(t *testing.T) {
+ if mode := os.Getenv(findNoMatchChildEnv); mode != "" {
+ runFindNoMatchChild(mode == "ref-only")
+ return
+ }
+
+ for _, tc := range []struct {
+ mode string
+ wantFatal bool
+ }{
+ {"default", false},
+ {"ref-only", true},
+ } {
+ t.Run(tc.mode, func(t *testing.T) {
+ child := exec.Command(os.Args[0], "-test.run=TestFind_NoMatchExitsZeroByDefaultAndNonZeroForRefOnly", "-test.timeout=60s") // #nosec G204 -- re-executes this test binary.
+ child.Env = append(os.Environ(), findNoMatchChildEnv+"="+tc.mode)
+ raw, err := child.CombinedOutput()
+
+ var exitErr *exec.ExitError
+ failed := errors.As(err, &exitErr)
+ if failed != tc.wantFatal {
+ t.Fatalf("%s exited with %v, want fatal=%v; output:\n%s", tc.mode, err, tc.wantFatal, raw)
+ }
+ if !strings.Contains(string(raw), `No elements matched "a unicorn that does not exist"`) {
+ t.Errorf("%s said nothing about the empty result; output:\n%s", tc.mode, raw)
+ }
+ })
+ }
+}
+
+const findNoMatchChildEnv = "PINCHTAB_TEST_FIND_NO_MATCH_MODE"
+
+func runFindNoMatchChild(refOnly bool) {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ _, _ = w.Write([]byte(noMatchPayload))
+ }))
+ defer srv.Close()
+
+ cmd := newFindCmd()
+ if refOnly {
+ _ = cmd.Flags().Set("ref-only", "true")
+ }
+ Find(srv.Client(), srv.URL, "", "a unicorn that does not exist", cmd)
+}