High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
package mcp
import (
"encoding/json"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io"
"net/http"
"net/http/httptest"
"os"
"reflect"
"regexp"
"sort"
"strconv"
"strings"
"testing"
"github.com/mark3labs/mcp-go/mcp"
)
// upstreamRecorder records every request that reaches PinchTab, so a test can
// assert a rejected call never got there — an error result alone cannot tell a
// pre-dispatch rejection from a request that went out and came back failing.
func upstreamRecorder(t *testing.T) (*httptest.Server, *[]string) {
t.Helper()
paths := &[]string{}
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
*paths = append(*paths, r.Method+" "+r.URL.Path)
resp := map[string]any{"path": r.URL.Path}
if body, _ := io.ReadAll(r.Body); len(body) > 0 {
var parsed map[string]any
if json.Unmarshal(body, &parsed) == nil {
resp["body"] = parsed
}
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(200)
_ = json.NewEncoder(w).Encode(resp)
}))
t.Cleanup(srv.Close)
return srv, paths
}
// A malformed delta must be reported, not dropped. Dropping it degrades a wheel
// scroll into a bare scroll with no magnitude, because hasDeltaY gates the wheel
// branch.
func TestScrollRejectsAMalformedDeltaWithoutCallingUpstream(t *testing.T) {
srv, paths := upstreamRecorder(t)
for _, malformed := range []string{"-300px", "300 pixels", "three hundred"} {
t.Run(malformed, func(t *testing.T) {
*paths = nil
result := callTool(t, "pinchtab_scroll", map[string]any{"deltaY": malformed}, srv)
if !result.IsError {
t.Fatalf("deltaY=%q was accepted: %s", malformed, resultText(t, result))
}
message := resultText(t, result)
if !strings.Contains(message, "deltaY") {
t.Errorf("error %q does not name the argument", message)
}
if !strings.Contains(message, malformed) {
t.Errorf("error %q does not echo the received value", message)
}
if len(*paths) != 0 {
t.Errorf("rejected call still reached upstream: %v", *paths)
}
})
}
}
// The case a caller cannot detect: direction synthesises a magnitude precisely
// because the malformed deltaY was dropped, so the tool scrolls DOWN by 120 when
// asked to scroll UP by 300 — sign inverted, magnitude invented, no error.
func TestScrollRejectsAMalformedDeltaRatherThanLettingDirectionInventOne(t *testing.T) {
srv, paths := upstreamRecorder(t)
result := callTool(t, "pinchtab_scroll", map[string]any{
"deltaY": "-300px",
"direction": "down",
}, srv)
if !result.IsError {
body := resultText(t, result)
if strings.Contains(body, "120") {
t.Fatalf("direction invented a magnitude for a malformed deltaY: %s", body)
}
t.Fatalf("malformed deltaY with direction was accepted: %s", body)
}
if len(*paths) != 0 {
t.Errorf("rejected call still reached upstream: %v", *paths)
}
}
// withBounds is an opt-out, so a dropped "no" leaves bounds switched on and the
// response looks like the default rather than like the request.
func TestCaptureRejectsAMalformedBoolean(t *testing.T) {
srv, paths := upstreamRecorder(t)
result := callTool(t, "pinchtab_capture", map[string]any{"withBounds": "no"}, srv)
if !result.IsError {
t.Fatalf(`withBounds="no" was accepted: %s`, resultText(t, result))
}
message := resultText(t, result)
if !strings.Contains(message, "withBounds") {
t.Errorf("error %q does not name the argument", message)
}
if !strings.Contains(message, "no") {
t.Errorf("error %q does not echo the received value", message)
}
if len(*paths) != 0 {
t.Errorf("rejected call still reached upstream: %v", *paths)
}
}
// Models emit "" for "not set"; turning that into a failure would be a
// regression, and so would rejecting an argument nobody passed.
func TestAbsentAndEmptyTypedArgumentsAreNotRejected(t *testing.T) {
for _, tc := range []struct {
name string
args map[string]any
}{
{name: "absent", args: map[string]any{}},
{name: "empty string", args: map[string]any{"deltaY": "", "steps": "", "x": ""}},
{name: "explicit null", args: map[string]any{"deltaY": nil}},
} {
t.Run(tc.name, func(t *testing.T) {
if err := validateTypedArgs("pinchtab_scroll", tc.args); err != nil {
t.Errorf("validateTypedArgs(%v) = %v, want nil — not set must not become a failure", tc.args, err)
}
})
}
}
// Every shape the accessors read today must still pass validation, or the fix
// would break working callers rather than malformed ones.
func TestReadableTypedArgumentsPassValidation(t *testing.T) {
for _, args := range []map[string]any{
{"deltaY": float64(-300)},
{"deltaY": "-300"},
{"deltaY": " -300 "},
{"deltaY": "-300.5"},
{"steps": "2", "x": "10", "y": float64(20)},
} {
if err := validateTypedArgs("pinchtab_scroll", args); err != nil {
t.Errorf("validateTypedArgs(%v) = %v, want nil", args, err)
}
}
for _, args := range []map[string]any{
{"withBounds": true},
{"withBounds": "true"},
{"withBounds": "false"},
{"withBounds": "1"},
} {
if err := validateTypedArgs("pinchtab_capture", args); err != nil {
t.Errorf("validateTypedArgs(%v) = %v, want nil", args, err)
}
}
}
// The argument list is derived from the schemas, so a tool gaining a WithNumber
// argument is validated on arrival. This asserts the derivation actually found
// the declared types rather than silently returning an empty map, which would
// make every test above pass vacuously.
func TestTypedArgsAreDerivedFromTheToolSchemas(t *testing.T) {
types := schemaArgTypesOnce()
if len(types) == 0 {
t.Fatal("no tool schemas parsed — validation would be a no-op for every tool")
}
declared := 0
for _, tool := range allTools() {
raw, err := json.Marshal(tool.InputSchema)
if err != nil {
t.Fatalf("marshal %s schema: %v", tool.Name, err)
}
var schema struct {
Properties map[string]struct {
Type string `json:"type"`
} `json:"properties"`
}
if err := json.Unmarshal(raw, &schema); err != nil {
t.Fatalf("unmarshal %s schema: %v", tool.Name, err)
}
for name, property := range schema.Properties {
switch property.Type {
case "number", "integer", "boolean":
declared++
if got := types[tool.Name][name]; got != property.Type {
t.Errorf("%s.%s typed %q by the schema but %q by the validator", tool.Name, name, property.Type, got)
}
default:
if got, ok := types[tool.Name][name]; ok {
t.Errorf("%s.%s is %q in the schema but the validator typed it %q", tool.Name, name, property.Type, got)
}
}
}
}
if declared == 0 {
t.Fatal("no numeric or boolean argument found in any schema — this guard is checking nothing")
}
t.Logf("validating %d schema-declared numeric/boolean arguments", declared)
}
// A handler with no schema would silently skip validation, so a new tool cannot
// be added to one side only.
func TestEveryHandlerHasASchemaAndEverySchemaAHandler(t *testing.T) {
handlers := rawHandlerMap(NewClient("http://example.invalid", ""))
schemas := map[string]struct{}{}
for _, tool := range allTools() {
schemas[tool.Name] = struct{}{}
}
for name := range handlers {
if _, ok := schemas[name]; !ok {
t.Errorf("handler %q has no tool schema, so its arguments are never validated", name)
}
}
for name := range schemas {
if _, ok := handlers[name]; !ok {
t.Errorf("tool %q has a schema but no handler", name)
}
}
}
// Declaring humanize is only half the fix: it was previously read solely to raise
// the mutual-exclusion error and never forwarded, so humanized input was
// unreachable from MCP even for a caller who guessed the name.
func TestPointerToolsForwardHumanizeToUpstream(t *testing.T) {
for _, tool := range []string{"pinchtab_click", "pinchtab_hover"} {
t.Run(tool, func(t *testing.T) {
srv, _ := upstreamRecorder(t)
result := callTool(t, tool, map[string]any{"selector": "#b", "humanize": true}, srv)
if result.IsError {
t.Fatalf("humanize=true was rejected: %s", resultText(t, result))
}
body, _ := resultJSON(t, result)["body"].(map[string]any)
if got, ok := body["humanize"]; !ok || got != true {
t.Errorf("outbound body humanize = %v (present: %v), want true — the argument must be usable, not just accepted", got, ok)
}
})
}
}
// An explicit false is an opt-OUT and must travel, because the wire field is a
// per-request override of the instance default rather than a flag.
func TestPointerToolsForwardAnExplicitHumanizeFalse(t *testing.T) {
srv, _ := upstreamRecorder(t)
result := callTool(t, "pinchtab_click", map[string]any{"selector": "#b", "humanize": false}, srv)
body, _ := resultJSON(t, result)["body"].(map[string]any)
if got, ok := body["humanize"]; !ok || got != false {
t.Errorf("outbound body humanize = %v (present: %v), want false to travel as an opt-out", got, ok)
}
}
// Forwarding must not become an unconditional default: a call that omits humanize
// has to leave the instance config in charge.
func TestOmittedHumanizeIsNotForwarded(t *testing.T) {
for _, tool := range []string{"pinchtab_click", "pinchtab_hover"} {
t.Run(tool, func(t *testing.T) {
srv, _ := upstreamRecorder(t)
result := callTool(t, tool, map[string]any{"selector": "#b"}, srv)
body, _ := resultJSON(t, result)["body"].(map[string]any)
if got, ok := body["humanize"]; ok {
t.Errorf("outbound body carries humanize = %v with none requested; the instance default must stay in charge", got)
}
})
}
}
// The third defect: before humanize was declared, the schema-derived validator
// could not see it, so "yes" was silently dropped and the mutual-exclusion guard
// it feeds was bypassed — the guard fired for true and "true" but not "yes".
// argcheck.go is untouched; the declaration alone brings this under validation.
func TestMalformedHumanizeIsRejectedFromTheDeclarationAlone(t *testing.T) {
srv, paths := upstreamRecorder(t)
result := callTool(t, "pinchtab_click", map[string]any{"selector": "#b", "mode": "dom", "humanize": "yes"}, srv)
if !result.IsError {
t.Fatalf(`humanize="yes" was accepted: %s`, resultText(t, result))
}
message := resultText(t, result)
if !strings.Contains(message, "humanize") {
t.Errorf("error %q does not name the argument", message)
}
if len(*paths) != 0 {
t.Errorf("rejected call still reached upstream: %v", *paths)
}
}
// The mutual-exclusion rule the CLI enforces stays enforced, for the parsed string
// form too, and only on the tool that has both arguments.
func TestModeAndHumanizeRemainMutuallyExclusiveOnClick(t *testing.T) {
for _, humanize := range []any{true, "true"} {
srv, _ := upstreamRecorder(t)
result := callTool(t, "pinchtab_click", map[string]any{"selector": "#b", "mode": "dom", "humanize": humanize}, srv)
if !result.IsError {
t.Errorf("mode+humanize=%v was accepted: %s", humanize, resultText(t, result))
}
}
}
// Only the pointer tools declare it. A tool without a pointer path must not, or
// the schema would advertise an argument its handler ignores.
func TestOnlyPointerToolsDeclareHumanize(t *testing.T) {
declaring := map[string]bool{}
for _, tool := range allTools() {
if _, ok := typedArgsOf(tool)["humanize"]; ok {
declaring[tool.Name] = true
}
}
want := map[string]bool{"pinchtab_click": true, "pinchtab_hover": true}
if !reflect.DeepEqual(declaring, want) {
t.Errorf("tools declaring humanize = %v, want %v (the MCP members of the CLI addPointerActionFlags set)", declaring, want)
}
for kind := range humanizeAction {
if !declaring["pinchtab_"+kind] {
t.Errorf("handler forwards humanize for %q but pinchtab_%s does not declare it", kind, kind)
}
}
}
// argumentProbe is what this guard sends: the typed arguments to probe together,
// plus fixed-value companions that make them reachable at all.
//
// A probe is a SET rather than a name because some arguments cannot show an effect
// alone — resolveXY needs both x and y, and steps is folded in only under a
// direction, and only by multiplying into deltaY. Companions may be of any type:
// direction is a string, and this guard deliberately never probes strings (the
// sibling census records why — no coercion, so nothing is silently dropped), so a
// string can only ever be a companion. A combination-only argument sent as a
// singleton cannot produce an effect on any tool, which is a vacuous pass; the
// positive control below is what forces it to be declared here instead.
type argumentProbe struct {
args []string
companions map[string]any
}
func (p argumentProbe) label() string { return strings.Join(p.args, "+") }
// combinationProbes are the probes whose arguments the handler only reads as a set.
// Everything else is derived as a singleton from the tools' own declarations.
//
// THE BOUNDARY, and it is deliberate. Each probe is sent alone or with the companions
// listed here, so the guard cannot see a leak that fires ONLY alongside an argument it
// does not pair with — pixels gated on direction reaches every tool while both halves
// of this test stay green, because the control only asks whether pixels can ever have
// an effect (it can, on scroll, alone) and the sweep never sends direction with it.
// The singleton form of the same leak reds immediately; the mutations recorded on the
// card bracket that difference on both sides.
//
// Enumerating the gap is combinatorial: the escape is per (probe, companion) PAIR, not
// per argument, so it grows with every typed argument added. The cheap alternative —
// one maximal probe per tool with every typed argument set at once — was considered and
// declined, because it does not catch this class either: the companion is frequently a
// STRING (direction here, mode elsewhere), and this guard never probes strings by
// design, since nothing is coerced and so nothing is silently dropped. Extending the
// maximal probe to strings needs a plausible value per string argument, which is a new
// hand-maintained map — the staleness this guard is built to avoid, in a different
// denomination.
//
// THE PRECONDITION is what makes that acceptable rather than ignored. A leak of this
// shape needs a typed argument read BEFORE the kind switch in handleAction that is
// neither declared by every action tool nor gated by a kind set. All three current
// pre-switch reads are covered by one of those, measured rather than assumed:
//
// x, y gated by xyAction, whose members are exactly the three action tools that
// declare x/y (click, hover, scroll); the other six never reach the read
// nodeId ungated, but declared by all nine action tools, so there is no tool it
// can leak to
// tabId read pre-switch and declared on every action tool, but as a string, which
// this guard's alphabet excludes for the reason above
//
// Every other typed argument is read inside its own case, where kind gating prevents a
// cross-tool leak by construction. So a reviewer's trigger is specific: a FOURTH
// pre-switch typed read, with neither mechanism, is what would make this gap reachable.
// Until then it is a hole in front of a shape the file does not contain, and this is
// where the chain of cards over this guard stops — not for lack of a next step, but
// because the next step costs more than the hazard.
var combinationProbes = []argumentProbe{
{args: []string{"x", "y"}},
{args: []string{"steps"}, companions: map[string]any{"direction": "down"}},
}
// callOutcome is everything this guard can observe about one tool call. The request
// list is recorded before the body is parsed: snap's effect is a second /snapshot
// GET, which makes the result text two concatenated JSON objects that resultJSON
// cannot parse — so a two-request call keeps its raw text and is compared on that.
type callOutcome struct {
requests []string
body map[string]any
text string
}
func observeToolCall(t *testing.T, tool string, args map[string]any) callOutcome {
t.Helper()
srv, paths := upstreamRecorder(t)
result := callTool(t, tool, args, srv)
if result.IsError {
t.Fatalf("%s rejected %v outright (%s); this guard reasons about arguments that are ignored, not rejected", tool, args, resultText(t, result))
}
outcome := callOutcome{requests: append([]string(nil), *paths...), text: resultText(t, result)}
if len(outcome.requests) == 1 {
outcome.body, _ = resultJSON(t, result)["body"].(map[string]any)
}
return outcome
}
// describeDifference reports how two outcomes differ, or "" when they do not. This
// is the guard's whole oracle: an argument had an observable effect if ANYTHING the
// caller can see changed. Matching the probe's own value instead — which is what
// this replaced — was blind to a derived effect, and needed hasXY hand-added to the
// condition as the tell.
func describeDifference(baseline, probed callOutcome) string {
if !reflect.DeepEqual(baseline.requests, probed.requests) {
return fmt.Sprintf("upstream requests %v -> %v", baseline.requests, probed.requests)
}
if baseline.body == nil || probed.body == nil {
if baseline.text != probed.text {
return "the response text changed"
}
return ""
}
var changes []string
for field, want := range baseline.body {
got, present := probed.body[field]
switch {
case !present:
changes = append(changes, fmt.Sprintf("%s=%v dropped", field, want))
case !reflect.DeepEqual(want, got):
changes = append(changes, fmt.Sprintf("%s %v -> %v", field, want, got))
}
}
for field, got := range probed.body {
if _, present := baseline.body[field]; !present {
changes = append(changes, fmt.Sprintf("%s=%v added", field, got))
}
}
sort.Strings(changes)
return strings.Join(changes, ", ")
}
// The per-tool half the name-level census above cannot see. A typed argument read
// for a kind whose tool does not declare it is undiscoverable AND unvalidated,
// because validateTypedArgs keys its type map per tool — the name being declared
// somewhere else does not help the tool being called. handleAction reads its
// arguments before switching on kind, so this is where that goes wrong.
//
// Behavioural rather than structural: the positive control observes reachability as a
// BASELINE DIFF on a tool that declares the probe, and the sweep then requires every
// tool that does NOT declare it to refuse the probe by name before upstream is called.
// The structural half — which keys each handler reads — is
// TestEveryArgumentAHandlerReadsIsDeclaredOnItsTool.
func TestNoActionToolIsSentATypedArgumentItDoesNotDeclare(t *testing.T) {
probes := append([]argumentProbe(nil), combinationProbes...)
grouped := map[string]bool{}
for _, probe := range probes {
for _, name := range probe.args {
grouped[name] = true
}
}
for _, tc := range actionToolTargets {
for name := range schemaArgTypesOnce()[tc.tool] {
if !grouped[name] {
probes = append(probes, argumentProbe{args: []string{name}})
grouped[name] = true
}
}
}
sort.Slice(probes, func(i, j int) bool { return probes[i].label() < probes[j].label() })
// The declared type of each name, taken from whichever action tool declares it,
// so the probe value is one the accessor would actually read.
typeOf := map[string]string{}
for _, tc := range actionToolTargets {
for name, kind := range schemaArgTypesOnce()[tc.tool] {
typeOf[name] = kind
}
}
const sentinel = 424242.0
probeArgs := func(tool string, probe argumentProbe, withProbe bool) map[string]any {
extra := map[string]any{}
for name, value := range probe.companions {
if _, declared := schemaPropertiesOnce()[tool][name]; declared {
extra[name] = value
}
}
if withProbe {
for _, name := range probe.args {
if typeOf[name] == "boolean" {
extra[name] = true
continue
}
extra[name] = sentinel
}
}
return targetedActionArgs(tool, extra)
}
// A diff oracle is only as trustworthy as the calls it compares. If anything in
// an outcome varied between two identical calls, every future card would inherit
// a red here — so this fails loudly and names the fields rather than normalising
// them away, and an exclusion has to be added deliberately.
for _, tc := range actionToolTargets {
for _, probe := range probes {
first := observeToolCall(t, tc.tool, probeArgs(tc.tool, probe, false))
second := observeToolCall(t, tc.tool, probeArgs(tc.tool, probe, false))
if diff := describeDifference(first, second); diff != "" {
t.Fatalf("%s is not stable across two identical calls (%s baseline): %s — the diff oracle below would read this as an effect, so exclude the varying field explicitly before trusting it",
tc.tool, probe.label(), diff)
}
}
}
// The positive control, and the half that keeps the probe list self-maintaining:
// every probe must be demonstrably capable of an effect on a tool that DOES
// declare it. A combination-only argument fails this as a singleton, which is
// what forces it into combinationProbes with the companions it needs instead of
// sitting in the undeclared sweep proving nothing.
for _, probe := range probes {
declaring := ""
for _, tc := range actionToolTargets {
declared := schemaArgTypesOnce()[tc.tool]
all := true
for _, name := range probe.args {
if _, ok := declared[name]; !ok {
all = false
}
}
if all {
declaring = tc.tool
break
}
}
if declaring == "" {
t.Errorf("no action tool declares %s, so the sweep below can never distinguish reachable from ignored for it", probe.label())
continue
}
baseline := observeToolCall(t, declaring, probeArgs(declaring, probe, false))
probed := observeToolCall(t, declaring, probeArgs(declaring, probe, true))
if diff := describeDifference(baseline, probed); diff == "" {
t.Errorf("%s has no observable effect on %s, which DECLARES it — so its rows in the sweep below prove nothing. Give it the companions that make it reachable (see combinationProbes) rather than leaving it a singleton.",
probe.label(), declaring)
}
}
checked := 0
for _, tc := range actionToolTargets {
declared := schemaArgTypesOnce()[tc.tool]
for _, probe := range probes {
kinds := map[string]int{}
for _, name := range probe.args {
kinds[declared[name]]++
}
if len(kinds) != 1 {
t.Errorf("%s declares %s inconsistently (%v); the group must be all-or-nothing", tc.tool, probe.label(), kinds)
continue
}
if _, isDeclared := declared[probe.args[0]]; isDeclared {
continue
}
checked++
srv, paths := upstreamRecorder(t)
result := callTool(t, tc.tool, probeArgs(tc.tool, probe, true), srv)
message := resultText(t, result)
if !result.IsError {
t.Errorf("%s: %s is undeclared but was accepted (%s); an undeclared argument must be refused, never dropped or acted on", tc.tool, probe.label(), message)
continue
}
for _, name := range probe.args {
if !strings.Contains(message, "unknown argument "+strconv.Quote(name)) {
t.Errorf("%s: refusal %q does not name the undeclared %q", tc.tool, message, name)
}
}
if len(*paths) != 0 {
t.Errorf("%s: a refused %s still reached upstream: %v", tc.tool, probe.label(), *paths)
}
}
}
if checked == 0 {
t.Fatal("no undeclared (tool, argument) pair exercised — this guard is checking nothing")
}
t.Logf("checked %d undeclared (tool, probe) pairs across %d action tools and %d probes", checked, len(actionToolTargets), len(probes))
}
// A wrapper index used to mean document order for css:/xpath: and semantic rank
// for text:, so nth:1 could resolve earlier in the page than nth:0. The rule is
// one rule now, and a schema that offers first/last/nth without stating it leaves
// an agent to infer the grammar from trial and error. Derived over the schemas:
// any tool that gains a wrapper-accepting selector inherits the requirement.
func TestSelectorSchemasThatOfferWrappersStateWhatAnIndexMeans(t *testing.T) {
checked := 0
for _, tool := range allTools() {
raw, err := json.Marshal(tool.InputSchema)
if err != nil {
t.Fatalf("marshal %s schema: %v", tool.Name, err)
}
var schema struct {
Properties map[string]struct {
Description string `json:"description"`
} `json:"properties"`
}
if err := json.Unmarshal(raw, &schema); err != nil {
t.Fatalf("unmarshal %s schema: %v", tool.Name, err)
}
for name, property := range schema.Properties {
if !strings.Contains(property.Description, "first/last/nth") {
continue
}
checked++
if !strings.Contains(property.Description, "document order") {
t.Errorf("%s.%s offers first/last/nth without saying an index follows document order: %q", tool.Name, name, property.Description)
}
if !strings.Contains(property.Description, "text:X and first:text:X can differ") {
t.Errorf("%s.%s does not warn that a bare text: selector ranks rather than indexes: %q", tool.Name, name, property.Description)
}
}
}
if checked == 0 {
t.Fatal("no schema offers first/last/nth, so this guard checked nothing")
}
}
func TestEveryToolRefusesAnUndeclaredArgumentBeforeCallingUpstream(t *testing.T) {
const undeclared = "notAnArgumentOfAnyTool"
tools := allTools()
if len(tools) == 0 {
t.Fatal("allTools() is empty, so this table checks nothing")
}
for _, tool := range tools {
t.Run(tool.Name, func(t *testing.T) {
srv, paths := upstreamRecorder(t)
result := callTool(t, tool.Name, map[string]any{undeclared: "x"}, srv)
if !result.IsError {
t.Fatalf("an undeclared argument was accepted: %s", resultText(t, result))
}
message := resultText(t, result)
if !strings.Contains(message, `unknown argument "`+undeclared+`"`) {
t.Errorf("refusal %q does not name the undeclared key", message)
}
if !strings.Contains(message, "declared arguments: "+declaredArgList(schemaPropertiesOnce()[tool.Name])) {
t.Errorf("refusal %q does not list the tool's declared arguments", message)
}
if len(*paths) != 0 {
t.Errorf("a refused call still reached upstream: %v", *paths)
}
})
}
}
func TestUndeclaredArgumentsNameTheNearestDeclaredOne(t *testing.T) {
for _, tc := range []struct {
tool string
args map[string]any
wantHint string
}{
{tool: "pinchtab_snapshot", args: map[string]any{"filter": "interactive"}, wantHint: `unknown argument "filter" (did you mean "interactive": true?)`},
{tool: "pinchtab_wait", args: map[string]any{"for": "selector", "value": "#nope", "timeoutSeconds": float64(2)}, wantHint: `unknown argument "timeoutSeconds" (did you mean "timeoutMs"?)`},
{tool: "pinchtab_scrape", args: map[string]any{"url": "https://example.com", "timeout": float64(5)}, wantHint: `unknown argument "timeout" (did you mean "timeoutSeconds"?)`},
{tool: "pinchtab_click", args: map[string]any{"selecter": "#a"}, wantHint: `unknown argument "selecter" (did you mean "selector"?)`},
{tool: "pinchtab_navigate", args: map[string]any{"url": "https://example.com", "tabid": "t1"}, wantHint: `unknown argument "tabid" (did you mean "tabId"?)`},
{tool: "pinchtab_eval", args: map[string]any{"expression": "1", "zzz": true}, wantHint: `unknown argument "zzz";`},
} {
t.Run(tc.tool, func(t *testing.T) {
srv, paths := upstreamRecorder(t)
result := callTool(t, tc.tool, tc.args, srv)
if !result.IsError {
t.Fatalf("%v was accepted: %s", tc.args, resultText(t, result))
}
if message := resultText(t, result); !strings.Contains(message, tc.wantHint) {
t.Errorf("refusal %q, want it to contain %q", message, tc.wantHint)
}
if len(*paths) != 0 {
t.Errorf("a refused call still reached upstream: %v", *paths)
}
})
}
}
func TestWaitSendsTimeoutMsAndItsDeprecatedAliasAsTheWaitBudget(t *testing.T) {
for _, tc := range []struct {
name string
args map[string]any
want float64
}{
{name: "timeoutMs", args: map[string]any{"timeoutMs": float64(1500)}, want: 1500},
{name: "deprecated timeout", args: map[string]any{"timeout": float64(1200)}, want: 1200},
{name: "timeoutMs wins over timeout", args: map[string]any{"timeoutMs": float64(1500), "timeout": float64(9000)}, want: 1500},
} {
t.Run(tc.name, func(t *testing.T) {
srv, _ := upstreamRecorder(t)
args := map[string]any{"for": "selector", "value": "#nope"}
for name, value := range tc.args {
args[name] = value
}
result := callTool(t, "pinchtab_wait", args, srv)
if result.IsError {
t.Fatalf("%v was refused: %s", tc.args, resultText(t, result))
}
body, _ := resultJSON(t, result)["body"].(map[string]any)
if got := body["timeout"]; got != tc.want {
t.Errorf("posted timeout = %v, want %v (body %v)", got, tc.want, body)
}
})
}
}
func TestWaitDeclaresTimeoutAsADeprecatedAliasOfTimeoutMs(t *testing.T) {
var wait mcp.Tool
for _, tool := range allTools() {
if tool.Name == "pinchtab_wait" {
wait = tool
}
}
properties := wait.InputSchema.Properties
canonical, _ := properties["timeoutMs"].(map[string]any)
if canonical["type"] != "number" {
t.Fatalf("pinchtab_wait timeoutMs = %v, want a declared number", properties["timeoutMs"])
}
alias, _ := properties["timeout"].(map[string]any)
description, _ := alias["description"].(string)
if !strings.Contains(description, "deprecated") || !strings.Contains(description, "timeoutMs") {
t.Errorf("pinchtab_wait timeout description %q must mark it deprecated and point at timeoutMs", description)
}
}
func TestEverySelectorAliasStillTargetsEveryActionTool(t *testing.T) {
for _, tc := range actionToolTargets {
if _, declared := schemaPropertiesOnce()[tc.tool]["selector"]; !declared {
continue
}
for _, key := range selectorArgKeys {
t.Run(tc.tool+"/"+key, func(t *testing.T) {
srv, _ := upstreamRecorder(t)
result := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{key: "e5"}), srv)
if result.IsError {
t.Fatalf("%s {%q: \"e5\"} was refused: %s", tc.tool, key, resultText(t, result))
}
body, _ := resultJSON(t, result)["body"].(map[string]any)
if got := body["selector"]; got != "e5" {
t.Errorf("posted selector = %v, want e5 (body %v)", got, body)
}
})
}
}
}
var dynamicArgumentReads = map[string][]string{
"handleKeyboard": {"key", "text"},
}
type argumentRead struct {
key string
typed bool
fn string
}
type argumentReader struct {
keyIndex int
variadic bool
typed bool
}
type paramBinding struct {
param string
value string
}
type argumentReadCensus struct {
funcs map[string]*ast.FuncDecl
readers map[string]argumentReader
stringLists map[string][]string
boolSets map[string]map[string]bool
dynamicSites map[string]int
memo map[string][]argumentRead
}
var requestAccessorMethod = regexp.MustCompile(`^(Require|Get)(String|Int|Float|Bool)(Slice)?$`)
func newArgumentReadCensus(t *testing.T) *argumentReadCensus {
t.Helper()
census := &argumentReadCensus{
funcs: map[string]*ast.FuncDecl{},
readers: map[string]argumentReader{},
stringLists: map[string][]string{},
boolSets: map[string]map[string]bool{},
dynamicSites: map[string]int{},
memo: map[string][]argumentRead{},
}
entries, err := os.ReadDir(".")
if err != nil {
t.Fatal(err)
}
fset := token.NewFileSet()
for _, entry := range entries {
name := entry.Name()
if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
continue
}
file, err := parser.ParseFile(fset, name, nil, 0)
if err != nil {
t.Fatalf("cannot parse %s: %v", name, err)
}
for _, decl := range file.Decls {
switch d := decl.(type) {
case *ast.FuncDecl:
if d.Recv != nil || d.Body == nil {
continue
}
census.funcs[d.Name.Name] = d
if reader, ok := readerOf(d); ok {
census.readers[d.Name.Name] = reader
}
case *ast.GenDecl:
census.recordPackageVars(d)
}
}
}
if len(census.funcs) == 0 || len(census.readers) == 0 {
t.Fatal("no package functions or argument readers found, so this census checks nothing")
}
return census
}
func readerOf(fn *ast.FuncDecl) (argumentReader, bool) {
if !takesToolRequest(fn) {
return argumentReader{}, false
}
index := 0
for _, field := range fn.Type.Params.List {
for _, name := range field.Names {
if name.Name == "key" || name.Name == "keys" {
_, variadic := field.Type.(*ast.Ellipsis)
return argumentReader{keyIndex: index, variadic: variadic, typed: returnsTypedValue(fn)}, true
}
index++
}
}
return argumentReader{}, false
}
func takesToolRequest(fn *ast.FuncDecl) bool {
for _, field := range fn.Type.Params.List {
sel, ok := field.Type.(*ast.SelectorExpr)
if ok && sel.Sel.Name == "CallToolRequest" {
return true
}
}
return false
}
func returnsTypedValue(fn *ast.FuncDecl) bool {
if fn.Type.Results == nil || len(fn.Type.Results.List) == 0 {
return false
}
ident, ok := fn.Type.Results.List[0].Type.(*ast.Ident)
return ok && (ident.Name == "float64" || ident.Name == "int" || ident.Name == "bool")
}
func (c *argumentReadCensus) recordPackageVars(decl *ast.GenDecl) {
for _, spec := range decl.Specs {
value, ok := spec.(*ast.ValueSpec)
if !ok || len(value.Names) != len(value.Values) {
continue
}
for i, name := range value.Names {
literal, ok := value.Values[i].(*ast.CompositeLit)
if !ok {
continue
}
switch literal.Type.(type) {
case *ast.ArrayType:
if list, ok := stringLiterals(literal.Elts); ok {
c.stringLists[name.Name] = list
}
case *ast.MapType:
members := map[string]bool{}
for _, elt := range literal.Elts {
kv, ok := elt.(*ast.KeyValueExpr)
if !ok {
continue
}
key, keyOK := stringLiteral(kv.Key)
flag, flagOK := kv.Value.(*ast.Ident)
if keyOK && flagOK && flag.Name == "true" {
members[key] = true
}
}
c.boolSets[name.Name] = members
}
}
}
}
func stringLiteral(expr ast.Expr) (string, bool) {
lit, ok := expr.(*ast.BasicLit)
if !ok || lit.Kind != token.STRING {
return "", false
}
value, err := strconv.Unquote(lit.Value)
return value, err == nil
}
func stringLiterals(exprs []ast.Expr) ([]string, bool) {
values := make([]string, 0, len(exprs))
for _, expr := range exprs {
value, ok := stringLiteral(expr)
if !ok {
return nil, false
}
values = append(values, value)
}
return values, true
}
func (c *argumentReadCensus) keysAt(call *ast.CallExpr, reader argumentReader, rangeKeys map[string][]string) ([]string, bool) {
if reader.keyIndex >= len(call.Args) {
return nil, true
}
args := call.Args[reader.keyIndex : reader.keyIndex+1]
if reader.variadic {
args = call.Args[reader.keyIndex:]
}
if call.Ellipsis.IsValid() && len(args) == 1 {
ident, ok := args[0].(*ast.Ident)
if !ok {
return nil, false
}
list, ok := c.stringLists[ident.Name]
return list, ok
}
var keys []string
for _, arg := range args {
if literal, ok := stringLiteral(arg); ok {
keys = append(keys, literal)
continue
}
ident, ok := arg.(*ast.Ident)
if !ok || rangeKeys[ident.Name] == nil {
return nil, false
}
keys = append(keys, rangeKeys[ident.Name]...)
}
return keys, true
}
func literalRangeKeys(body *ast.BlockStmt) map[string][]string {
keys := map[string][]string{}
ast.Inspect(body, func(n ast.Node) bool {
loop, ok := n.(*ast.RangeStmt)
if !ok {
return true
}
literal, ok := loop.X.(*ast.CompositeLit)
if !ok {
return true
}
switch literal.Type.(type) {
case *ast.ArrayType:
ident, isIdent := loop.Value.(*ast.Ident)
values, allStrings := stringLiterals(literal.Elts)
if isIdent && allStrings {
keys[ident.Name] = values
}
case *ast.MapType:
ident, isIdent := loop.Key.(*ast.Ident)
if !isIdent {
return true
}
for _, elt := range literal.Elts {
if kv, ok := elt.(*ast.KeyValueExpr); ok {
if key, ok := stringLiteral(kv.Key); ok {
keys[ident.Name] = append(keys[ident.Name], key)
}
}
}
}
return true
})
return keys
}
func (c *argumentReadCensus) readsOf(fn string, binding *paramBinding, visiting map[string]bool) []argumentRead {
if binding == nil {
if cached, ok := c.memo[fn]; ok {
return cached
}
}
decl, ok := c.funcs[fn]
if !ok || visiting[fn] {
return nil
}
visiting[fn] = true
defer delete(visiting, fn)
_, isReader := c.readers[fn]
requestMaps := argumentMapIdents(decl.Body)
rangeKeys := literalRangeKeys(decl.Body)
var reads []argumentRead
callees := map[string]bool{}
record := func(keys []string, resolved, typed bool) {
if !resolved {
if !isReader {
c.dynamicSites[fn]++
}
return
}
for _, key := range keys {
reads = append(reads, argumentRead{key: key, typed: typed, fn: fn})
}
}
var visit func(ast.Node) bool
visit = func(n ast.Node) bool {
switch node := n.(type) {
case *ast.SwitchStmt:
if binding == nil || !isIdent(node.Tag, binding.param) {
return true
}
if node.Init != nil {
ast.Inspect(node.Init, visit)
}
for _, clause := range boundCaseClauses(node, binding.value) {
for _, stmt := range clause.Body {
ast.Inspect(stmt, visit)
}
}
return false
case *ast.IfStmt:
if binding == nil {
return true
}
if holds, known := c.evalCondition(node.Cond, binding); known && !holds {
if node.Init != nil {
ast.Inspect(node.Init, visit)
}
if node.Else != nil {
ast.Inspect(node.Else, visit)
}
return false
}
case *ast.CallExpr:
switch fun := node.Fun.(type) {
case *ast.Ident:
if reader, ok := c.readers[fun.Name]; ok {
keys, resolved := c.keysAt(node, reader, rangeKeys)
record(keys, resolved, reader.typed)
}
if _, ok := c.funcs[fun.Name]; ok {
callees[fun.Name] = true
}
case *ast.SelectorExpr:
if match := requestAccessorMethod.FindStringSubmatch(fun.Sel.Name); match != nil && len(node.Args) > 0 {
key, resolved := stringLiteral(node.Args[0])
record([]string{key}, resolved, match[2] != "String")
}
}
case *ast.IndexExpr:
if readsArgumentMap(node.X, requestMaps) {
key, resolved := stringLiteral(node.Index)
record([]string{key}, resolved, false)
}
}
return true
}
ast.Inspect(decl.Body, visit)
for callee := range callees {
reads = append(reads, c.readsOf(callee, nil, visiting)...)
}
for _, key := range dynamicArgumentReads[fn] {
reads = append(reads, argumentRead{key: key, fn: fn})
}
if binding == nil {
c.memo[fn] = reads
}
return reads
}
func boundCaseClauses(node *ast.SwitchStmt, value string) []*ast.CaseClause {
var fallback *ast.CaseClause
for _, stmt := range node.Body.List {
clause := stmt.(*ast.CaseClause)
if clause.List == nil {
fallback = clause
continue
}
for _, expr := range clause.List {
if literal, ok := stringLiteral(expr); ok && literal == value {
return []*ast.CaseClause{clause}
}
}
}
if fallback != nil {
return []*ast.CaseClause{fallback}
}
return nil
}
func (c *argumentReadCensus) evalCondition(expr ast.Expr, binding *paramBinding) (holds, known bool) {
switch cond := expr.(type) {
case *ast.ParenExpr:
return c.evalCondition(cond.X, binding)
case *ast.UnaryExpr:
if cond.Op == token.NOT {
holds, known := c.evalCondition(cond.X, binding)
return !holds, known
}
case *ast.BinaryExpr:
left, leftKnown := c.evalCondition(cond.X, binding)
right, rightKnown := c.evalCondition(cond.Y, binding)
switch cond.Op {
case token.LAND:
if (leftKnown && !left) || (rightKnown && !right) {
return false, true
}
return true, leftKnown && rightKnown
case token.LOR:
if (leftKnown && left) || (rightKnown && right) {
return true, true
}
return false, leftKnown && rightKnown
case token.EQL, token.NEQ:
literal, ok := stringLiteral(cond.Y)
if !ok || !isIdent(cond.X, binding.param) {
return false, false
}
return (literal == binding.value) == (cond.Op == token.EQL), true
}
case *ast.IndexExpr:
set, ok := cond.X.(*ast.Ident)
if !ok || !isIdent(cond.Index, binding.param) {
return false, false
}
members, ok := c.boolSets[set.Name]
if !ok {
return false, false
}
return members[binding.value], true
}
return false, false
}
func argumentMapIdents(body *ast.BlockStmt) map[string]bool {
idents := map[string]bool{}
ast.Inspect(body, func(n ast.Node) bool {
assign, ok := n.(*ast.AssignStmt)
if !ok || len(assign.Lhs) != len(assign.Rhs) {
return true
}
for i, rhs := range assign.Rhs {
if isGetArgumentsCall(rhs) {
if ident, ok := assign.Lhs[i].(*ast.Ident); ok {
idents[ident.Name] = true
}
}
}
return true
})
return idents
}
func isGetArgumentsCall(expr ast.Expr) bool {
call, ok := expr.(*ast.CallExpr)
if !ok {
return false
}
sel, ok := call.Fun.(*ast.SelectorExpr)
return ok && sel.Sel.Name == "GetArguments"
}
func readsArgumentMap(expr ast.Expr, requestMaps map[string]bool) bool {
if isGetArgumentsCall(expr) {
return true
}
ident, ok := expr.(*ast.Ident)
return ok && requestMaps[ident.Name]
}
func toolRegistrations(t *testing.T) map[string]*ast.CallExpr {
t.Helper()
file, err := parser.ParseFile(token.NewFileSet(), "handlers.go", nil, 0)
if err != nil {
t.Fatalf("cannot parse handlers.go: %v", err)
}
registrations := map[string]*ast.CallExpr{}
for _, decl := range file.Decls {
fn, ok := decl.(*ast.FuncDecl)
if !ok || fn.Name.Name != "rawHandlerMap" {
continue
}
ast.Inspect(fn.Body, func(n ast.Node) bool {
kv, ok := n.(*ast.KeyValueExpr)
if !ok {
return true
}
name, nameOK := stringLiteral(kv.Key)
call, callOK := kv.Value.(*ast.CallExpr)
if nameOK && callOK {
registrations[name] = call
}
return true
})
}
if len(registrations) == 0 {
t.Fatal("found no tool registrations in rawHandlerMap, so this census checks nothing")
}
return registrations
}
func (c *argumentReadCensus) bindingFor(call *ast.CallExpr) (string, *paramBinding) {
handler, ok := call.Fun.(*ast.Ident)
if !ok {
return "", nil
}
decl, ok := c.funcs[handler.Name]
if !ok {
return handler.Name, nil
}
index := 0
for _, field := range decl.Type.Params.List {
for _, name := range field.Names {
if index < len(call.Args) {
if value, ok := stringLiteral(call.Args[index]); ok {
return handler.Name, ¶mBinding{param: name.Name, value: value}
}
}
index++
}
}
return handler.Name, nil
}
func TestEveryArgumentAHandlerReadsIsDeclaredOnItsTool(t *testing.T) {
census := newArgumentReadCensus(t)
registrations := toolRegistrations(t)
properties := schemaPropertiesOnce()
total := 0
for tool, call := range registrations {
handler, binding := census.bindingFor(call)
reads := census.readsOf(handler, binding, map[string]bool{})
if len(reads) == 0 && len(properties[tool]) > 0 {
t.Errorf("%s declares %d arguments but the census found no read in %s; the walk no longer follows how this handler reads arguments", tool, len(properties[tool]), handler)
}
for _, read := range reads {
total++
kind, declared := properties[tool][read.key]
if !declared {
t.Errorf("%s reads %q (in %s) but the tool does not declare it, so the argument is refused before the handler can see it and is undiscoverable in tools/list", tool, read.key, read.fn)
continue
}
if read.typed && kind != "number" && kind != "integer" && kind != "boolean" {
t.Errorf("%s reads %q (in %s) with a typed accessor but declares it as %q, so validateTypedArgs cannot reject a malformed value", tool, read.key, read.fn, kind)
}
}
}
if total == 0 {
t.Fatal("no argument read found in any handler, so this census checks nothing")
}
for fn, count := range census.dynamicSites {
if _, recorded := dynamicArgumentReads[fn]; !recorded {
t.Errorf("%s reads %d argument(s) under a name the census cannot resolve; use a literal key or record the names it can take in dynamicArgumentReads", fn, count)
}
}
for fn := range dynamicArgumentReads {
if census.dynamicSites[fn] == 0 {
t.Errorf("dynamicArgumentReads records %s, which no longer reads an argument under a computed name; drop the entry", fn)
}
}
t.Logf("checked %d argument reads across %d tools", total, len(registrations))
}
func TestTheReadCensusAttributesSharedHandlerReadsToTheBoundTool(t *testing.T) {
census := newArgumentReadCensus(t)
registrations := toolRegistrations(t)
readsFor := func(tool string) map[string]bool {
handler, binding := census.bindingFor(registrations[tool])
keys := map[string]bool{}
for _, read := range census.readsOf(handler, binding, map[string]bool{}) {
keys[read.key] = true
}
return keys
}
for _, tc := range []struct {
tool string
reads []string
ignores []string
}{
{tool: "pinchtab_click", reads: []string{"x", "humanize", "onDialog", "element", "target", "snap", "browser"}, ignores: []string{"pixels", "option"}},
{tool: "pinchtab_type", reads: []string{"text", "value", "ref"}, ignores: []string{"x", "humanize", "snap"}},
{tool: "pinchtab_wait", reads: []string{"timeoutMs", "timeout", "for", "value", "state"}},
{tool: "pinchtab_key", reads: []string{"key", "text", "action"}},
} {
keys := readsFor(tc.tool)
for _, key := range tc.reads {
if !keys[key] {
t.Errorf("census finds no read of %q on %s (found %v); it has lost track of an argument idiom", key, tc.tool, keys)
}
}
for _, key := range tc.ignores {
if keys[key] {
t.Errorf("census attributes %q to %s, whose kind never reads it; the shared-handler narrowing is broken", key, tc.tool)
}
}
}
}