Skip to content

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.md
index 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 a
field, 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.go
index 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 the
diff --git a/internal/bridge/action_form_test.go b/internal/bridge/action_form_test.go
new file mode 100644
index 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.go
index 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. Clearing
diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index 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.CallToolRequ
if _, 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.CallToolRequ
if _, 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 empty
diff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.go
index 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