API Reference

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(options: TestOptions): void

mcp.tools.list(): Promise<Tool[]>

mcp.tools.call(name: string, args: Record<string, unknown>): Promise<ToolResult>

interface ToolResult {
  // Status checks
  isSuccess: boolean;
  isError: boolean;

  // Content accessors
  text(): string;                    // Get text content
  json<T = unknown>(): 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 };
}

mcp.resources.list(): Promise<Resource[]>

mcp.resources.listTemplates(): Promise<ResourceTemplate[]>

mcp.resources.read(uri: string): Promise<ResourceContent>

interface ResourceContent {
  text(): string;                    // Get text content
  json<T = unknown>(): T;            // Parse JSON content
  blob(): Uint8Array;                // Get binary content
  mimeType: string;                  // Content MIME type
  uri: string;                       // Resource URI
  raw: ReadResourceResult;           // Raw MCP response
}

mcp.prompts.list(): Promise<Prompt[]>

mcp.prompts.get(name: string, args?: Record<string, string>): Promise<PromptResult>

interface PromptResult {
  messages: PromptMessage[];         // Array of messages
  description?: string;              // Optional description
}

interface PromptMessage {
  role: 'user' | 'assistant';
  content: TextContent | ImageContent | EmbeddedResource;
}

mcp.isConnected(): boolean

mcp.sessionId: string | undefined

mcp.serverInfo: {
  name: string;
  version: string;
}

mcp.protocolVersion: string

mcp.capabilities: ServerCapabilities

mcp.hasCapability(name: 'tools' | 'resources' | 'prompts'): boolean

mcp.authenticate(token: string): Promise<void>

mcp.disconnect(): Promise<void>

mcp.raw.request(request: JsonRpcRequest): Promise<JsonRpcResponse>

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 };
}

mcp.raw.notify(notification: JsonRpcNotification): Promise<void>

mcp.raw.sendRaw(data: string): Promise<JsonRpcResponse>

mcp.logs.all(): LogEntry[]

mcp.logs.filter(level: 'debug' | 'info' | 'warn' | 'error'): LogEntry[]

mcp.logs.search(query: string): LogEntry[]

mcp.logs.clear(): void

mcp.trace.all(): RequestTrace[]

interface RequestTrace {
  method: string;
  params: unknown;
  response: unknown;
  durationMs: number;
  timestamp: Date;
}

mcp.trace.last(): RequestTrace | undefined

mcp.trace.clear(): void

auth.createToken(options: TokenOptions): Promise<string>

interface TokenOptions {
  sub: string;                              // Subject (required)
  scopes?: string[];                        // OAuth scopes
  email?: string;                           // Email claim
  name?: string;                            // Name claim
  claims?: Record<string, unknown>;         // Custom claims
  expiresIn?: number;                       // Lifetime in seconds (default: 3600)
}

auth.createExpiredToken(options: Omit<TokenOptions, 'expiresIn'>): Promise<string>

auth.createInvalidToken(options: TokenOptions): string

auth.users: {
  admin: { sub: 'test-admin', scopes: ['*'] };
  user: { sub: 'test-user', scopes: ['read', 'write'] };
  readOnly: { sub: 'test-readonly', scopes: ['read'] };
}

auth.getJwks(): Promise<JsonWebKeySet>

auth.getIssuer(): string

auth.getAudience(): string

server.info: {
  baseUrl: string;
  port: number;
  pid: number;
}

server.createClient(options?: ClientOptions): Promise<McpTestClient>

interface ClientOptions {
  transport?: 'sse' | 'streamable-http';
  token?: string;
}

server.restart(): Promise<void>

server.getLogs(): string[]

server.clearLogs(): void

mcp.mock.add(options: MockOptions): MockHandle

interface MockOptions {
  method: string;                           // MCP method to match
  params?: Record<string, unknown>;         // 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;
}

mcp.mock.tool(name: string, response: unknown): MockHandle

mcp.mock.toolError(name: string, code: number, message: string): MockHandle

mcp.mock.resource(uri: string, content: string | ResourceContent): MockHandle

mcp.mock.clear(): void

mcp.intercept.request(handler: RequestInterceptor): () => void

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 };

mcp.intercept.response(handler: ResponseInterceptor): () => void

type ResponseInterceptor = (ctx: ResponseContext) => ResponseAction;

interface ResponseContext {
  request: JsonRpcRequest;
  response: JsonRpcResponse;
  durationMs: number;
}

type ResponseAction =
  | { action: 'passthrough' }
  | { action: 'modify'; response: JsonRpcResponse };

mcp.intercept.delay(ms: number): () => void

mcp.intercept.failMethod(method: string, message: string): () => void

import { httpMock } from '@frontmcp/testing';

const interceptor = httpMock.interceptor();

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

type UrlMatcher = string | RegExp | ((url: string) => boolean);

interceptor.any(url: UrlMatcher, response: unknown, options?: MockOptions): MockHandle

interceptor.mock(options: HttpMockOptions): MockHandle

interface HttpMockOptions {
  match: {
    url: UrlMatcher;
    method?: string | string[];
    headers?: Record<string, string | RegExp>;
    body?: unknown | ((body: unknown) => boolean);
  };
  response: HttpResponse;
  times?: number;
}

interface HttpResponse {
  status?: number;
  statusText?: string;
  headers?: Record<string, string>;
  body?: unknown;
  delay?: number;
}

interceptor.allowPassthrough(enabled: boolean): void

interceptor.assertDone(): void

interceptor.pending(): HttpMockOptions[]

interceptor.restore(): void

interface MockHandle {
  callCount(): number;
  calls(): HttpCall[];
  waitForCalls(count: number, timeout?: number): Promise<HttpCall[]>;
}

interface HttpCall {
  url: string;
  method: string;
  headers: Record<string, string>;
  body?: unknown;
}

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

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

expect(tools).toContainTool(name: string): void

expect(result).toBeSuccessful(): void
expect(result).toBeError(code?: number): void

expect(result).toHaveTextContent(text?: string): void
expect(result).toHaveImageContent(): void
expect(result).toHaveResourceContent(): void
expect(content).toHaveMimeType(mimeType: string): void

expect(resources).toContainResource(uri: string): void
expect(templates).toContainResourceTemplate(uriTemplate: string): void

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

expect(response).toBeValidJsonRpc(): void
expect(response).toHaveResult(): void
expect(response).toHaveError(): void
expect(response).toHaveErrorCode(code: number): void

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';