testharness

type BenchHarness struct {
	// contains filtered or unexported fields
}

type FakeClockify struct {
	// contains filtered or unexported fields
}

type InvokeOpts struct {
	// Tool is the MCP tool name (e.g. "clockify_delete_entry"). Required.
	Tool string
	// Args is the tools/call arguments map. Nil means an empty args object.
	Args map[string]any
	// PolicyMode defaults to policy.Standard. Set to policy.ReadOnly or
	// policy.SafeCore to assert that write tools are rejected before the
	// handler runs.
	PolicyMode policy.Mode
	// DeniedTools is an optional per-call override for the policy deny list.
	// Lets a single test assert that an explicitly-denied tool is rejected
	// under an otherwise-permissive mode.
	DeniedTools []string
	// Principal is attached to the call context via authn.WithPrincipal.
	// Nil means no principal (rate-limit falls back to the global scope);
	// set this to simulate per-subject rate limiting or auth failures that
	// still flow through the dispatcher.
	Principal *authn.Principal
	// Upstream is the fake Clockify server the tool's HTTP client talks to.
	// Required — the harness panics if nil, because there's nothing sensible
	// to default here.
	Upstream *FakeClockify
	// ClockifyAPIKey is the bearer key the clockify client sends upstream.
	// Defaults to "test-api-key". The fake upstream decides whether to
	// reject it — tests that want to assert upstream auth errors provide a
	// handler that returns 401 for mismatched keys.
	ClockifyAPIKey string
	// WorkspaceID is written into tools.Service.WorkspaceID. Defaults to
	// "test-workspace".
	WorkspaceID string
	// RequestID is the JSON-RPC request id. Defaults to 1; set this when a
	// test needs to correlate multiple invocations in the same log stream.
	RequestID int
	// Client lets callers supply a pre-built clockify.Client whose HTTP
	// transport is reused across many Invoke calls. Default behaviour is
	// "construct a fresh client per call" (correct for tests where each
	// case must be independent). Benchmarks pass a shared client so they
	// don't burn an ephemeral port per iteration — without this the
	// loopback exhausts its port range after a few thousand calls.
	Client *clockify.Client
	// ActivateTier2Groups is the list of Tier-2 group names to register
	// on the server via Server.ActivateGroup after initialize. Only
	// honoured by NewBenchHarness; Invoke ignores this field because its
	// fresh-per-call server doesn't need lazy activation for unit tests.
	// Use this when a benchmark dispatches a Tier-2 tool (expenses,
	// invoices, approvals, custom_fields, scheduling, ...). A group name
	// that doesn't exist in Tier2Groups causes the harness to Fatal.
	ActivateTier2Groups []string
}

type InvokeResult struct {
	// Result is the decoded tools/call result envelope. For a successful
	// call this is `{"content":[{"type":"text","text":"<json>"}]}`; tests
	// that need the tool-specific shape should decode the "text" field.
	// Nil when the call failed at the JSON-RPC protocol layer (-32xxx).
	Result map[string]any
	// ResultText is the JSON text returned inside Result.content[0].text
	// when the call succeeded. Tests that want to assert on the concrete
	// tool response shape typically json.Unmarshal this. Empty string when
	// the call errored.
	ResultText string
	// IsError is the MCP spec's tool-error flag on the result envelope.
	// True when the tool handler (or the enforcement pipeline) returned an
	// error without triggering a JSON-RPC -32xxx protocol error. Policy
	// denials, handler errors, and upstream 4xx/5xx all surface here.
	IsError bool
	// ErrorMessage is the human-readable error string extracted from either
	// the JSON-RPC error envelope or the isError:true content block. Empty
	// on success.
	ErrorMessage string
	// RPCError is the JSON-RPC protocol error (schema validation -32602,
	// uninitialized server -32002, etc.) or nil when the call went through.
	// Tool errors come back as IsError:true on the result envelope, NOT as
	// a JSON-RPC error.
	RPCError *mcp.RPCError
	// Outcome classifies the call result for assertion. See the Outcome*
	// constants below.
	Outcome Outcome
	// UpstreamHit reports whether any HTTP request reached the fake
	// Clockify server during this call. False when the enforcement pipeline
	// rejected the call (policy, rate limit, schema validation) before the
	// handler had a chance to run.
	UpstreamHit bool
	// Raw is the full JSON-RPC response bytes in case a test needs more
	// detail than the structured fields expose.
	Raw []byte
}

type Outcome string