api-testing

Overview

Tests target handler behavior directly — call handler(input, ctx), assert on the return value or thrown error. The framework's handler factory (try/catch, formatting, telemetry) is not involved. Use createMockContext from @cyanheads/mcp-ts-core/testing to construct the ctx argument.

Philosophy: Test behavior, not implementation. Refactors should not break tests. Colocate test files with source (foo.tool.ts → foo.tool.test.ts). Integration tests at I/O boundaries over unit tests of internals.

---

createMockContext options

import { createMockContext } from '@cyanheads/mcp-ts-core/testing';

createMockContext()                                           // minimal — ctx.state operations throw without tenantId
createMockContext({ tenantId: 'test-tenant' })               // enables ctx.state (tenant-scoped in-memory storage)
createMockContext({ sample: vi.fn().mockResolvedValue(...) }) // with MCP sampling
createMockContext({ elicit: vi.fn().mockResolvedValue(...) }) // with elicitation
createMockContext({ progress: true })                        // with task progress (ctx.progress populated)
createMockContext({ requestId: 'my-id' })                    // override request ID (default: 'test-request-id')
createMockContext({ signal: controller.signal })             // custom AbortSignal
createMockContext({ auth: { clientId: 'test', scopes: [] } }) // with auth context
createMockContext({ uri: new URL('myscheme://item/123') })   // for resource handler testing

MockContextOptions interface:

interface MockContextOptions {
  auth?: AuthContext;
  elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
  progress?: boolean;
  requestId?: string;
  sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
  signal?: AbortSignal;
  tenantId?: string;
  uri?: URL;
}

Option	Effect
(none)	Minimal context — ctx.state operations throw without tenantId; ctx.elicit/ctx.sample/ctx.progress are undefined
auth	Sets ctx.auth for scope-checking tests
elicit	Assigns a function to ctx.elicit for testing elicitation calls
progress	Populates ctx.progress with real state-tracking implementation (see below)
requestId	Overrides ctx.requestId (default: 'test-request-id')
sample	Assigns a function to ctx.sample for testing sampling calls
signal	Overrides ctx.signal — useful for cancellation testing
tenantId	Sets ctx.tenantId and enables ctx.state operations with in-memory storage
uri	Sets ctx.uri for resource handler testing