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.

Additional exports from /testing: createMockSession() binds a mock handler context to an HTTP session; createFetchMock() provides a strict upstream HTTP fake; runToolContract() executes a definition through schema, handler, formatting, enrichment/content, and production-shaped error-envelope checks. createMockLogger() returns a standalone MockContextLogger, createInMemoryStorage(options?) provides a real StorageService backed by InMemoryProvider, and expectInputRequired(run) returns the input_required result a multi-round-trip handler asked for (see Mock inputs).

Other testing subpaths: /testing/vitest (fixtures and conformance suites, below), /testing/fuzz (see Fuzz testing), and /testing/apps, whose renderAppTool renders an app tool's ui:// view against your server (a stdio command or an HTTP URL) in a headless MCP Apps host and reports initialization, errors, CSP violations, the view↔host messages, and screenshots. It needs the optional peers @modelcontextprotocol/client and @modelcontextprotocol/ext-apps plus a chrome-headless-shell build; the field-test skill covers installing one and reading the report.

Philosophy: Test behavior, not implementation. Refactors should not break tests. Match the repo's existing test layout: fresh scaffolds use tests/, while colocated src/**/*.test.ts files are also supported. Integration tests at I/O boundaries over unit tests of internals.

mcpTest — fixture-based Vitest test

mcpTest is a test.extend-based Vitest test that provides ctx, session, fetchMock, and storage as per-test fixtures — fresh instances for every test, eliminating boilerplate and enforcing isolation automatically. fetchMock is installed as globalThis.fetch only when requested by a test and restored afterward.

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

mcpTest('echoes the message', async ({ ctx }) => {
  const result = await echoTool.handler(echoTool.input.parse({ message: 'hi' }), ctx);
  expect(result.message).toBe('hi');
});

mcpTest('uses storage fixture', async ({ ctx, storage }) => {
  const svc = new MyService(config, storage);
  const result = await svc.doWork(ctx);
  expect(result).toBeDefined();
});

mcpTest('stubs an upstream HTTP boundary', async ({ fetchMock }) => {
  fetchMock.route({
    match: 'https://api.example.test/items/42',
    respond: Response.json({ id: '42' }),
  });
  await expect(loadItem('42')).resolves.toMatchObject({ id: '42' });
});

Fixtures

Extending with the function form

Override fixtures using the function form (async ({}, use) => { ... }) to preserve per-test freshness. A bare-value override shares one mutable instance across the entire file — defeating the fixture's isolation guarantee.

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

// Correct — function form gives each test a fresh context:
const tenantTest = mcpTest.extend({
  ctx: async ({}, use) => { await use(createMockContext({ tenantId: 'test-tenant' })); },
});

// Wrong — bare value shares one ctx across every test in the file:
// const tenantTest = mcpTest.extend({ ctx: createMockContext({ tenantId: 'test-tenant' }) });

The portable /testing helpers are re-exported from @cyanheads/mcp-ts-core/testing/vitest so fixture overrides don't need a second import.

Upstream HTTP testing with createFetchMock

Use the fetch harness at real outbound I/O boundaries. Stub the external service, not server-owned services or handlers.

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

const http = createFetchMock([
  {
    method: 'GET',
    match: 'https://api.example.test/items/42',
    respond: Response.json({ id: '42', name: 'Example' }),
  },
]);

http.install();
try {
  await expect(loadItem('42')).resolves.toEqual({ id: '42', name: 'Example' });
  expect(http.calls[0]?.request.url).toBe('https://api.example.test/items/42');
} finally {
  http.restore();
}

Routes match in registration order. match accepts an exact URL, RegExp, or request predicate; respond accepts a static Response or a response factory. A static response's body is read once, on the route's first match, and every call is served a fresh Response over those bytes with the same status, statusText, and headers — so a consumer that cancels the body, or an error-body reader like httpErrorFromResponse that stops past its cap, settles on Node as on Bun. Set once: true for one-shot behavior. Unmatched requests throw unless onUnhandled is provided.

A request predicate routes on the URL's origin, never a prefix. req.url.startsWith(BASE_URL) also matches a lookalike host (https://api.example.test.evil.com/...), which CodeQL reports as high-severity incomplete URL substring sanitization — it scans test files as readily as src/, so a suite that is green locally still fails the security check on a pull request. Parse the URL and compare origins, matching the path separately:

match: (req) => {
  const url = new URL(req.url);
  return url.origin === new URL(BASE_URL).origin && url.pathname.startsWith('/items/');
},

Tool conformance with toolContractSuite

Point the reusable suite at a definition plus representative success and failure inputs. It checks input/output schemas, invokes the real handler, applies formatting/enrichment/content, and validates both public error surfaces.

import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
import { toolContractSuite } from '@cyanheads/mcp-ts-core/testing/vitest';

