High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: no surface can select an empty-valued option, so a dropdown cannot be reset to its placeholder (PIN-209)
Luigi Agostie06c8a45fab6
diff --git a/docs/endpoints.md b/docs/endpoints.mdindex 95262e1b..9cae32af 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -190,6 +190,13 @@ Action targeting fields:field `select` reads. A `fill` carrying neither is rejected — send `"text": ""` to clear afield, so clearing stays distinct from a request whose text never arrived.+`select` matches the `<option value="...">` attribute first and the option's visible text+second, so either spelling works. It draws the same absent-versus-supplied distinction as+`fill`: send `"value": ""` to select an `<option value="">` placeholder and reset the+dropdown, and a `select` carrying neither key is rejected. Every surface expresses it —+`POST /action` with `"value": ""`, `pinchtab select <ref> ""`, and the `pinchtab_select` MCP+tool with `value: ""`.+`humanize` is a per-action override for input style. When omitted, actions use `instanceDefaults.humanize`, which defaults to `false`. Use `kind:"click"` or `kind:"type"` with `humanize:true` when a page needs the slower human-like pointer or typing path.Pointer fallback behavior:diff --git a/internal/bridge/action_form.go b/internal/bridge/action_form.goindex 0fdb3424..04c29931 100644--- a/internal/bridge/action_form.go+++ b/internal/bridge/action_form.go@@ -73,12 +73,9 @@ func (b *Bridge) actionFocus(ctx context.Context, req ActionRequest) (map[string}func (b *Bridge) actionSelect(ctx context.Context, req ActionRequest) (map[string]any, error) {- val := req.Value- if val == "" {- val = req.Text- }- if val == "" {- return nil, fmt.Errorf("value required for select")+ val, supplied := SelectValue(req)+ if !supplied {+ return nil, fmt.Errorf(`select requires "value" (or "text"); send "value": "" to select an empty-valued option`)}// Both paths route through SelectByNodeID so they share its// value-then-text match fallback. This lets callers pass either thediff --git a/internal/bridge/action_form_test.go b/internal/bridge/action_form_test.gonew file mode 100644index 00000000..783e1433--- /dev/null+++ b/internal/bridge/action_form_test.go@@ -0,0 +1,133 @@+package bridge++import (+ "context"+ "encoding/base64"+ "encoding/json"+ "os"+ "strings"+ "testing"+ "time"++ "github.com/chromedp/chromedp"+ "github.com/pinchtab/pinchtab/internal/config"+ "github.com/pinchtab/pinchtab/internal/testbrowser"+)++func decodeSelectRequest(t *testing.T, body string) ActionRequest {+ t.Helper()++ var req ActionRequest+ if err := json.Unmarshal([]byte(body), &req); err != nil {+ t.Fatalf("decode %s: %v", body, err)+ }+ return req+}++// `<option value="">` is the standard placeholder, and selecting it is how a dropdown is+// reset. An empty value and an absent one both left Value and Text empty, so select refused+// both — and told a caller that had supplied the argument it was missing.+//+// The pair is the assertion: either half alone is satisfiable by deleting the check.+func TestSelectSeparatesASuppliedEmptyValueFromAnAbsentOne(t *testing.T) {+ for _, tc := range []struct {+ body string+ want string+ supplied bool+ }{+ {body: `{"kind":"select","selector":"#pick"}`},+ {body: `{"kind":"select","selector":"#pick","value":""}`, supplied: true},+ {body: `{"kind":"select","selector":"#pick","text":""}`, supplied: true},+ {body: `{"kind":"select","selector":"#pick","value":"uk"}`, want: "uk", supplied: true},+ {body: `{"kind":"select","selector":"#pick","text":"United Kingdom"}`, want: "United Kingdom", supplied: true},+ } {+ got, supplied := SelectValue(decodeSelectRequest(t, tc.body))+ if supplied != tc.supplied || got != tc.want {+ t.Errorf("%s: SelectValue = (%q, %v), want (%q, %v)", tc.body, got, supplied, tc.want, tc.supplied)+ }+ }+}++// The browserless half of the pair, so the rule is still guarded where no browser runs.+// Resolving the element needs a browser this test does not have, so the assertion on the+// supplied-empty case is that it got PAST the refusal and failed later.+func TestActionSelectRefusesOnlyWhenNoValueWasSupplied(t *testing.T) {+ b := &Bridge{}++ _, err := b.actionSelect(context.Background(), decodeSelectRequest(t, `{"kind":"select","selector":"#pick"}`))+ if err == nil {+ t.Fatal("a select carrying no value at all was accepted")+ }+ if !strings.Contains(err.Error(), `send "value": ""`) {+ t.Errorf("refusal = %v, want it to name the empty-valued option idiom", err)+ }++ _, err = b.actionSelect(context.Background(), decodeSelectRequest(t, `{"kind":"select","selector":"#pick","value":""}`))+ if err != nil && strings.Contains(err.Error(), `send "value": ""`) {+ t.Errorf("a supplied empty value was refused as absent: %v", err)+ }+}++// The outcome asserted against the PAGE, not against the action result: the result echoes+// back what the caller asked for, so it reports success for a selection that never landed.+func TestSelectAppliesASuppliedEmptyValueToThePage(t *testing.T) {+ chromePath := testbrowser.Path(t)+ profile := testbrowser.ProfileDir(t)+ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(+ chromedp.DefaultExecAllocatorOptions[:],+ chromedp.ExecPath(chromePath),+ chromedp.UserDataDir(profile),+ chromedp.Flag("headless", true),+ chromedp.Flag("no-sandbox", true),+ )...)+ ctx, cancel := chromedp.NewContext(alloc)+ ctx, cancelTimeout := context.WithTimeout(ctx, 20*time.Second)+ t.Cleanup(func() {+ cancelTimeout()+ cancel()+ cancelAlloc()+ _ = os.RemoveAll(profile)+ })++ html := `<select id="pick">+ <option value="uk">United Kingdom</option>+ <option value="">-- choose --</option>+ <option value="fr">France</option>+ </select>`+ dataURL := "data:text/html;base64," + base64.StdEncoding.EncodeToString([]byte(html))+ if err := chromedp.Run(ctx, chromedp.Navigate(dataURL)); err != nil {+ t.Fatal(err)+ }+ selected := func() string {+ t.Helper()+ var value string+ if err := chromedp.Run(ctx, chromedp.Evaluate(`document.querySelector('#pick').value`, &value)); err != nil {+ t.Fatalf("read the selected value: %v", err)+ }+ return value+ }+ b := New(context.Background(), nil, &config.RuntimeConfig{})++ if _, err := b.Actions[ActionSelect](ctx, decodeSelectRequest(t, `{"kind":"select","selector":"#pick","value":""}`)); err != nil {+ t.Fatalf("a supplied empty value was refused: %v", err)+ }+ if got := selected(); got != "" {+ t.Errorf("the page has %q selected, want the empty-valued placeholder", got)+ }++ // The value-then-text fallback is what makes most placeholders reachable by label, so+ // selection by visible text must keep working alongside the empty-value case.+ if _, err := b.Actions[ActionSelect](ctx, decodeSelectRequest(t, `{"kind":"select","selector":"#pick","value":"France"}`)); err != nil {+ t.Fatalf("select by visible text: %v", err)+ }+ if got := selected(); got != "fr" {+ t.Errorf("selection by visible text left %q selected, want fr", got)+ }++ if _, err := b.Actions[ActionSelect](ctx, decodeSelectRequest(t, `{"kind":"select","selector":"#pick"}`)); err == nil {+ t.Error("a select carrying no value at all was accepted")+ }+ if got := selected(); got != "fr" {+ t.Errorf("the refused select changed the page to %q; a refusal must not act", got)+ }+}diff --git a/internal/bridge/action_request.go b/internal/bridge/action_request.goindex cf800682..25c56b6b 100644--- a/internal/bridge/action_request.go+++ b/internal/bridge/action_request.go@@ -253,6 +253,23 @@ func FillText(req ActionRequest) (string, bool) {return "", req.HasText}+// SelectValue is FillText with the precedence reversed, and they stay two named functions+// because the precedence IS the difference — a shared helper taking a preference argument+// would hide it at both call sites.+//+// Supplied-ness reads HasText, which is inferred from key presence of text OR value, and+// those are exactly the two fields select reads. So an explicitly supplied empty string is+// a request to select the `<option value="">` placeholder, not an absent argument.+func SelectValue(req ActionRequest) (string, bool) {+ if req.Value != "" {+ return req.Value, true+ }+ if req.Text != "" {+ return req.Text, true+ }+ return "", req.HasText+}+// ValidateFillAction refuses a fill that carries no text under any spelling. That// request used to write "" and answer filled:true with len:0 — indistinguishable// from clearing a field on purpose, which is why it stayed invisible. Clearingdiff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.goindex 24a3acf7..55f8e95c 100644--- a/internal/mcp/handlers_interaction.go+++ b/internal/mcp/handlers_interaction.go@@ -22,6 +22,33 @@ var humanizeAction = map[string]bool{"click": true, "hover": true}// forwarded an inert, undiscoverable and unvalidated pair, hasXY included.var xyAction = map[string]bool{"click": true, "hover": true, "scroll": true}+// suppliedStringArg resolves an argument whose PRESENCE, not emptiness, says it was asked+// for, and refuses with a message the caller can act on. Both refusals exist because the+// collapsing accessor answers "missing" to two requests that are not missing: one that+// supplied the empty string on purpose, and one that supplied the argument under a type the+// library never enforced. An agent told to send what it just sent has nowhere to go.+//+// emptyMeans says what the empty string DOES on this verb; a verb where it means nothing+// passes "" and the refusals leave the clause out.+func suppliedStringArg(r mcp.CallToolRequest, verb, arg, emptyMeans string, keys ...string) (string, *mcp.CallToolResult) {+ value, supplied, wrongType := firstSuppliedString(r, keys...)+ if supplied {+ return value, nil+ }+ if wrongType != "" {+ message := fmt.Sprintf("%s's '%s' must be a string, got %s; quote it", verb, arg, wrongType)+ if emptyMeans != "" {+ message += ", or " + emptyMeans+ }+ return "", mcp.NewToolResultError(message)+ }+ message := fmt.Sprintf("%s needs a '%s' argument", verb, arg)+ if emptyMeans != "" {+ message += "; " + emptyMeans+ }+ return "", mcp.NewToolResultError(message)+}+func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {payload := map[string]any{"kind": kind}@@ -107,9 +134,15 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequif _, err := resolveSelector(!hasNodeID); err != nil {return mcp.NewToolResultError(err.Error()), nil}- text := firstNonEmptyString(r, "text", "value")- if text == "" {- return mcp.NewToolResultError("required parameter 'text' is missing"), nil+ // Typing nothing is meaningless, so type keeps collapsing empty with absent —+ // but only after a wrong-typed argument has been named as one, rather than+ // reported as an argument the caller never sent.+ text, refusal := suppliedStringArg(r, "type", "text", "", "text", "value")+ if refusal != nil {+ return refusal, nil+ }+ if strings.TrimSpace(text) == "" {+ return mcp.NewToolResultError("type needs a non-empty 'text' argument"), nil}payload["text"] = text@@ -124,9 +157,12 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequif _, err := resolveSelector(!hasNodeID); err != nil {return mcp.NewToolResultError(err.Error()), nil}- value := firstNonEmptyString(r, "value", "option")- if value == "" {- return mcp.NewToolResultError("required parameter 'value' is missing"), nil+ // `<option value="">` is the standard placeholder, so an empty value is a real+ // selection — the one that resets a dropdown — and the bridge tells it apart+ // from an absent one by key presence.+ value, refusal := suppliedStringArg(r, "select", "value", `send "" to select an empty-valued option`, "value", "option")+ if refusal != nil {+ return refusal, nil}payload["value"] = value@@ -199,12 +235,9 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ// so refusing it made the one documented clear idiom inexpressible here// while the raw API accepted it — and the old message claimed a parameter// the caller had supplied was missing.- value, supplied, wrongType := firstSuppliedString(r, "value", "text")- if !supplied {- if wrongType != "" {- return mcp.NewToolResultError(fmt.Sprintf("fill's 'value' must be a string, got %s; quote it, or send \"\" to clear the field", wrongType)), nil- }- return mcp.NewToolResultError("fill needs a 'value' argument; send \"\" to clear the field"), nil+ value, refusal := suppliedStringArg(r, "fill", "value", `send "" to clear the field`, "value", "text")+ if refusal != nil {+ return refusal, nil}// "text" is the field actionFill reads. Posting the same string under "value"// reached a real ActionRequest field that fill ignores, so the write was emptydiff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.goindex bef134bd..2d106d68 100644--- a/internal/mcp/handlers_interaction_test.go+++ b/internal/mcp/handlers_interaction_test.go@@ -667,6 +667,132 @@ func TestFillStillSendsAnEmptyStringVerbatim(t *testing.T) {}}+// `<option value="">` is the standard placeholder, so an empty value is the one selection+// that resets a dropdown. The pair is the assertion: either half alone is satisfiable by+// deleting the check, which would forward a select with no value at all.+func TestSelectForwardsASuppliedEmptyValueAndStillRefusesAnAbsentOne(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ for _, key := range []string{"value", "option"} {+ t.Run("supplied empty "+key+" selects the placeholder", func(t *testing.T) {+ r := callTool(t, "pinchtab_select", map[string]any{"ref": "e0", key: ""}, srv)+ if r.IsError {+ t.Fatalf("a supplied empty %s was refused: %s", key, resultText(t, r))+ }+ body, _ := resultJSON(t, r)["body"].(map[string]any)+ value, present := body["value"]+ if !present {+ t.Fatalf("payload carries no value key, so the bridge cannot tell a placeholder selection from a request whose value never arrived: %v", body)+ }+ if got, _ := value.(string); got != "" {+ t.Errorf("forwarded value = %q, want the empty string that selects the placeholder", got)+ }+ })+ }++ t.Run("absent value is refused", func(t *testing.T) {+ r := callTool(t, "pinchtab_select", map[string]any{"ref": "e0"}, srv)+ if !r.IsError {+ body, _ := resultJSON(t, r)["body"].(map[string]any)+ t.Fatalf("a select with no value at all was forwarded as %v; absent is not a placeholder", body)+ }+ message := resultText(t, r)+ if strings.Contains(message, "is missing") && strings.Contains(message, "'value'") {+ t.Errorf("refusal %q reads as a supplied parameter being missing; it must say what select needs", message)+ }+ if !strings.Contains(message, "empty-valued option") {+ t.Errorf("refusal %q does not tell the caller how to reach the placeholder, which is the case it is most likely to be confused with", message)+ }+ })+}++// The two verbs still reading the collapsing accessor answered "the argument is missing" to+// an argument the caller had sent under the wrong type — the same dead end fill was fixed to+// remove. The genuinely-absent row is the pair: collapsing the two again reds it.+func TestSelectAndTypeNameAWrongTypedArgumentInsteadOfCallingItMissing(t *testing.T) {+ for _, tc := range []struct {+ name string+ tool string+ args map[string]any+ wantSays string+ }{+ {name: "select a number", tool: "pinchtab_select", args: map[string]any{"selector": "e5", "value": float64(2024)}, wantSays: "must be a string, got number"},+ {name: "select a boolean", tool: "pinchtab_select", args: map[string]any{"selector": "e5", "value": true}, wantSays: "must be a string, got boolean"},+ {name: "select genuinely absent", tool: "pinchtab_select", args: map[string]any{"selector": "e5"}, wantSays: "needs a 'value' argument"},+ {name: "type a number", tool: "pinchtab_type", args: map[string]any{"selector": "e5", "text": float64(2024)}, wantSays: "must be a string, got number"},+ {name: "type an array", tool: "pinchtab_type", args: map[string]any{"selector": "e5", "text": []any{"a"}}, wantSays: "must be a string, got array"},+ {name: "type genuinely absent", tool: "pinchtab_type", args: map[string]any{"selector": "e5"}, wantSays: "needs a 'text' argument"},+ } {+ t.Run(tc.name, func(t *testing.T) {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {+ t.Error("an unusable argument was posted instead of refused")+ w.Header().Set("Content-Type", "application/json")+ _, _ = w.Write([]byte(`{}`))+ }))+ defer srv.Close()++ res := callTool(t, tc.tool, tc.args, srv)++ if !res.IsError {+ t.Fatalf("accepted %v", tc.args)+ }+ if text := resultText(t, res); !strings.Contains(text, tc.wantSays) {+ t.Errorf("error = %q, want it to say %q so the caller knows what to change", text, tc.wantSays)+ }+ })+ }+}++// The surfaces are compared on the WIRE, not against two copies of a rule: each builds its+// own body, and the bridge reads key presence, so only the posted bytes can show that a+// caller reaches the placeholder whichever surface it came in through. The raw API is the+// same body, asserted against a real page in internal/bridge.+func TestSelectSendsAnEmptyValueOnEverySurface(t *testing.T) {+ var mcpBody string+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ raw, _ := io.ReadAll(r.Body)+ mcpBody = string(raw)+ w.Header().Set("Content-Type", "application/json")+ _, _ = w.Write([]byte(`{"ok":true}`))+ }))+ defer srv.Close()++ res := callTool(t, "pinchtab_select", map[string]any{"selector": "e5", "value": ""}, srv)+ if res.IsError {+ t.Fatalf("MCP refused an empty value: %s", resultText(t, res))+ }+ if !strings.Contains(mcpBody, `"value":""`) {+ t.Errorf("MCP posted %s, want value:\"\" — the key presence is what the bridge reads", mcpBody)+ }++ if cliBody := cliSelectBody(t, ""); !strings.Contains(cliBody, `"value":""`) {+ t.Errorf("the CLI posted %s, want value:\"\" — the surfaces must express the same selection", cliBody)+ }+}++// cliSelectBody runs the CLI's own select builder against a recording server and returns the+// raw body it posted, so the assertion is on the wire rather than on two copies of a rule.+func cliSelectBody(t *testing.T, value string) string {+ t.Helper()+ var raw []byte+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ raw, _ = io.ReadAll(r.Body)+ _, _ = w.Write([]byte(`{"success":true}`))+ }))+ defer srv.Close()++ cmd := &cobra.Command{}+ cmd.Flags().String("tab", "", "")+ cmd.Flags().Bool("json", false, "")+ cmd.Flags().Bool("snap", false, "")+ cmd.Flags().Bool("snap-diff", false, "")+ cmd.Flags().Bool("text", false, "")+ browseractions.ActionSimple(srv.Client(), srv.URL, "", "select", []string{"e5", value}, cmd)++ return string(raw)+}+// THE CARD'S MEASUREMENT, as a test: capture the outbound body on BOTH surfaces and// compare them, rather than comparing constants — the two surfaces each used to build// their own body from their own copy of the vocabulary, so only the bodies can show they