@frontmcp/testing 0.5.1 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/testing",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "E2E testing framework for FrontMCP servers - MCP client, auth mocks, Playwright integration",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -58,8 +58,8 @@
     }
   },
   "peerDependencies": {
-    "@frontmcp/sdk": "0.5.1",
-    "@frontmcp/ui": "0.5.1",
+    "@frontmcp/sdk": "0.6.1",
+    "@frontmcp/ui": "0.6.1",
     "@playwright/test": "^1.40.0",
     "jest": "^29.0.0",
     "@jest/globals": "^29.0.0"
@@ -82,7 +82,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.24.3",
+    "@modelcontextprotocol/sdk": "1.25.1",
     "jose": "^6.0.11",
     "tslib": "^2.3.0"
   },

package/src/auth/mock-api-server.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @file mock-api-server.ts
+ * @description Mock API server for testing OpenAPI adapter
+ *
+ * This module provides a mock HTTP server that serves:
+ * - OpenAPI spec endpoint for adapter initialization
+ * - Mock API responses for generated tools
+ *
+ * @example
+ * ```typescript
+ * import { MockAPIServer } from '@frontmcp/testing';
+ *
+ * const apiServer = new MockAPIServer({
+ *   openApiSpec: { openapi: '3.0.0', ... },
+ *   routes: [
+ *     { method: 'GET', path: '/products', response: { body: [...] } },
+ *   ],
+ * });
+ *
+ * // Start the mock server
+ * const info = await apiServer.start();
+ *
+ * // Configure your MCP server to use this mock
+ * // OPENAPI_BASE_URL = info.baseUrl
+ *
+ * // Stop when done
+ * await apiServer.stop();
+ * ```
+ */
+export interface MockRoute {
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Path to match (e.g., '/products', '/products/:id') */
+    path: string;
+    /** Response to return */
+    response: MockResponse;
+}
+export interface MockResponse {
+    /** HTTP status code (default: 200) */
+    status?: number;
+    /** Response headers */
+    headers?: Record<string, string>;
+    /** Response body (will be JSON serialized) */
+    body: unknown;
+}
+export interface MockAPIServerOptions {
+    /** Port to listen on (default: random available port) */
+    port?: number;
+    /** OpenAPI spec to serve at /openapi.json */
+    openApiSpec: unknown;
+    /** Routes to mock */
+    routes?: MockRoute[];
+    /** Enable debug logging */
+    debug?: boolean;
+}
+export interface MockAPIServerInfo {
+    /** Base URL of the server */
+    baseUrl: string;
+    /** Port the server is listening on */
+    port: number;
+    /** OpenAPI spec URL */
+    specUrl: string;
+}
+/**
+ * Mock API server for testing OpenAPI adapter
+ *
+ * Serves an OpenAPI spec and mock API responses so that MCP servers
+ * can use the OpenAPI adapter without connecting to a real API.
+ */
+export declare class MockAPIServer {
+    private readonly options;
+    private server;
+    private _info;
+    private routes;
+    constructor(options: MockAPIServerOptions);
+    /**
+     * Start the mock API server
+     */
+    start(): Promise<MockAPIServerInfo>;
+    /**
+     * Stop the mock API server
+     */
+    stop(): Promise<void>;
+    /**
+     * Get server info
+     */
+    get info(): MockAPIServerInfo;
+    /**
+     * Add a route dynamically
+     */
+    addRoute(route: MockRoute): void;
+    /**
+     * Clear all routes
+     */
+    clearRoutes(): void;
+    private handleRequest;
+    private findRoute;
+    private log;
+}

