@frontmcp/testing 0.5.0

package/src/client/mcp-test-client.d.ts

@@ -0,0 +1,360 @@
+/**
+ * @file mcp-test-client.ts
+ * @description Main MCP Test Client implementation for E2E testing
+ */
+import type { McpTestClientConfig, TestTransportType, ToolResultWrapper, ResourceContentWrapper, PromptResultWrapper, LogEntry, RequestTrace, NotificationEntry, ProgressUpdate, SessionInfo, AuthState, InitializeResult, Tool, Resource, ResourceTemplate, Prompt, JSONRPCResponse } from './mcp-test-client.types';
+import { McpTestClientBuilder } from './mcp-test-client.builder';
+import type { MockDefinition, MockHandle, RequestInterceptor, ResponseInterceptor } from '../interceptor';
+export declare class McpTestClient {
+    private readonly config;
+    private transport;
+    private initResult;
+    private requestIdCounter;
+    private _lastRequestId;
+    private _sessionId;
+    private _sessionInfo;
+    private _authState;
+    private _logs;
+    private _traces;
+    private _notifications;
+    private _progressUpdates;
+    private _interceptors;
+    constructor(config: McpTestClientConfig);
+    /**
+     * Create a new McpTestClientBuilder for fluent configuration
+     */
+    static create(config: McpTestClientConfig): McpTestClientBuilder;
+    /**
+     * Connect to the MCP server and perform initialization
+     */
+    connect(): Promise<InitializeResult>;
+    /**
+     * Disconnect from the MCP server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reconnect to the server, optionally with an existing session ID
+     */
+    reconnect(options?: {
+        sessionId?: string;
+    }): Promise<void>;
+    /**
+     * Check if the client is currently connected
+     */
+    isConnected(): boolean;
+    get sessionId(): string;
+    get session(): SessionInfo & {
+        expire: () => Promise<void>;
+    };
+    get auth(): AuthState;
+    /**
+     * Authenticate with a token
+     */
+    authenticate(token: string): Promise<void>;
+    get serverInfo(): {
+        name: string;
+        version: string;
+        title?: string;
+    };
+    get protocolVersion(): string;
+    get instructions(): string;
+    get capabilities(): InitializeResult['capabilities'];
+    /**
+     * Check if server has a specific capability
+     */
+    hasCapability(name: 'tools' | 'resources' | 'prompts' | 'logging' | 'sampling'): boolean;
+    readonly tools: {
+        /**
+         * List all available tools
+         */
+        list: () => Promise<Tool[]>;
+        /**
+         * Call a tool by name with arguments
+         */
+        call: (name: string, args?: Record<string, unknown>) => Promise<ToolResultWrapper>;
+    };
+    readonly resources: {
+        /**
+         * List all static resources
+         */
+        list: () => Promise<Resource[]>;
+        /**
+         * List all resource templates
+         */
+        listTemplates: () => Promise<ResourceTemplate[]>;
+        /**
+         * Read a resource by URI
+         */
+        read: (uri: string) => Promise<ResourceContentWrapper>;
+        /**
+         * Subscribe to resource changes (placeholder for future implementation)
+         */
+        subscribe: (_uri: string) => Promise<void>;
+        /**
+         * Unsubscribe from resource changes (placeholder for future implementation)
+         */
+        unsubscribe: (_uri: string) => Promise<void>;
+    };
+    readonly prompts: {
+        /**
+         * List all available prompts
+         */
+        list: () => Promise<Prompt[]>;
+        /**
+         * Get a prompt with arguments
+         */
+        get: (name: string, args?: Record<string, string>) => Promise<PromptResultWrapper>;
+    };
+    readonly raw: {
+        /**
+         * Send any JSON-RPC request
+         */
+        request: (message: {
+            jsonrpc: "2.0";
+            id: string | number;
+            method: string;
+            params?: Record<string, unknown>;
+        }) => Promise<JSONRPCResponse>;
+        /**
+         * Send a notification (no response expected)
+         */
+        notify: (message: {
+            jsonrpc: "2.0";
+            method: string;
+            params?: Record<string, unknown>;
+        }) => Promise<void>;
+        /**
+         * Send raw string data (for error testing)
+         */
+        sendRaw: (data: string) => Promise<JSONRPCResponse>;
+    };
+    get lastRequestId(): string | number;
+    /**
+     * Get transport information and utilities
+     */
+    get transport_info(): {
+        type: TestTransportType;
+        isConnected: () => boolean;
+        messageEndpoint: string | undefined;
+        connectionCount: number;
+        reconnectCount: number;
+        lastRequestHeaders: Record<string, string>;
+        simulateDisconnect: () => Promise<void>;
+        waitForReconnect: (timeoutMs: number) => Promise<void>;
+    };
+    get transport_(): {
+        type: TestTransportType;
+        isConnected: () => boolean;
+        messageEndpoint: string | undefined;
+        connectionCount: number;
+        reconnectCount: number;
+        lastRequestHeaders: Record<string, string>;
+        simulateDisconnect: () => Promise<void>;
+        waitForReconnect: (timeoutMs: number) => Promise<void>;
+    };
+    readonly notifications: {
+        /**
+         * Start collecting server notifications
+         */
+        collect: () => NotificationCollector;
+        /**
+         * Collect progress notifications specifically
+         */
+        collectProgress: () => ProgressCollector;
+        /**
+         * Send a notification to the server
+         */
+        send: (method: string, params?: Record<string, unknown>) => Promise<void>;
+    };
+    readonly logs: {
+        all: () => LogEntry[];
+        filter: (level: "debug" | "info" | "warn" | "error") => LogEntry[];
+        search: (text: string) => LogEntry[];
+        last: () => LogEntry | undefined;
+        clear: () => void;
+    };
+    readonly trace: {
+        all: () => RequestTrace[];
+        last: () => RequestTrace | undefined;
+        clear: () => void;
+    };
+    /**
+     * API for mocking MCP requests
+     *
+     * @example
+     * ```typescript
+     * // Mock a specific tool call
+     * const handle = mcp.mock.tool('my-tool', { result: 'mocked!' });
+     *
+     * // Mock with params matching
+     * mcp.mock.add({
+     *   method: 'tools/call',
+     *   params: { name: 'my-tool' },
+     *   response: mockResponse.toolResult([{ type: 'text', text: 'mocked' }]),
+     * });
+     *
+     * // Clear all mocks after test
+     * mcp.mock.clear();
+     * ```
+     */
+    readonly mock: {
+        /**
+         * Add a mock definition
+         */
+        add: (mock: MockDefinition) => MockHandle;
+        /**
+         * Mock a tools/call request for a specific tool
+         */
+        tool: (name: string, result: unknown, options?: {
+            times?: number;
+            delay?: number;
+        }) => MockHandle;
+        /**
+         * Mock a tools/call request to return an error
+         */
+        toolError: (name: string, code: number, message: string, options?: {
+            times?: number;
+        }) => MockHandle;
+        /**
+         * Mock a resources/read request
+         */
+        resource: (uri: string, content: string | {
+            text?: string;
+            blob?: string;
+            mimeType?: string;
+        }, options?: {
+            times?: number;
+            delay?: number;
+        }) => MockHandle;
+        /**
+         * Mock a resources/read request to return an error
+         */
+        resourceError: (uri: string, options?: {
+            times?: number;
+        }) => MockHandle;
+        /**
+         * Mock the tools/list response
+         */
+        toolsList: (tools: Array<{
+            name: string;
+            description?: string;
+            inputSchema?: Record<string, unknown>;
+        }>, options?: {
+            times?: number;
+        }) => MockHandle;
+        /**
+         * Mock the resources/list response
+         */
+        resourcesList: (resources: Array<{
+            uri: string;
+            name?: string;
+            description?: string;
+            mimeType?: string;
+        }>, options?: {
+            times?: number;
+        }) => MockHandle;
+        /**
+         * Clear all mocks
+         */
+        clear: () => void;
+        /**
+         * Get all active mocks
+         */
+        all: () => MockDefinition[];
+    };
+    /**
+     * API for intercepting requests and responses
+     *
+     * @example
+     * ```typescript
+     * // Log all requests
+     * const remove = mcp.intercept.request((ctx) => {
+     *   console.log('Request:', ctx.request.method);
+     *   return { action: 'passthrough' };
+     * });
+     *
+     * // Modify requests
+     * mcp.intercept.request((ctx) => {
+     *   if (ctx.request.method === 'tools/call') {
+     *     return {
+     *       action: 'modify',
+     *       request: { ...ctx.request, params: { ...ctx.request.params, extra: true } },
+     *     };
+     *   }
+     *   return { action: 'passthrough' };
+     * });
+     *
+     * // Add latency to all requests
+     * mcp.intercept.delay(100);
+     *
+     * // Clean up
+     * remove();
+     * mcp.intercept.clear();
+     * ```
+     */
+    readonly intercept: {
+        /**
+         * Add a request interceptor
+         * @returns Function to remove the interceptor
+         */
+        request: (interceptor: RequestInterceptor) => (() => void);
+        /**
+         * Add a response interceptor
+         * @returns Function to remove the interceptor
+         */
+        response: (interceptor: ResponseInterceptor) => (() => void);
+        /**
+         * Add latency to all requests
+         * @returns Function to remove the interceptor
+         */
+        delay: (ms: number) => (() => void);
+        /**
+         * Fail requests matching a method
+         * @returns Function to remove the interceptor
+         */
+        failMethod: (method: string, error?: string) => (() => void);
+        /**
+         * Clear all interceptors (but not mocks)
+         */
+        clear: () => void;
+        /**
+         * Clear everything (interceptors and mocks)
+         */
+        clearAll: () => void;
+    };
+    setTimeout(ms: number): void;
+    private initialize;
+    private listTools;
+    private callTool;
+    private listResources;
+    private listResourceTemplates;
+    private readResource;
+    private listPrompts;
+    private getPrompt;
+    private createTransport;
+    private request;
+    private ensureConnected;
+    private updateSessionActivity;
+    private wrapToolResult;
+    private wrapResourceContent;
+    private wrapPromptResult;
+    private log;
+    private traceRequest;
+    private parseScopesFromToken;
+    private parseUserFromToken;
+    private decodeJwtPayload;
+}
+declare class NotificationCollector {
+    private readonly notifications;
+    constructor(notifications: NotificationEntry[]);
+    get received(): NotificationEntry[];
+    has(method: string): boolean;
+    waitFor(method: string, timeoutMs: number): Promise<NotificationEntry>;
+}
+declare class ProgressCollector {
+    private readonly updates;
+    constructor(updates: ProgressUpdate[]);
+    get all(): ProgressUpdate[];
+    waitForComplete(timeoutMs: number): Promise<void>;
+}
+export {};