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.mdindex 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````bashdiff --git a/internal/cli/actions/actions_find.go b/internal/cli/actions/actions_find.goindex 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.Commfmt.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.Commrole, _ := 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.goindex 7c8dcb7c..3d491ecf 100644--- a/internal/cli/actions/actions_find_test.go+++ b/internal/cli/actions/actions_find_test.go@@ -2,6 +2,12 @@ package actionsimport ("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)+}