> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Complete API reference for @frontmcp/testing Complete API documentation for all `@frontmcp/testing` exports, types, and methods. *** ## Test Function ### test The main test function with fixture injection. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} import { test } from '@frontmcp/testing'; test('description', async ({ mcp, auth, server }) => { // Test implementation }); // Describe blocks test.describe('group name', () => { test('test 1', async ({ mcp }) => {}); test('test 2', async ({ mcp }) => {}); }); // Skip tests test.skip('skipped test', async ({ mcp }) => {}); // Only run this test test.only('focused test', async ({ mcp }) => {}); ``` ### test.use Configure fixtures for a test file. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} test.use(options: TestOptions): void ``` | Option | Type | Default | Description | | ---------------- | ---------------------------------------- | ------------------- | ------------------------------------ | | `server` | `string` | — | Path to server entry file (required) | | `port` | `number` | Auto | Port to run server on | | `transport` | `'sse' \| 'streamable-http'` | `'streamable-http'` | Transport protocol | | `auth` | `AuthOptions` | — | Authentication configuration | | `logLevel` | `'debug' \| 'info' \| 'warn' \| 'error'` | `'warn'` | Server log level | | `env` | `Record` | — | Environment variables | | `startupTimeout` | `number` | `30000` | Startup timeout in ms | | `baseUrl` | `string` | — | Connect to existing server | *** ## McpTestClient The primary fixture for testing MCP servers. ### Tools API #### tools.list List all available tools. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.tools.list(): Promise ``` **Returns:** Array of tool definitions with `name`, `description`, and `inputSchema`. #### tools.call Call a tool with arguments. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.tools.call(name: string, args: Record): Promise ``` | Parameter | Type | Description | | --------- | ------------------------- | -------------- | | `name` | `string` | Tool name | | `args` | `Record` | Tool arguments | **Returns:** `ToolResult` with methods: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface ToolResult { // Status checks isSuccess: boolean; isError: boolean; // Content accessors text(): string; // Get text content json(): T; // Parse JSON content image(): { data: string; mimeType: string }; // Raw access raw: CallToolResult; // Raw MCP response content: Content[]; // Content array // Error info (if isError) error?: { code: number; message: string }; } ``` *** ### Resources API #### resources.list List static resources. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.resources.list(): Promise ``` **Returns:** Array of resources with `uri`, `name`, `description`, and `mimeType`. #### resources.listTemplates List resource templates. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.resources.listTemplates(): Promise ``` **Returns:** Array of templates with `uriTemplate`, `name`, and `description`. #### resources.read Read a resource by URI. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.resources.read(uri: string): Promise ``` **Returns:** `ResourceContent` with methods: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface ResourceContent { text(): string; // Get text content json(): T; // Parse JSON content blob(): Uint8Array; // Get binary content mimeType: string; // Content MIME type uri: string; // Resource URI raw: ReadResourceResult; // Raw MCP response } ``` *** ### Prompts API #### prompts.list List available prompts. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.prompts.list(): Promise ``` **Returns:** Array of prompts with `name`, `description`, and `arguments`. #### prompts.get Get a prompt with arguments. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.prompts.get(name: string, args?: Record): Promise ``` **Returns:** `PromptResult` with: ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface PromptResult { messages: PromptMessage[]; // Array of messages description?: string; // Optional description } interface PromptMessage { role: 'user' | 'assistant'; content: TextContent | ImageContent | EmbeddedResource; } ``` *** ### Session & Connection #### isConnected Check connection status. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.isConnected(): boolean ``` #### sessionId Get the current session ID. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.sessionId: string | undefined ``` #### serverInfo Get server information. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.serverInfo: { name: string; version: string; } ``` #### protocolVersion Get the MCP protocol version. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.protocolVersion: string ``` #### capabilities Get server capabilities. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.capabilities: ServerCapabilities ``` #### hasCapability Check for a specific capability. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.hasCapability(name: 'tools' | 'resources' | 'prompts'): boolean ``` #### authenticate Authenticate the client with a JWT token. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.authenticate(token: string): Promise ``` #### disconnect Disconnect from the server. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.disconnect(): Promise ``` *** ### Raw Protocol API #### raw\.request Send a raw JSON-RPC request. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.raw.request(request: JsonRpcRequest): Promise ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface JsonRpcRequest { jsonrpc: '2.0'; id: number | string; method: string; params?: unknown; } interface JsonRpcResponse { jsonrpc: '2.0'; id: number | string; result?: unknown; error?: { code: number; message: string; data?: unknown }; } ``` #### raw\.notify Send a JSON-RPC notification (no response expected). ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.raw.notify(notification: JsonRpcNotification): Promise ``` #### raw\.sendRaw Send raw string data (for testing parse errors). ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.raw.sendRaw(data: string): Promise ``` *** ### Logging & Tracing #### logs.all Get all captured logs. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.logs.all(): LogEntry[] ``` #### logs.filter Filter logs by level. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.logs.filter(level: 'debug' | 'info' | 'warn' | 'error'): LogEntry[] ``` #### logs.search Search logs by text. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.logs.search(query: string): LogEntry[] ``` #### logs.clear Clear captured logs. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.logs.clear(): void ``` #### trace.all Get all request traces. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.trace.all(): RequestTrace[] ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface RequestTrace { method: string; params: unknown; response: unknown; durationMs: number; timestamp: Date; } ``` #### trace.last Get the last request trace. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.trace.last(): RequestTrace | undefined ``` #### trace.clear Clear request traces. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.trace.clear(): void ``` *** ## Auth Fixture The `auth` fixture generates JWT tokens for authentication testing. ### createToken Create a valid JWT token. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} auth.createToken(options: TokenOptions): Promise ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface TokenOptions { sub: string; // Subject (required) scopes?: string[]; // OAuth scopes email?: string; // Email claim name?: string; // Name claim claims?: Record; // Custom claims expiresIn?: number; // Lifetime in seconds (default: 3600) } ``` ### createExpiredToken Create an expired token for testing expiration handling. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} auth.createExpiredToken(options: Omit): Promise ``` ### createInvalidToken Create a token with an invalid signature. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} auth.createInvalidToken(options: TokenOptions): string ``` ### users Pre-built test user configurations. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} auth.users: { admin: { sub: 'test-admin', scopes: ['*'] }; user: { sub: 'test-user', scopes: ['read', 'write'] }; readOnly: { sub: 'test-readonly', scopes: ['read'] }; } ``` ### getJwks Get the public JWKS for token verification. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} auth.getJwks(): Promise ``` ### getIssuer Get the token issuer. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} auth.getIssuer(): string ``` ### getAudience Get the token audience. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} auth.getAudience(): string ``` *** ## Server Fixture The `server` fixture provides server control. ### info Server information. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} server.info: { baseUrl: string; port: number; pid: number; } ``` ### createClient Create an additional MCP client. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} server.createClient(options?: ClientOptions): Promise ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface ClientOptions { transport?: 'sse' | 'streamable-http'; token?: string; } ``` ### restart Restart the server. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} server.restart(): Promise ``` ### getLogs Get server-side logs. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} server.getLogs(): string[] ``` ### clearLogs Clear server logs. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} server.clearLogs(): void ``` *** ## Mock Registry The `mcp.mock` API for mocking MCP responses. ### mock.add Add a mock definition. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.mock.add(options: MockOptions): MockHandle ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface MockOptions { method: string; // MCP method to match params?: Record; // Parameters to match (partial) response: JsonRpcResponse; // Response to return times?: number; // Match count (default: unlimited) delay?: number; // Response delay in ms } interface MockHandle { callCount(): number; calls(): MockCall[]; remove(): void; } ``` ### mock.tool Convenience method for mocking tool responses. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.mock.tool(name: string, response: unknown): MockHandle ``` ### mock.toolError Mock a tool error. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.mock.toolError(name: string, code: number, message: string): MockHandle ``` ### mock.resource Mock a resource response. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.mock.resource(uri: string, content: string | ResourceContent): MockHandle ``` ### mock.clear Clear all mocks. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.mock.clear(): void ``` *** ## Request Interceptors The `mcp.intercept` API for intercepting requests and responses. ### intercept.request Intercept outgoing requests. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.intercept.request(handler: RequestInterceptor): () => void ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} type RequestInterceptor = (ctx: RequestContext) => InterceptAction; interface RequestContext { request: JsonRpcRequest; meta: { sessionId?: string }; } type InterceptAction = | { action: 'passthrough' } | { action: 'modify'; request: JsonRpcRequest } | { action: 'mock'; response: JsonRpcResponse } | { action: 'error'; error: Error }; ``` **Returns:** Function to remove the interceptor. ### intercept.response Intercept incoming responses. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.intercept.response(handler: ResponseInterceptor): () => void ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} type ResponseInterceptor = (ctx: ResponseContext) => ResponseAction; interface ResponseContext { request: JsonRpcRequest; response: JsonRpcResponse; durationMs: number; } type ResponseAction = | { action: 'passthrough' } | { action: 'modify'; response: JsonRpcResponse }; ``` ### intercept.delay Add delay to all requests. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.intercept.delay(ms: number): () => void ``` **Returns:** Function to remove the delay. ### intercept.failMethod Fail requests to a specific method. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} mcp.intercept.failMethod(method: string, message: string): () => void ``` **Returns:** Function to remove the failure. *** ## HTTP Mock API The `httpMock` module for mocking external HTTP requests. ### httpMock.interceptor Create an HTTP interceptor. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} import { httpMock } from '@frontmcp/testing'; const interceptor = httpMock.interceptor(); ``` ### Interceptor Methods #### get, post, put, delete Create method-specific mocks. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interceptor.get(url: UrlMatcher, response: unknown, options?: MockOptions): MockHandle interceptor.post(url: UrlMatcher, response: unknown, options?: MockOptions): MockHandle interceptor.put(url: UrlMatcher, response: unknown, options?: MockOptions): MockHandle interceptor.delete(url: UrlMatcher, response: unknown, options?: MockOptions): MockHandle ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} type UrlMatcher = string | RegExp | ((url: string) => boolean); ``` #### any Match any HTTP method. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interceptor.any(url: UrlMatcher, response: unknown, options?: MockOptions): MockHandle ``` #### mock Full mock definition. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interceptor.mock(options: HttpMockOptions): MockHandle ``` ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface HttpMockOptions { match: { url: UrlMatcher; method?: string | string[]; headers?: Record; body?: unknown | ((body: unknown) => boolean); }; response: HttpResponse; times?: number; } interface HttpResponse { status?: number; statusText?: string; headers?: Record; body?: unknown; delay?: number; } ``` #### allowPassthrough Allow unmatched requests to reach the network. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interceptor.allowPassthrough(enabled: boolean): void ``` #### assertDone Assert all one-time mocks were used. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interceptor.assertDone(): void ``` #### pending Get unused mocks. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interceptor.pending(): HttpMockOptions[] ``` #### restore Restore original fetch function. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interceptor.restore(): void ``` ### MockHandle Returned by mock methods. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} interface MockHandle { callCount(): number; calls(): HttpCall[]; waitForCalls(count: number, timeout?: number): Promise; } interface HttpCall { url: string; method: string; headers: Record; body?: unknown; } ``` *** ## Response Helpers ### httpResponse Pre-built HTTP response creators. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} import { httpResponse } from '@frontmcp/testing'; httpResponse.json(data: unknown): HttpResponse httpResponse.text(text: string): HttpResponse httpResponse.html(html: string): HttpResponse httpResponse.notFound(): HttpResponse httpResponse.unauthorized(): HttpResponse httpResponse.forbidden(): HttpResponse httpResponse.serverError(message?: string): HttpResponse httpResponse.error(status: number, message: string): HttpResponse httpResponse.delayed(data: unknown, ms: number): HttpResponse ``` ### mockResponse Pre-built MCP response creators. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} import { mockResponse } from '@frontmcp/testing'; mockResponse.success(result: unknown): JsonRpcResponse mockResponse.toolResult(content: Content[]): JsonRpcResponse mockResponse.toolsList(tools: Tool[]): JsonRpcResponse mockResponse.resourcesList(resources: Resource[]): JsonRpcResponse mockResponse.resourceRead(contents: ResourceContent[]): JsonRpcResponse mockResponse.error(code: number, message: string): JsonRpcResponse // Error shortcuts mockResponse.errors.methodNotFound(method: string): JsonRpcResponse mockResponse.errors.resourceNotFound(uri: string): JsonRpcResponse mockResponse.errors.invalidParams(message: string): JsonRpcResponse mockResponse.errors.unauthorized(): JsonRpcResponse ``` *** ## Custom Matchers All custom Jest matchers added by `@frontmcp/testing`. ### Tool Matchers ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} expect(tools).toContainTool(name: string): void ``` ### Result Matchers ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} expect(result).toBeSuccessful(): void expect(result).toBeError(code?: number): void ``` ### Content Matchers ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} expect(result).toHaveTextContent(text?: string): void expect(result).toHaveImageContent(): void expect(result).toHaveResourceContent(): void expect(content).toHaveMimeType(mimeType: string): void ``` ### Resource Matchers ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} expect(resources).toContainResource(uri: string): void expect(templates).toContainResourceTemplate(uriTemplate: string): void ``` ### Prompt Matchers ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} expect(prompts).toContainPrompt(name: string): void expect(result).toHaveMessages(count: number): void expect(message).toHaveRole(role: 'user' | 'assistant'): void expect(message).toContainText(text: string): void ``` ### JSON-RPC Matchers ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} expect(response).toBeValidJsonRpc(): void expect(response).toHaveResult(): void expect(response).toHaveError(): void expect(response).toHaveErrorCode(code: number): void ``` *** ## Error Codes Common MCP error codes for use in tests. | Code | Name | Description | | -------- | ------------------ | -------------------------- | | `-32700` | Parse error | Invalid JSON | | `-32600` | Invalid request | Invalid JSON-RPC structure | | `-32601` | Method not found | Unknown method | | `-32602` | Invalid params | Invalid parameters | | `-32603` | Internal error | Server error | | `-32001` | Unauthorized | Authentication required | | `-32002` | Resource not found | Resource doesn't exist | | `-32800` | Request cancelled | Request was cancelled | *** ## Type Exports All types are exported for TypeScript usage. ```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} import type { // Test types TestOptions, TestFixtures, // Client types McpTestClient, ToolResult, ResourceContent, PromptResult, // Auth types AuthFixture, TokenOptions, // Server types ServerFixture, ClientOptions, // Mock types MockOptions, MockHandle, HttpMockOptions, HttpResponse, // Interceptor types RequestInterceptor, ResponseInterceptor, InterceptAction, ResponseAction, } from '@frontmcp/testing'; ```