toolContractSuite(searchTool, {
  success: [{ name: 'returns matches', input: { query: 'mcp' } }],
  errors: [{
    name: 'reports an empty query',
    input: { query: '' },
    code: JsonRpcErrorCode.InvalidParams,
    reason: 'empty_query',
  }],
});

Use runToolContract(definition, input, { context }) from /testing when a custom test runner or an imperative assertion is a better fit. It intentionally skips transport auth and telemetry; those belong in transport/integration tests.

A declared reason thrown without a hint — a bare ctx.fail('reason') or a service throw carrying { reason } — comes back with the entry's recovery as data.recovery.hint and a Recovery: line in content[], as in production. The one production field it leaves out is data.requestId (and the request <id> term closing content[]), since there is no real request; a test asserting the factory's envelope instead expects both. Calling definition.handler(...) directly returns the McpError exactly as the throw site built it — no fill, no request id.

Arguments that fail the input schema are rejected the way the production handler factory rejects them: InvalidParams (-32602), with a message naming the tool and every failing field. That is the code a client sees on the wire, so assert it — not ValidationError (-32007), which stays the classification for a ZodError a handler throws itself. A result that breaks the tool's own output or enrichment schema is the definition's bug, so it returns InternalError (-32603) with a message naming that contract, exactly as in production.

Cancellation settles as it does in production. Pass context: { signal } and abort it: once the signal has fired, whatever the handler — or the output validation, format(), and enrichment after it — throws comes back as RequestCancelled (-32011), whether that is the signal's AbortError, its reason string, a withRetry backoff that stopped, or an McpError of the handler's own. A throw while the signal is still live keeps its own classification, and argument parsing stays outside the settle, so schema-invalid arguments on an aborted signal still return InvalidParams. A toolContractSuite error case with an aborted context.signal asserts code: JsonRpcErrorCode.RequestCancelled the same way.

Resources have no contract runner. A resource definition's handler(...) called directly returns the throw site's McpError with no recovery fill, so asserting a resource's declared errors[] hints needs a path through the resource factory. Serve the definition from createWorkerHandler({ name, title, resources: [def] }) (/worker) and fetch it a resources/read JSON-RPC request carrying the current protocol revision in both the MCP-Protocol-Version header and params._meta. The response is plain JSON or an SSE data: frame, and its error carries code, data.reason, and the filled data.recovery.hint.

createMockContext options

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

createMockContext()                                           // working ctx.state on tenant 'default'
createMockContext({ tenantId: 'test-tenant' })               // explicit tenant scope for ctx.state
createMockContext({ errors: myTool.errors })                 // attaches typed ctx.fail keyed by the contract reasons
createMockContext({ inputResponses: { confirm: { action: 'accept', content: { ok: true } } } }) // second round of a multi-round-trip handler
createMockContext({ requestState: 'opaque-state' })          // seeds ctx.inputs.state()
createMockContext({ clientCapabilities: { roots: {} } })     // seeds ctx.clientCapabilities and filters inputResponses to declared kinds
createMockContext({ requestId: 'my-id' })                    // override request ID (default: 'test-request-id')
createMockContext({ notifyResourceListChanged: () => {} })   // with resource-list change notifier
createMockContext({ notifyResourceUpdated: (_uri) => {} })   // with resource update notifier
createMockContext({ signal: controller.signal })             // custom AbortSignal
createMockContext({ auth: { clientId: 'test', scopes: [], sub: 'test-user' } }) // with auth context
createMockContext({ uri: new URL('myscheme://item/123') })   // for resource handler testing

MockContextOptions interface:

interface MockContextOptions<TErrors extends readonly ErrorContract[] | undefined> {
  auth?: AuthContext;
  clientCapabilities?: ClientCapabilities;
  errors?: TErrors | undefined;
  inputResponses?: InputResponses | Record<string, unknown>;
  notifyPromptListChanged?: () => void;
  notifyResourceListChanged?: () => void;
  notifyResourceUpdated?: (uri: string) => void;
  notifyToolListChanged?: () => void;
  requestId?: string;
  requestState?: unknown;
  sessionId?: string;
  signal?: AbortSignal;
  tenantId?: string;
  uri?: URL;
}

Mock state

ctx.state is a real StorageService over an InMemoryProvider — the production storage path, not a Map. A test therefore sees the same rules a deployed server enforces:

• Keys match ^[a-zA-Z0-9_.\-/]+$ and may not contain ... Colons are rejected, so cache:v1:abc throws McpError(ValidationError) in the test exactly as it would in a deployment; use cache/v1/abc.
• Values round-trip as JSON, as on every persistent provider. A read returns a fresh object in its JSON form — a Date reads back as its ISO string — so a test cannot pass on identity or on a Date/Map surviving storage. A value JSON cannot encode (bigint, a cyclic reference, a top-level undefined, function, or symbol) rejects with McpError(SerializationError).
• TTL is honored. An entry written with { ttl: 30 } reads back as null once 30 seconds elapse — drive the clock with vi.useFakeTimers() to assert expiry.
• getMany / setMany / deleteMany / list validate every key and prefix, and list paginates with the same opaque cursors.
• Cancellation applies: once ctx.signal aborts, state operations reject.

const ctx = createMockContext();

await ctx.state.set('cache/v1/abc', { hits: 1 }, { ttl: 30 });
await expect(ctx.state.get('cache/v1/abc')).resolves.toEqual({ hits: 1 });
await expect(ctx.state.set('cache:v1:abc', {})).rejects.toThrow(McpError);

await ctx.state.set('seen/abc', { at: new Date('2026-01-01T00:00:00Z') });
await expect(ctx.state.get('seen/abc')).resolves.toEqual({ at: '2026-01-01T00:00:00.000Z' });

Reach for createInMemoryStorage() when a service takes a StorageService directly — it builds the same pair.

Mock inputs

ctx.requestInput is the real implementation: it throws an InputRequiredSignal the production handler factories convert into an input_required result. In a unit test the handler is called directly, so that signal surfaces as a thrown value — which is exactly how you assert the first round. The examples below drive export_report from api-context § The shape of a multi-round-trip handler, which asks for a format the caller left out:

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

it('asks for the format on the first round', async () => {
  const ctx = createMockContext();
  await expect(exportReport.handler(exportReport.input.parse({ reportId: 'r1' }), ctx))
    .rejects.toSatisfy(isInputRequiredSignal);
});

To assert on what was requested, use expectInputRequired from /testing. It runs the handler and returns the input_required result the handler factory would have returned; it throws when the handler returns normally, and any other error propagates untouched:

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

const asked = await expectInputRequired(() => exportReport.handler(input, createMockContext()));
expect(asked.inputRequests?.format?.method).toBe('elicitation/create');

Pass asked.requestState back as createMockContext({ requestState }) when the handler reads state from the prior round. inputResponses drives the second round. ctx.inputs.accepted(key, schema) and .view(key) read it with the same helpers production uses, so a wrong response shape fails in the test:

it('exports in the format the user picked', async () => {
  const ctx = createMockContext({
    inputResponses: { format: { action: 'accept', content: { format: 'csv' } } },
  });
  await expect(exportReport.handler(input, ctx)).resolves.toMatchObject({ url: expect.any(String) });
});

it('stops when the user declines', async () => {
  const ctx = createMockContext({
    inputResponses: { format: { action: 'decline' } },
  });
  await expect(exportReport.handler(input, ctx)).rejects.toThrow(McpError);
});

Seeding an answer this way is right for a handler that treats it as input. A consent gate does not: it acts only on a record it stored when it asked, so an answer seeded alone makes it ask again — see below.

ctx.inputs.dropped is always [] on a mock context — the drop only happens in the SDK's wire decoding, so cover it in an integration test rather than a unit one.

Seed clientCapabilities to test what a client without a capability gets: a pre-answered inputResponses the declared capabilities do not cover — a kind never declared, a form answer (one carrying content) from a client that declared only elicitation.url, a tool-use sampling answer without sampling.tools — never reaches ctx.inputs, so the handler asks again. A handler that falls through when a capability is missing (if (ctx.clientCapabilities?.roots) … else …) is tested by seeding both shapes.

A consent gate that redeems a ctx.state record (see api-context § Consent gates) needs the record in the second round's storage, and each mock context has its own. Copy what round one stored into the round-two context. The record carries the caller, so seed the same auth (or none) on both:

const accept = { confirm: { action: 'accept', content: { confirm: true } } };

const first = createMockContext();
const asked = await expectInputRequired(() => deletePath.handler(input, first));
const record = await first.state.get(`consent/${asked.requestState}`);

const second = createMockContext({ inputResponses: accept, requestState: asked.requestState });
await second.state.set(`consent/${asked.requestState}`, record);
await expect(deletePath.handler(input, second)).resolves.toEqual({ deleted: input.path });

// The record is spent: the same state again asks for a fresh confirmation.
await expect(deletePath.handler(input, second)).rejects.toSatisfy(isInputRequiredSignal);

// An answer with no record behind it asks as well — nothing was asked, so nothing was confirmed.
const unasked = createMockContext({ inputResponses: accept });
await expect(deletePath.handler(input, unasked)).rejects.toSatisfy(isInputRequiredSignal);

A record the round-two context holds under another auth, or one written by another tool (its operation differs), asks again the same way — cover whichever of those the handler's binding is meant to catch.