package/src/auth/mock-api-server.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * @file mock-api-server.ts
+ * @description Mock API server for testing OpenAPI adapter
+ *
+ * This module provides a mock HTTP server that serves:
+ * - OpenAPI spec endpoint for adapter initialization
+ * - Mock API responses for generated tools
+ *
+ * @example
+ * ```typescript
+ * import { MockAPIServer } from '@frontmcp/testing';
+ *
+ * const apiServer = new MockAPIServer({
+ *   openApiSpec: { openapi: '3.0.0', ... },
+ *   routes: [
+ *     { method: 'GET', path: '/products', response: { body: [...] } },
+ *   ],
+ * });
+ *
+ * // Start the mock server
+ * const info = await apiServer.start();
+ *
+ * // Configure your MCP server to use this mock
+ * // OPENAPI_BASE_URL = info.baseUrl
+ *
+ * // Stop when done
+ * await apiServer.stop();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockAPIServer = void 0;
+const http_1 = require("http");
+// ═══════════════════════════════════════════════════════════════════
+// MOCK API SERVER
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Mock API server for testing OpenAPI adapter
+ *
+ * Serves an OpenAPI spec and mock API responses so that MCP servers
+ * can use the OpenAPI adapter without connecting to a real API.
+ */
+class MockAPIServer {
+    options;
+    server = null;
+    _info = null;
+    routes;
+    constructor(options) {
+        this.options = options;
+        this.routes = options.routes ?? [];
+    }
+    /**
+     * Start the mock API server
+     */
+    async start() {
+        if (this.server) {
+            throw new Error('Mock API server is already running');
+        }
+        const port = this.options.port ?? 0; // 0 = random available port
+        return new Promise((resolve, reject) => {
+            this.server = (0, http_1.createServer)(this.handleRequest.bind(this));
+            this.server.on('error', (err) => {
+                this.log(`Server error: ${err.message}`);
+                reject(err);
+            });
+            this.server.listen(port, () => {
+                const address = this.server.address();
+                if (!address || typeof address === 'string') {
+                    reject(new Error('Failed to get server address'));
+                    return;
+                }
+                const actualPort = address.port;
+                this._info = {
+                    baseUrl: `http://localhost:${actualPort}`,
+                    port: actualPort,
+                    specUrl: `http://localhost:${actualPort}/openapi.json`,
+                };
+                this.log(`Mock API server started at ${this._info.baseUrl}`);
+                resolve(this._info);
+            });
+        });
+    }
+    /**
+     * Stop the mock API server
+     */
+    async stop() {
+        if (!this.server) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            this.server.close((err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    this.server = null;
+                    this._info = null;
+                    this.log('Mock API server stopped');
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Get server info
+     */
+    get info() {
+        if (!this._info) {
+            throw new Error('Mock API server is not running');
+        }
+        return this._info;
+    }
+    /**
+     * Add a route dynamically
+     */
+    addRoute(route) {
+        this.routes.push(route);
+    }
+    /**
+     * Clear all routes
+     */
+    clearRoutes() {
+        this.routes = [];
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // PRIVATE
+    // ═══════════════════════════════════════════════════════════════════
+    async handleRequest(req, res) {
+        const url = req.url ?? '/';
+        const method = (req.method ?? 'GET').toUpperCase();
+        this.log(`${method} ${url}`);
+        // CORS headers
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        if (method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        try {
+            // Serve OpenAPI spec
+            if (url === '/openapi.json' || url === '/openapi.yaml') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(this.options.openApiSpec));
+                this.log('Served OpenAPI spec');
+                return;
+            }
+            // Find matching route
+            const route = this.findRoute(method, url);
+            if (route) {
+                const status = route.response.status ?? 200;
+                const headers = {
+                    'Content-Type': 'application/json',
+                    ...route.response.headers,
+                };
+                res.writeHead(status, headers);
+                res.end(JSON.stringify(route.response.body));
+                this.log(`Matched route: ${method} ${route.path} -> ${status}`);
+                return;
+            }
+            // No matching route
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'not_found', message: `No mock for ${method} ${url}` }));
+        }
+        catch (error) {
+            this.log(`Error handling request: ${error}`);
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'server_error', message: 'Internal server error' }));
+        }
+    }
+    findRoute(method, url) {
+        // Strip query string
+        const path = url.split('?')[0];
+        return this.routes.find((route) => {
+            if (route.method !== method)
+                return false;
+            // Simple path matching (exact match or path params)
+            if (route.path === path)
+                return true;
+            // Handle path parameters like /products/:id
+            const routeParts = route.path.split('/');
+            const urlParts = path.split('/');
+            if (routeParts.length !== urlParts.length)
+                return false;
+            return routeParts.every((part, i) => {
+                if (part.startsWith(':'))
+                    return true; // Path parameter
+                return part === urlParts[i];
+            });
+        });
+    }
+    log(message) {
+        if (this.options.debug) {
+            console.log(`[MockAPIServer] ${message}`);
+        }
+    }
+}
+exports.MockAPIServer = MockAPIServer;
+//# sourceMappingURL=mock-api-server.js.map

