@frontmcp/testing 1.8.0 → 1.8.1

package/esm/index.mjs

@@ -343,6 +343,7 @@ var interceptors = {
 
 // libs/testing/src/transport/streamable-http.transport.ts
 var DEFAULT_TIMEOUT = 3e4;
+var NOTIFICATION_STREAM_REOPEN_DELAY_MS = 250;
 var StreamableHttpTransport = class {
   config;
   state = "disconnected";
@@ -354,6 +355,10 @@ var StreamableHttpTransport = class {
   interceptors;
   publicMode;
   elicitationHandler;
+  notificationHandler;
+  notificationStream;
+  notificationProtocolVersion = "";
+  notificationStreamReopenTimer;
   constructor(config) {
     this.config = {
       baseUrl: config.baseUrl.replace(/\/$/, ""),
@@ -370,6 +375,7 @@ var StreamableHttpTransport = class {
     this.interceptors = config.interceptors;
     this.publicMode = config.publicMode ?? false;
     this.elicitationHandler = config.elicitationHandler;
+    this.notificationHandler = config.notificationHandler;
   }
   async connect() {
     this.state = "connecting";
@@ -589,7 +595,12 @@ var StreamableHttpTransport = class {
       };
     }
   }
+  async openNotificationStream(protocolVersion) {
+    this.notificationProtocolVersion = protocolVersion;
+    await this.connectNotificationStream();
+  }
   async close() {
+    this.closeNotificationStream();
     this.state = "disconnected";
     this.sessionId = void 0;
     this.log("StreamableHTTP transport closed");
@@ -628,6 +639,7 @@ var StreamableHttpTransport = class {
     return { ...this.lastRequestHeaders };
   }
   async simulateDisconnect() {
+    this.closeNotificationStream();
     this.state = "disconnected";
     this.sessionId = void 0;
   }
@@ -646,6 +658,72 @@ var StreamableHttpTransport = class {
   // ═══════════════════════════════════════════════════════════════════
   // PRIVATE HELPERS
   // ═══════════════════════════════════════════════════════════════════
+  closeNotificationStream() {
+    clearTimeout(this.notificationStreamReopenTimer);
+    this.notificationStream?.abort();
+    this.notificationStream = void 0;
+  }
+  /** Opens the stream without holding up the caller past the request timeout; close() aborts it at any point. */
+  async connectNotificationStream() {
+    if (!this.sessionId || this.notificationStream) return;
+    const controller = new AbortController();
+    this.notificationStream = controller;
+    const { "Content-Type": _contentType, ...headers } = this.buildHeaders();
+    const established = fetch(this.mcpUrl(), {
+      method: "GET",
+      headers: { ...headers, Accept: "text/event-stream", "MCP-Protocol-Version": this.notificationProtocolVersion },
+      signal: controller.signal
+    }).then(
+      async (response) => {
+        const isEventStream = response.headers.get("content-type")?.includes("text/event-stream") ?? false;
+        if (!response.ok || !response.body || !isEventStream) {
+          await response.body?.cancel();
+          this.log(`Server offers no notification stream (HTTP ${response.status})`);
+          this.releaseNotificationStream(controller);
+          return;
+        }
+        void this.readNotificationStream(controller, response.body.getReader());
+      },
+      (error) => {
+        this.log("Failed to open the notification stream:", error);
+        this.releaseNotificationStream(controller);
+      }
+    );
+    let establishTimer;
+    const establishDeadline = new Promise((resolve) => {
+      establishTimer = setTimeout(resolve, this.config.timeout);
+    });
+    await Promise.race([established, establishDeadline]);
+    clearTimeout(establishTimer);
+  }
+  releaseNotificationStream(controller) {
+    if (this.notificationStream === controller) this.notificationStream = void 0;
+  }
+  async readNotificationStream(controller, reader) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+        const { completeEvents, remainder } = splitSSEEvents(buffer + decoder.decode(chunk.value, { stream: true }));
+        buffer = remainder;
+        for (const eventText of completeEvents) {
+          for (const event of this.parseSSEEvents(eventText, void 0).events) {
+            await this.handleSSEEvent(event);
+          }
+        }
+      }
+    } catch (error) {
+      this.log("Notification stream ended:", error);
+    } finally {
+      reader.releaseLock();
+    }
+    if (controller.signal.aborted || this.notificationStream !== controller) return;
+    this.releaseNotificationStream(controller);
+    this.notificationStreamReopenTimer = setTimeout(
+      () => void this.connectNotificationStream(),
+      NOTIFICATION_STREAM_REOPEN_DELAY_MS
+    );
+  }
   /**
    * Handle SSE response with elicitation support.
    *
@@ -783,6 +861,13 @@ var StreamableHttpTransport = class {
           response: { jsonrpc: "2.0", id: null, result: void 0 }
         };
       }
+      if ("method" in parsed && parsed.id === void 0) {
+        this.notificationHandler?.(parsed);
+        return {
+          isFinal: false,
+          response: { jsonrpc: "2.0", id: null, result: void 0 }
+        };
+      }
       if ("result" in parsed || "error" in parsed) {
         return { isFinal: true, response: parsed };
       }
@@ -953,6 +1038,13 @@ var StreamableHttpTransport = class {
     };
   }
 };
+function splitSSEEvents(buffer) {
+  const endsWithCarriageReturn = buffer.endsWith("\r");
+  const normalized = (endsWithCarriageReturn ? buffer.slice(0, -1) : buffer).replace(/\r\n?/g, "\n");
+  const completeEvents = normalized.split("\n\n");
+  const remainder = completeEvents.pop() ?? "";
+  return { completeEvents, remainder: endsWithCarriageReturn ? `${remainder}\r` : remainder };
+}
 
 // libs/testing/src/platform/platform-client-info.ts
 var MCP_APPS_EXTENSION_KEY = "io.modelcontextprotocol/ui";
@@ -1108,7 +1200,8 @@ var McpTestClientBuilder = class {
     return this;
   }
   /**
-   * Set the MCP protocol version to request
+   * Set the MCP protocol version to request (default '2025-06-18').
+   * '2026-07-28' has no initialize handshake, so `build()` throws for it.
    */
   withProtocolVersion(version) {
     this.config.protocolVersion = version;
@@ -1204,6 +1297,7 @@ var McpTestClientBuilder = class {
 // libs/testing/src/client/mcp-test-client.ts
 var DEFAULT_TIMEOUT2 = 3e4;
 var DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+var UNSUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28"];
 var DEFAULT_CLIENT_INFO = {
   name: "@frontmcp/testing",
   version: "0.4.0"
@@ -1240,6 +1334,8 @@ var McpTestClient = class {
   _traces = [];
   _notifications = [];
   _progressUpdates = [];
+  collectingProgress = false;
+  progressTokenCounter = 0;
   // Interceptor chain
   _interceptors;
   // Elicitation handler for server→client elicit requests
@@ -1248,6 +1344,11 @@ var McpTestClient = class {
   // CONSTRUCTOR & FACTORY
   // ═══════════════════════════════════════════════════════════════════
   constructor(config) {
+    if (config.protocolVersion && UNSUPPORTED_PROTOCOL_VERSIONS.includes(config.protocolVersion)) {
+      throw new Error(
+        `McpTestClient does not support protocol version ${config.protocolVersion}: it has no initialize handshake. Use ${DEFAULT_PROTOCOL_VERSION} or earlier.`
+      );
+    }
     this.config = {
       baseUrl: config.baseUrl,
       entryPath: config.entryPath,
@@ -1333,6 +1434,7 @@ var McpTestClient = class {
       jsonrpc: "2.0",
       method: "notifications/initialized"
     });
+    await this.transport.openNotificationStream?.(this.initResult.protocolVersion);
     this.log("info", `Connected to ${this.initResult.serverInfo?.name ?? "MCP Server"}`);
     return this.initResult;
   }
@@ -1443,8 +1545,8 @@ var McpTestClient = class {
     /**
      * Call a tool by name with arguments
      */
-    call: async (name, args) => {
-      const response = await this.callTool(name, args);
+    call: async (name, args, options = {}) => {
+      const response = await this.callTool(name, args, this.progressTokenFor(options));
       return this.wrapToolResult(response);
     }
   };
@@ -1586,6 +1688,7 @@ var McpTestClient = class {
      * Collect progress notifications specifically
      */
     collectProgress: () => {
+      this.collectingProgress = true;
       return new ProgressCollector(this._progressUpdates);
     },
     /**
@@ -1891,12 +1994,29 @@ var McpTestClient = class {
   async listTools() {
     return this.request("tools/list", {});
   }
-  async callTool(name, args) {
+  async callTool(name, args, progressToken) {
     return this.request("tools/call", {
       name,
-      arguments: args ?? {}
+      arguments: args ?? {},
+      ...progressToken !== void 0 && { _meta: { progressToken } }
     });
   }
+  progressTokenFor(options) {
+    if (options.progressToken !== void 0) return options.progressToken;
+    return this.collectingProgress ? `progress-${++this.progressTokenCounter}` : void 0;
+  }
+  recordNotification = (notification) => {
+    const timestamp = /* @__PURE__ */ new Date();
+    this._notifications.push({ method: notification.method, params: notification.params, timestamp });
+    if (notification.method !== "notifications/progress") return;
+    const { progress, total, progressToken } = notification.params ?? {};
+    this._progressUpdates.push({
+      progress: Number(progress),
+      total: typeof total === "number" ? total : void 0,
+      progressToken: typeof progressToken === "string" || typeof progressToken === "number" ? progressToken : void 0,
+      timestamp
+    });
+  };
   async listResources() {
     return this.request("resources/list", {});
   }
@@ -1943,7 +2063,8 @@ var McpTestClient = class {
           debug: this.config.debug,
           interceptors: this._interceptors,
           clientInfo: this.config.clientInfo,
-          elicitationHandler: this._elicitationHandler
+          elicitationHandler: this._elicitationHandler,
+          notificationHandler: this.recordNotification
         });
       case "sse":
         throw new Error("SSE transport not yet implemented");
@@ -5486,18 +5607,17 @@ var toBeError = function(received, expectedCode) {
       message: () => `Expected a result wrapper object with isError property`
     };
   }
-  let pass = result.isError;
-  if (pass && expectedCode !== void 0) {
-    pass = result.error?.code === expectedCode;
-  }
+  const receivedCode = typeof expectedCode === "string" ? result.raw?._meta?.["code"] : result.error?.code;
+  const codeMatches = expectedCode === void 0 || receivedCode === expectedCode;
+  const pass = result.isError && codeMatches;
   return {
     pass,
     message: () => {
       if (!result.isError) {
         return "Expected result to be an error, but it was successful";
       }
-      if (expectedCode !== void 0 && result.error?.code !== expectedCode) {
-        return `Expected error code ${expectedCode}, but got ${result.error?.code}`;
+      if (!codeMatches) {
+        return `Expected error code ${expectedCode}, but got ${String(receivedCode)}`;
       }
       return "Expected result not to be an error";
     }

package/esm/matchers/index.mjs

@@ -363,18 +363,17 @@ var toBeError = function(received, expectedCode) {
       message: () => `Expected a result wrapper object with isError property`
     };
   }
-  let pass = result.isError;
-  if (pass && expectedCode !== void 0) {
-    pass = result.error?.code === expectedCode;
-  }
+  const receivedCode = typeof expectedCode === "string" ? result.raw?._meta?.["code"] : result.error?.code;
+  const codeMatches = expectedCode === void 0 || receivedCode === expectedCode;
+  const pass = result.isError && codeMatches;
   return {
     pass,
     message: () => {
       if (!result.isError) {
         return "Expected result to be an error, but it was successful";
       }
-      if (expectedCode !== void 0 && result.error?.code !== expectedCode) {
-        return `Expected error code ${expectedCode}, but got ${result.error?.code}`;
+      if (!codeMatches) {
+        return `Expected error code ${expectedCode}, but got ${String(receivedCode)}`;
       }
       return "Expected result not to be an error";
     }

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/testing",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "E2E testing framework for FrontMCP servers - MCP client, auth mocks, Playwright integration",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -87,9 +87,9 @@
     "./esm": null
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.8.0",
-    "@frontmcp/sdk": "1.8.0",
-    "@frontmcp/ui": "1.8.0",
+    "@frontmcp/lazy-zod": "1.8.1",
+    "@frontmcp/sdk": "1.8.1",
+    "@frontmcp/ui": "1.8.1",
     "@jest/globals": "^29.0.0 || ^30.0.0",
     "@playwright/test": "^1.40.0",
     "jest": "^29.0.0 || ^30.0.0"
@@ -112,8 +112,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@frontmcp/protocol": "1.8.0",
-    "@frontmcp/utils": "1.8.0",
+    "@frontmcp/protocol": "1.8.1",
+    "@frontmcp/utils": "1.8.1",
     "jose": "^6.0.11",
     "tslib": "^2.3.0"
   },

package/esm/perf/index.mjs

@@ -1046,6 +1046,7 @@ function sleep3(ms) {
 
 // libs/testing/src/transport/streamable-http.transport.ts
 var DEFAULT_TIMEOUT = 3e4;
+var NOTIFICATION_STREAM_REOPEN_DELAY_MS = 250;
 var StreamableHttpTransport = class {
   config;
   state = "disconnected";
@@ -1057,6 +1058,10 @@ var StreamableHttpTransport = class {
   interceptors;
   publicMode;
   elicitationHandler;
+  notificationHandler;
+  notificationStream;
+  notificationProtocolVersion = "";
+  notificationStreamReopenTimer;
   constructor(config) {
     this.config = {
       baseUrl: config.baseUrl.replace(/\/$/, ""),
@@ -1073,6 +1078,7 @@ var StreamableHttpTransport = class {
     this.interceptors = config.interceptors;
     this.publicMode = config.publicMode ?? false;
     this.elicitationHandler = config.elicitationHandler;
+    this.notificationHandler = config.notificationHandler;
   }
   async connect() {
     this.state = "connecting";
@@ -1292,7 +1298,12 @@ var StreamableHttpTransport = class {
       };
     }
   }
+  async openNotificationStream(protocolVersion) {
+    this.notificationProtocolVersion = protocolVersion;
+    await this.connectNotificationStream();
+  }
   async close() {
+    this.closeNotificationStream();
     this.state = "disconnected";
     this.sessionId = void 0;
     this.log("StreamableHTTP transport closed");
@@ -1331,6 +1342,7 @@ var StreamableHttpTransport = class {
     return { ...this.lastRequestHeaders };
   }
   async simulateDisconnect() {
+    this.closeNotificationStream();
     this.state = "disconnected";
     this.sessionId = void 0;
   }
@@ -1349,6 +1361,72 @@ var StreamableHttpTransport = class {
   // ═══════════════════════════════════════════════════════════════════
   // PRIVATE HELPERS
   // ═══════════════════════════════════════════════════════════════════
+  closeNotificationStream() {
+    clearTimeout(this.notificationStreamReopenTimer);
+    this.notificationStream?.abort();
+    this.notificationStream = void 0;
+  }
+  /** Opens the stream without holding up the caller past the request timeout; close() aborts it at any point. */
+  async connectNotificationStream() {
+    if (!this.sessionId || this.notificationStream) return;
+    const controller = new AbortController();
+    this.notificationStream = controller;
+    const { "Content-Type": _contentType, ...headers } = this.buildHeaders();
+    const established = fetch(this.mcpUrl(), {
+      method: "GET",
+      headers: { ...headers, Accept: "text/event-stream", "MCP-Protocol-Version": this.notificationProtocolVersion },
+      signal: controller.signal
+    }).then(
+      async (response) => {
+        const isEventStream = response.headers.get("content-type")?.includes("text/event-stream") ?? false;
+        if (!response.ok || !response.body || !isEventStream) {
+          await response.body?.cancel();
+          this.log(`Server offers no notification stream (HTTP ${response.status})`);
+          this.releaseNotificationStream(controller);
+          return;
+        }
+        void this.readNotificationStream(controller, response.body.getReader());
+      },
+      (error) => {
+        this.log("Failed to open the notification stream:", error);
+        this.releaseNotificationStream(controller);
+      }
+    );
+    let establishTimer;
+    const establishDeadline = new Promise((resolve) => {
+      establishTimer = setTimeout(resolve, this.config.timeout);
+    });
+    await Promise.race([established, establishDeadline]);
+    clearTimeout(establishTimer);
+  }
+  releaseNotificationStream(controller) {
+    if (this.notificationStream === controller) this.notificationStream = void 0;
+  }
+  async readNotificationStream(controller, reader) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+        const { completeEvents, remainder } = splitSSEEvents(buffer + decoder.decode(chunk.value, { stream: true }));
+        buffer = remainder;
+        for (const eventText of completeEvents) {
+          for (const event of this.parseSSEEvents(eventText, void 0).events) {
+            await this.handleSSEEvent(event);
+          }
+        }
+      }
+    } catch (error) {
+      this.log("Notification stream ended:", error);
+    } finally {
+      reader.releaseLock();
+    }
+    if (controller.signal.aborted || this.notificationStream !== controller) return;
+    this.releaseNotificationStream(controller);
+    this.notificationStreamReopenTimer = setTimeout(
+      () => void this.connectNotificationStream(),
+      NOTIFICATION_STREAM_REOPEN_DELAY_MS
+    );
+  }
   /**
    * Handle SSE response with elicitation support.
    *
@@ -1486,6 +1564,13 @@ var StreamableHttpTransport = class {
           response: { jsonrpc: "2.0", id: null, result: void 0 }
         };
       }
+      if ("method" in parsed && parsed.id === void 0) {
+        this.notificationHandler?.(parsed);
+        return {
+          isFinal: false,
+          response: { jsonrpc: "2.0", id: null, result: void 0 }
+        };
+      }
       if ("result" in parsed || "error" in parsed) {
         return { isFinal: true, response: parsed };
       }
@@ -1656,6 +1741,13 @@ var StreamableHttpTransport = class {
     };
   }
 };
+function splitSSEEvents(buffer) {
+  const endsWithCarriageReturn = buffer.endsWith("\r");
+  const normalized = (endsWithCarriageReturn ? buffer.slice(0, -1) : buffer).replace(/\r\n?/g, "\n");
+  const completeEvents = normalized.split("\n\n");
+  const remainder = completeEvents.pop() ?? "";
+  return { completeEvents, remainder: endsWithCarriageReturn ? `${remainder}\r` : remainder };
+}
 
 // libs/testing/src/platform/platform-client-info.ts
 var MCP_APPS_EXTENSION_KEY = "io.modelcontextprotocol/ui";
@@ -1792,7 +1884,8 @@ var McpTestClientBuilder = class {
     return this;
   }
   /**
-   * Set the MCP protocol version to request
+   * Set the MCP protocol version to request (default '2025-06-18').
+   * '2026-07-28' has no initialize handshake, so `build()` throws for it.
    */
   withProtocolVersion(version) {
     this.config.protocolVersion = version;
@@ -1888,6 +1981,7 @@ var McpTestClientBuilder = class {
 // libs/testing/src/client/mcp-test-client.ts
 var DEFAULT_TIMEOUT2 = 3e4;
 var DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+var UNSUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28"];
 var DEFAULT_CLIENT_INFO = {
   name: "@frontmcp/testing",
   version: "0.4.0"
@@ -1924,6 +2018,8 @@ var McpTestClient = class {
   _traces = [];
   _notifications = [];
   _progressUpdates = [];
+  collectingProgress = false;
+  progressTokenCounter = 0;
   // Interceptor chain
   _interceptors;
   // Elicitation handler for server→client elicit requests
@@ -1932,6 +2028,11 @@ var McpTestClient = class {
   // CONSTRUCTOR & FACTORY
   // ═══════════════════════════════════════════════════════════════════
   constructor(config) {
+    if (config.protocolVersion && UNSUPPORTED_PROTOCOL_VERSIONS.includes(config.protocolVersion)) {
+      throw new Error(
+        `McpTestClient does not support protocol version ${config.protocolVersion}: it has no initialize handshake. Use ${DEFAULT_PROTOCOL_VERSION} or earlier.`
+      );
+    }
     this.config = {
       baseUrl: config.baseUrl,
       entryPath: config.entryPath,
@@ -2017,6 +2118,7 @@ var McpTestClient = class {
       jsonrpc: "2.0",
       method: "notifications/initialized"
     });
+    await this.transport.openNotificationStream?.(this.initResult.protocolVersion);
     this.log("info", `Connected to ${this.initResult.serverInfo?.name ?? "MCP Server"}`);
     return this.initResult;
   }
@@ -2127,8 +2229,8 @@ var McpTestClient = class {
     /**
      * Call a tool by name with arguments
      */
-    call: async (name, args) => {
-      const response = await this.callTool(name, args);
+    call: async (name, args, options = {}) => {
+      const response = await this.callTool(name, args, this.progressTokenFor(options));
       return this.wrapToolResult(response);
     }
   };
@@ -2270,6 +2372,7 @@ var McpTestClient = class {
      * Collect progress notifications specifically
      */
     collectProgress: () => {
+      this.collectingProgress = true;
       return new ProgressCollector(this._progressUpdates);
     },
     /**
@@ -2575,12 +2678,29 @@ var McpTestClient = class {
   async listTools() {
     return this.request("tools/list", {});
   }
-  async callTool(name, args) {
+  async callTool(name, args, progressToken) {
     return this.request("tools/call", {
       name,
-      arguments: args ?? {}
+      arguments: args ?? {},
+      ...progressToken !== void 0 && { _meta: { progressToken } }
     });
   }
+  progressTokenFor(options) {
+    if (options.progressToken !== void 0) return options.progressToken;
+    return this.collectingProgress ? `progress-${++this.progressTokenCounter}` : void 0;
+  }
+  recordNotification = (notification) => {
+    const timestamp = /* @__PURE__ */ new Date();
+    this._notifications.push({ method: notification.method, params: notification.params, timestamp });
+    if (notification.method !== "notifications/progress") return;
+    const { progress, total, progressToken } = notification.params ?? {};
+    this._progressUpdates.push({
+      progress: Number(progress),
+      total: typeof total === "number" ? total : void 0,
+      progressToken: typeof progressToken === "string" || typeof progressToken === "number" ? progressToken : void 0,
+      timestamp
+    });
+  };
   async listResources() {
     return this.request("resources/list", {});
   }
@@ -2627,7 +2747,8 @@ var McpTestClient = class {
           debug: this.config.debug,
           interceptors: this._interceptors,
           clientInfo: this.config.clientInfo,
-          elicitationHandler: this._elicitationHandler
+          elicitationHandler: this._elicitationHandler,
+          notificationHandler: this.recordNotification
         });
       case "sse":
         throw new Error("SSE transport not yet implemented");

package/esm/setup.mjs

@@ -397,18 +397,17 @@ var init_mcp_matchers = __esm({
           message: () => `Expected a result wrapper object with isError property`
         };
       }
-      let pass = result.isError;
-      if (pass && expectedCode !== void 0) {
-        pass = result.error?.code === expectedCode;
-      }
+      const receivedCode = typeof expectedCode === "string" ? result.raw?._meta?.["code"] : result.error?.code;
+      const codeMatches = expectedCode === void 0 || receivedCode === expectedCode;
+      const pass = result.isError && codeMatches;
       return {
         pass,
         message: () => {
           if (!result.isError) {
             return "Expected result to be an error, but it was successful";
           }
-          if (expectedCode !== void 0 && result.error?.code !== expectedCode) {
-            return `Expected error code ${expectedCode}, but got ${result.error?.code}`;
+          if (!codeMatches) {
+            return `Expected error code ${expectedCode}, but got ${String(receivedCode)}`;
           }
           return "Expected result not to be an error";
         }