package/src/auth/mock-api-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-api-server.js","sourceRoot":"","sources":["../../../src/auth/mock-api-server.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @file mock-api-server.ts\n * @description Mock API server for testing OpenAPI adapter\n *\n * This module provides a mock HTTP server that serves:\n * - OpenAPI spec endpoint for adapter initialization\n * - Mock API responses for generated tools\n *\n * @example\n * ```typescript\n * import { MockAPIServer } from '@frontmcp/testing';\n *\n * const apiServer = new MockAPIServer({\n *   openApiSpec: { openapi: '3.0.0', ... },\n *   routes: [\n *     { method: 'GET', path: '/products', response: { body: [...] } },\n *   ],\n * });\n *\n * // Start the mock server\n * const info = await apiServer.start();\n *\n * // Configure your MCP server to use this mock\n * // OPENAPI_BASE_URL = info.baseUrl\n *\n * // Stop when done\n * await apiServer.stop();\n * ```\n */\n\nimport { createServer, Server, IncomingMessage, ServerResponse } from 'http';\n\n// ═══════════════════════════════════════════════════════════════════\n// TYPES\n// ═══════════════════════════════════════════════════════════════════\n\nexport interface MockRoute {\n  /** HTTP method */\n  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';\n  /** Path to match (e.g., '/products', '/products/:id') */\n  path: string;\n  /** Response to return */\n  response: MockResponse;\n}\n\nexport interface MockResponse {\n  /** HTTP status code (default: 200) */\n  status?: number;\n  /** Response headers */\n  headers?: Record<string, string>;\n  /** Response body (will be JSON serialized) */\n  body: unknown;\n}\n\nexport interface MockAPIServerOptions {\n  /** Port to listen on (default: random available port) */\n  port?: number;\n  /** OpenAPI spec to serve at /openapi.json */\n  openApiSpec: unknown;\n  /** Routes to mock */\n  routes?: MockRoute[];\n  /** Enable debug logging */\n  debug?: boolean;\n}\n\nexport interface MockAPIServerInfo {\n  /** Base URL of the server */\n  baseUrl: string;\n  /** Port the server is listening on */\n  port: number;\n  /** OpenAPI spec URL */\n  specUrl: string;\n}\n\n// ═══════════════════════════════════════════════════════════════════\n// MOCK API SERVER\n// ═══════════════════════════════════════════════════════════════════\n\n/**\n * Mock API server for testing OpenAPI adapter\n *\n * Serves an OpenAPI spec and mock API responses so that MCP servers\n * can use the OpenAPI adapter without connecting to a real API.\n */\nexport class MockAPIServer {\n  private readonly options: MockAPIServerOptions;\n  private server: Server | null = null;\n  private _info: MockAPIServerInfo | null = null;\n  private routes: MockRoute[];\n\n  constructor(options: MockAPIServerOptions) {\n    this.options = options;\n    this.routes = options.routes ?? [];\n  }\n\n  /**\n   * Start the mock API server\n   */\n  async start(): Promise<MockAPIServerInfo> {\n    if (this.server) {\n      throw new Error('Mock API server is already running');\n    }\n\n    const port = this.options.port ?? 0; // 0 = random available port\n\n    return new Promise((resolve, reject) => {\n      this.server = createServer(this.handleRequest.bind(this));\n\n      this.server.on('error', (err) => {\n        this.log(`Server error: ${err.message}`);\n        reject(err);\n      });\n\n      this.server.listen(port, () => {\n        const address = this.server!.address();\n        if (!address || typeof address === 'string') {\n          reject(new Error('Failed to get server address'));\n          return;\n        }\n\n        const actualPort = address.port;\n\n        this._info = {\n          baseUrl: `http://localhost:${actualPort}`,\n          port: actualPort,\n          specUrl: `http://localhost:${actualPort}/openapi.json`,\n        };\n\n        this.log(`Mock API server started at ${this._info.baseUrl}`);\n        resolve(this._info);\n      });\n    });\n  }\n\n  /**\n   * Stop the mock API server\n   */\n  async stop(): Promise<void> {\n    if (!this.server) {\n      return;\n    }\n\n    return new Promise((resolve, reject) => {\n      this.server!.close((err) => {\n        if (err) {\n          reject(err);\n        } else {\n          this.server = null;\n          this._info = null;\n          this.log('Mock API server stopped');\n          resolve();\n        }\n      });\n    });\n  }\n\n  /**\n   * Get server info\n   */\n  get info(): MockAPIServerInfo {\n    if (!this._info) {\n      throw new Error('Mock API server is not running');\n    }\n    return this._info;\n  }\n\n  /**\n   * Add a route dynamically\n   */\n  addRoute(route: MockRoute): void {\n    this.routes.push(route);\n  }\n\n  /**\n   * Clear all routes\n   */\n  clearRoutes(): void {\n    this.routes = [];\n  }\n\n  // ═══════════════════════════════════════════════════════════════════\n  // PRIVATE\n  // ═══════════════════════════════════════════════════════════════════\n\n  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {\n    const url = req.url ?? '/';\n    const method = (req.method ?? 'GET').toUpperCase();\n    this.log(`${method} ${url}`);\n\n    // CORS headers\n    res.setHeader('Access-Control-Allow-Origin', '*');\n    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');\n    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');\n\n    if (method === 'OPTIONS') {\n      res.writeHead(204);\n      res.end();\n      return;\n    }\n\n    try {\n      // Serve OpenAPI spec\n      if (url === '/openapi.json' || url === '/openapi.yaml') {\n        res.writeHead(200, { 'Content-Type': 'application/json' });\n        res.end(JSON.stringify(this.options.openApiSpec));\n        this.log('Served OpenAPI spec');\n        return;\n      }\n\n      // Find matching route\n      const route = this.findRoute(method, url);\n      if (route) {\n        const status = route.response.status ?? 200;\n        const headers = {\n          'Content-Type': 'application/json',\n          ...route.response.headers,\n        };\n        res.writeHead(status, headers);\n        res.end(JSON.stringify(route.response.body));\n        this.log(`Matched route: ${method} ${route.path} -> ${status}`);\n        return;\n      }\n\n      // No matching route\n      res.writeHead(404, { 'Content-Type': 'application/json' });\n      res.end(JSON.stringify({ error: 'not_found', message: `No mock for ${method} ${url}` }));\n    } catch (error) {\n      this.log(`Error handling request: ${error}`);\n      res.writeHead(500, { 'Content-Type': 'application/json' });\n      res.end(JSON.stringify({ error: 'server_error', message: 'Internal server error' }));\n    }\n  }\n\n  private findRoute(method: string, url: string): MockRoute | undefined {\n    // Strip query string\n    const path = url.split('?')[0];\n\n    return this.routes.find((route) => {\n      if (route.method !== method) return false;\n\n      // Simple path matching (exact match or path params)\n      if (route.path === path) return true;\n\n      // Handle path parameters like /products/:id\n      const routeParts = route.path.split('/');\n      const urlParts = path.split('/');\n\n      if (routeParts.length !== urlParts.length) return false;\n\n      return routeParts.every((part, i) => {\n        if (part.startsWith(':')) return true; // Path parameter\n        return part === urlParts[i];\n      });\n    });\n  }\n\n  private log(message: string): void {\n    if (this.options.debug) {\n      console.log(`[MockAPIServer] ${message}`);\n    }\n  }\n}\n"]}

package/src/auth/mock-oauth-server.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file mock-oauth-server.ts
+ * @description Mock OAuth server for testing transparent auth mode
+ *
+ * This module provides a mock OAuth/OIDC server that serves:
+ * - JWKS endpoint for token verification
+ * - OAuth metadata endpoint (optional)
+ * - Token endpoint for anonymous tokens (optional)
+ *
+ * @example
+ * ```typescript
+ * import { MockOAuthServer, TestTokenFactory } from '@frontmcp/testing';
+ *
+ * const tokenFactory = new TestTokenFactory();
+ * const oauthServer = new MockOAuthServer(tokenFactory);
+ *
+ * // Start the mock server
+ * await oauthServer.start();
+ *
+ * // Configure your MCP server to use this mock
+ * // IDP_PROVIDER_URL = oauthServer.baseUrl
+ *
+ * // Create tokens using the same factory
+ * const token = await tokenFactory.createTestToken({ sub: 'user-123' });
+ *
+ * // Stop when done
+ * await oauthServer.stop();
+ * ```
+ */
+import type { TestTokenFactory } from './token-factory';
+export interface MockOAuthServerOptions {
+    /** Port to listen on (default: random available port) */
+    port?: number;
+    /** Issuer URL (default: http://localhost:{port}) */
+    issuer?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+export interface MockOAuthServerInfo {
+    /** Base URL of the server */
+    baseUrl: string;
+    /** Port the server is listening on */
+    port: number;
+    /** Issuer URL */
+    issuer: string;
+    /** JWKS endpoint URL */
+    jwksUrl: string;
+}
+/**
+ * Mock OAuth/OIDC server for testing transparent auth mode
+ *
+ * Serves JWKS from a TestTokenFactory so that MCP servers can
+ * validate test tokens without connecting to a real IdP.
+ */
+export declare class MockOAuthServer {
+    private readonly tokenFactory;
+    private readonly options;
+    private server;
+    private _info;
+    private connections;
+    constructor(tokenFactory: TestTokenFactory, options?: MockOAuthServerOptions);
+    /**
+     * Start the mock OAuth server
+     */
+    start(): Promise<MockOAuthServerInfo>;
+    /**
+     * Stop the mock OAuth server
+     */
+    stop(): Promise<void>;
+    /**
+     * Get server info
+     */
+    get info(): MockOAuthServerInfo;
+    /**
+     * Get the token factory (for creating tokens)
+     */
+    getTokenFactory(): TestTokenFactory;
+    private handleRequest;
+    private handleJwks;
+    private handleOidcConfig;
+    private handleOAuthMetadata;
+    private handleTokenEndpoint;
+    private readBody;
+    private log;
+}