@frontmcp/testing 0.7.1 → 0.8.0

package/esm/fixtures/index.mjs

@@ -52,7 +52,12 @@ function getPlatformClientInfo(platform) {
 }
 function getPlatformCapabilities(platform) {
   const baseCapabilities = {
-    sampling: {}
+    sampling: {},
+    // Include elicitation.form by default for testing elicitation workflows
+    // Note: MCP SDK expects form to be an object, not boolean
+    elicitation: {
+      form: {}
+    }
   };
   if (platform === "ext-apps") {
     return {
@@ -190,6 +195,21 @@ var McpTestClientBuilder = class {
     this.config.capabilities = capabilities;
     return this;
   }
+  /**
+   * Set query parameters to append to the connection URL.
+   * Useful for testing mode switches like `?mode=skills_only`.
+   *
+   * @example
+   * ```typescript
+   * const client = await McpTestClient.create({ baseUrl })
+   *   .withQueryParams({ mode: 'skills_only' })
+   *   .buildAndConnect();
+   * ```
+   */
+  withQueryParams(params) {
+    this.config.queryParams = { ...this.config.queryParams, ...params };
+    return this;
+  }
   /**
    * Build the McpTestClient instance (does not connect)
    */
@@ -218,6 +238,7 @@ var StreamableHttpTransport = class {
   lastRequestHeaders = {};
   interceptors;
   publicMode;
+  elicitationHandler;
   constructor(config) {
     this.config = {
       baseUrl: config.baseUrl.replace(/\/$/, ""),
@@ -232,6 +253,7 @@ var StreamableHttpTransport = class {
     this.authToken = config.auth?.token;
     this.interceptors = config.interceptors;
     this.publicMode = config.publicMode ?? false;
+    this.elicitationHandler = config.elicitationHandler;
   }
   async connect() {
     this.state = "connecting";
@@ -324,7 +346,6 @@ var StreamableHttpTransport = class {
         body: JSON.stringify(message),
         signal: controller.signal
       });
-      clearTimeout(timeoutId);
       const newSessionId = response.headers.get("mcp-session-id");
       if (newSessionId) {
         this.sessionId = newSessionId;
@@ -344,28 +365,26 @@ var StreamableHttpTransport = class {
         };
       } else {
         const contentType = response.headers.get("content-type") ?? "";
-        const text = await response.text();
-        this.log("Response:", text);
-        if (!text.trim()) {
-          jsonResponse = {
-            jsonrpc: "2.0",
-            id: message.id ?? null,
-            result: void 0
-          };
-        } else if (contentType.includes("text/event-stream")) {
-          const { response: sseResponse, sseSessionId } = this.parseSSEResponseWithSession(text, message.id);
-          jsonResponse = sseResponse;
-          if (sseSessionId && !this.sessionId) {
-            this.sessionId = sseSessionId;
-            this.log("Session ID from SSE:", this.sessionId);
-          }
+        if (contentType.includes("text/event-stream")) {
+          jsonResponse = await this.handleSSEResponseWithElicitation(response, message);
         } else {
-          jsonResponse = JSON.parse(text);
+          const text = await response.text();
+          this.log("Response:", text);
+          if (!text.trim()) {
+            jsonResponse = {
+              jsonrpc: "2.0",
+              id: message.id ?? null,
+              result: void 0
+            };
+          } else {
+            jsonResponse = JSON.parse(text);
+          }
         }
       }
       if (this.interceptors) {
         jsonResponse = await this.interceptors.processResponse(message, jsonResponse, Date.now() - startTime);
       }
+      clearTimeout(timeoutId);
       return jsonResponse;
     } catch (error) {
       clearTimeout(timeoutId);
@@ -480,6 +499,9 @@ var StreamableHttpTransport = class {
   getInterceptors() {
     return this.interceptors;
   }
+  setElicitationHandler(handler) {
+    this.elicitationHandler = handler;
+  }
   getConnectionCount() {
     return this.connectionCount;
   }
@@ -508,6 +530,215 @@ var StreamableHttpTransport = class {
   // ═══════════════════════════════════════════════════════════════════
   // PRIVATE HELPERS
   // ═══════════════════════════════════════════════════════════════════
+  /**
+   * Handle SSE response with elicitation support.
+   *
+   * Streams the SSE response, detects elicitation/create requests, and handles them
+   * by calling the registered handler and sending the response back to the server.
+   */
+  async handleSSEResponseWithElicitation(response, originalRequest) {
+    this.log("handleSSEResponseWithElicitation: starting", { requestId: originalRequest.id });
+    const reader = response.body?.getReader();
+    if (!reader) {
+      this.log("handleSSEResponseWithElicitation: no response body");
+      return {
+        jsonrpc: "2.0",
+        id: originalRequest.id ?? null,
+        error: { code: -32e3, message: "No response body" }
+      };
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let finalResponse = null;
+    let sseSessionId;
+    try {
+      let readCount = 0;
+      while (true) {
+        readCount++;
+        this.log(`handleSSEResponseWithElicitation: reading chunk ${readCount}`);
+        const { done, value } = await reader.read();
+        this.log(`handleSSEResponseWithElicitation: read result`, { done, valueLength: value?.length });
+        if (done) {
+          if (buffer.trim()) {
+            const parsed = this.parseSSEEvents(buffer, originalRequest.id);
+            for (const event of parsed.events) {
+              const handled = await this.handleSSEEvent(event);
+              if (handled.isFinal) {
+                finalResponse = handled.response;
+              }
+            }
+            if (parsed.sessionId && !sseSessionId) {
+              sseSessionId = parsed.sessionId;
+            }
+          }
+          break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const eventEndPattern = /\n\n/g;
+        let lastEventEnd = 0;
+        let match;
+        while ((match = eventEndPattern.exec(buffer)) !== null) {
+          const eventText = buffer.slice(lastEventEnd, match.index);
+          lastEventEnd = match.index + 2;
+          if (eventText.trim()) {
+            const parsed = this.parseSSEEvents(eventText, originalRequest.id);
+            for (const event of parsed.events) {
+              const handled = await this.handleSSEEvent(event);
+              if (handled.isFinal) {
+                finalResponse = handled.response;
+              }
+            }
+            if (parsed.sessionId && !sseSessionId) {
+              sseSessionId = parsed.sessionId;
+            }
+          }
+        }
+        buffer = buffer.slice(lastEventEnd);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    if (sseSessionId && !this.sessionId) {
+      this.sessionId = sseSessionId;
+      this.log("Session ID from SSE:", this.sessionId);
+    }
+    if (finalResponse) {
+      return finalResponse;
+    }
+    return {
+      jsonrpc: "2.0",
+      id: originalRequest.id ?? null,
+      error: { code: -32e3, message: "No final response received in SSE stream" }
+    };
+  }
+  /**
+   * Parse SSE event text into structured events
+   */
+  parseSSEEvents(text, _requestId) {
+    const lines = text.split("\n");
+    const events = [];
+    let currentEvent = { type: "message", data: [] };
+    let sessionId;
+    for (const line of lines) {
+      if (line.startsWith("event: ")) {
+        currentEvent.type = line.slice(7);
+      } else if (line.startsWith("data: ")) {
+        currentEvent.data.push(line.slice(6));
+      } else if (line === "data:") {
+        currentEvent.data.push("");
+      } else if (line.startsWith("id: ")) {
+        const idValue = line.slice(4);
+        currentEvent.id = idValue;
+        const colonIndex = idValue.lastIndexOf(":");
+        if (colonIndex > 0) {
+          sessionId = idValue.substring(0, colonIndex);
+        } else {
+          sessionId = idValue;
+        }
+      } else if (line === "" && currentEvent.data.length > 0) {
+        events.push({
+          type: currentEvent.type,
+          data: currentEvent.data.join("\n"),
+          id: currentEvent.id
+        });
+        currentEvent = { type: "message", data: [] };
+      }
+    }
+    if (currentEvent.data.length > 0) {
+      events.push({
+        type: currentEvent.type,
+        data: currentEvent.data.join("\n"),
+        id: currentEvent.id
+      });
+    }
+    return { events, sessionId };
+  }
+  /**
+   * Handle a single SSE event, including elicitation requests
+   */
+  async handleSSEEvent(event) {
+    this.log("SSE Event:", { type: event.type, data: event.data.slice(0, 200) });
+    try {
+      const parsed = JSON.parse(event.data);
+      if ("method" in parsed && parsed.method === "elicitation/create") {
+        await this.handleElicitationRequest(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 };
+      }
+      return {
+        isFinal: false,
+        response: { jsonrpc: "2.0", id: null, result: void 0 }
+      };
+    } catch {
+      this.log("Failed to parse SSE event data:", event.data);
+      return {
+        isFinal: false,
+        response: { jsonrpc: "2.0", id: null, result: void 0 }
+      };
+    }
+  }
+  /**
+   * Handle an elicitation/create request from the server
+   */
+  async handleElicitationRequest(request) {
+    const params = request.params;
+    this.log("Elicitation request received:", {
+      mode: params?.mode,
+      message: params?.message?.slice(0, 100)
+    });
+    const requestId = request.id;
+    if (requestId === void 0 || requestId === null) {
+      this.log("Elicitation request has no ID, cannot respond");
+      return;
+    }
+    if (!this.elicitationHandler) {
+      this.log("No elicitation handler registered, sending error");
+      await this.sendElicitationResponse(requestId, {
+        action: "decline"
+      });
+      return;
+    }
+    try {
+      const response = await this.elicitationHandler(params);
+      this.log("Elicitation handler response:", response);
+      await this.sendElicitationResponse(requestId, response);
+    } catch (error) {
+      this.log("Elicitation handler error:", error);
+      await this.sendElicitationResponse(requestId, {
+        action: "cancel"
+      });
+    }
+  }
+  /**
+   * Send an elicitation response back to the server
+   */
+  async sendElicitationResponse(requestId, response) {
+    const headers = this.buildHeaders();
+    const url = `${this.config.baseUrl}/`;
+    const rpcResponse = {
+      jsonrpc: "2.0",
+      id: requestId,
+      result: response
+    };
+    this.log("Sending elicitation response:", rpcResponse);
+    try {
+      const fetchResponse = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(rpcResponse)
+      });
+      if (!fetchResponse.ok) {
+        this.log(`Elicitation response HTTP error: ${fetchResponse.status}`);
+      }
+    } catch (error) {
+      this.log("Failed to send elicitation response:", error);
+    }
+  }
   buildHeaders() {
     const headers = {
       "Content-Type": "application/json",
@@ -875,7 +1106,7 @@ var DEFAULT_CLIENT_INFO = {
   version: "0.4.0"
 };
 var McpTestClient = class {
-  // Platform and capabilities are optional - only set when testing platform-specific behavior
+  // Platform, capabilities, and queryParams are optional - only set when needed
   config;
   transport = null;
   initResult = null;
@@ -891,6 +1122,8 @@ var McpTestClient = class {
   _progressUpdates = [];
   // Interceptor chain
   _interceptors;
+  // Elicitation handler for server→client elicit requests
+  _elicitationHandler;
   // ═══════════════════════════════════════════════════════════════════
   // CONSTRUCTOR & FACTORY
   // ═══════════════════════════════════════════════════════════════════
@@ -905,7 +1138,8 @@ var McpTestClient = class {
       protocolVersion: config.protocolVersion ?? DEFAULT_PROTOCOL_VERSION,
       clientInfo: config.clientInfo ?? DEFAULT_CLIENT_INFO,
       platform: config.platform,
-      capabilities: config.capabilities
+      capabilities: config.capabilities,
+      queryParams: config.queryParams
     };
     if (config.auth?.token) {
       this._authState = {
@@ -1138,9 +1372,9 @@ var McpTestClient = class {
      * Send any JSON-RPC request
      */
     request: async (message) => {
-      this.ensureConnected();
+      const transport = this.getConnectedTransport();
       const start = Date.now();
-      const response = await this.transport.request(message);
+      const response = await transport.request(message);
       this.traceRequest(message.method, message.params, message.id, response, Date.now() - start);
       return response;
     },
@@ -1148,15 +1382,15 @@ var McpTestClient = class {
      * Send a notification (no response expected)
      */
     notify: async (message) => {
-      this.ensureConnected();
-      await this.transport.notify(message);
+      const transport = this.getConnectedTransport();
+      await transport.notify(message);
     },
     /**
      * Send raw string data (for error testing)
      */
     sendRaw: async (data) => {
-      this.ensureConnected();
-      return this.transport.sendRaw(data);
+      const transport = this.getConnectedTransport();
+      return transport.sendRaw(data);
     }
   };
   get lastRequestId() {
@@ -1212,6 +1446,63 @@ var McpTestClient = class {
     }
   };
   // ═══════════════════════════════════════════════════════════════════
+  // ELICITATION
+  // ═══════════════════════════════════════════════════════════════════
+  /**
+   * Register a handler for elicitation requests from the server.
+   *
+   * When a tool calls `this.elicit()` during execution, the server sends an
+   * `elicitation/create` request to the client. This handler is called to
+   * provide the response that would normally come from user interaction.
+   *
+   * @param handler - Function that receives the elicitation request and returns a response
+   *
+   * @example
+   * ```typescript
+   * // Simple acceptance
+   * mcp.onElicitation(async () => ({
+   *   action: 'accept',
+   *   content: { confirmed: true }
+   * }));
+   *
+   * // Conditional response based on request
+   * mcp.onElicitation(async (request) => {
+   *   if (request.message.includes('delete')) {
+   *     return { action: 'decline' };
+   *   }
+   *   return { action: 'accept', content: { approved: true } };
+   * });
+   *
+   * // Multi-step wizard
+   * let step = 0;
+   * mcp.onElicitation(async () => {
+   *   step++;
+   *   if (step === 1) return { action: 'accept', content: { name: 'Alice' } };
+   *   return { action: 'accept', content: { color: 'blue' } };
+   * });
+   * ```
+   */
+  onElicitation(handler) {
+    this._elicitationHandler = handler;
+    if (this.transport?.setElicitationHandler) {
+      this.transport.setElicitationHandler(handler);
+    }
+    this.log("debug", "Elicitation handler registered");
+  }
+  /**
+   * Clear the elicitation handler.
+   *
+   * After calling this, elicitation requests from the server will not be
+   * handled automatically. This can be used to test timeout scenarios.
+   */
+  clearElicitationHandler() {
+    this._elicitationHandler = void 0;
+    if (this.transport?.setElicitationHandler) {
+      this.transport.setElicitationHandler(void 0);
+    }
+    this.log("debug", "Elicitation handler cleared");
+  }
+  // ═══════════════════════════════════════════════════════════════════
   // LOGGING & DEBUGGING
   // ═══════════════════════════════════════════════════════════════════
   logs = {
@@ -1436,7 +1727,10 @@ var McpTestClient = class {
   // ═══════════════════════════════════════════════════════════════════
   async initialize() {
     const capabilities = this.config.capabilities ?? {
-      sampling: {}
+      sampling: {},
+      elicitation: {
+        form: {}
+      }
     };
     return this.request("initialize", {
       protocolVersion: this.config.protocolVersion,
@@ -1475,16 +1769,25 @@ var McpTestClient = class {
   // PRIVATE: TRANSPORT & REQUEST HELPERS
   // ═══════════════════════════════════════════════════════════════════
   createTransport() {
+    let baseUrl = this.config.baseUrl;
+    if (this.config.queryParams && Object.keys(this.config.queryParams).length > 0) {
+      const url = new URL(baseUrl);
+      Object.entries(this.config.queryParams).forEach(([key, value]) => {
+        url.searchParams.set(key, String(value));
+      });
+      baseUrl = url.toString();
+    }
     switch (this.config.transport) {
       case "streamable-http":
         return new StreamableHttpTransport({
-          baseUrl: this.config.baseUrl,
+          baseUrl,
           timeout: this.config.timeout,
           auth: this.config.auth,
           publicMode: this.config.publicMode,
           debug: this.config.debug,
           interceptors: this._interceptors,
-          clientInfo: this.config.clientInfo
+          clientInfo: this.config.clientInfo,
+          elicitationHandler: this._elicitationHandler
         });
       case "sse":
         throw new Error("SSE transport not yet implemented");
@@ -1493,12 +1796,12 @@ var McpTestClient = class {
     }
   }
   async request(method, params) {
-    this.ensureConnected();
+    const transport = this.getConnectedTransport();
     const id = ++this.requestIdCounter;
     this._lastRequestId = id;
     const start = Date.now();
     try {
-      const response = await this.transport.request({
+      const response = await transport.request({
         jsonrpc: "2.0",
         id,
         method,
@@ -1537,10 +1840,14 @@ var McpTestClient = class {
       };
     }
   }
-  ensureConnected() {
-    if (!this.transport?.isConnected()) {
+  /**
+   * Get the transport, throwing if not connected.
+   */
+  getConnectedTransport() {
+    if (!this.transport || !this.transport.isConnected()) {
       throw new Error("Not connected to MCP server. Call connect() first.");
     }
+    return this.transport;
   }
   updateSessionActivity() {
     if (this._sessionInfo) {
@@ -1793,6 +2100,9 @@ var TestTokenFactory = class {
       scope: options.scopes?.join(" "),
       ...options.claims
     };
+    if (!this.privateKey) {
+      throw new Error("Private key not initialized");
+    }
     const token = await new SignJWT(payload).setProtectedHeader({ alg: "RS256", kid: this.keyId }).sign(this.privateKey);
     return token;
   }
@@ -1852,6 +2162,9 @@ var TestTokenFactory = class {
       exp: now - 3600
       // Expired 1 hour ago
     };
+    if (!this.privateKey) {
+      throw new Error("Private key not initialized");
+    }
     const token = await new SignJWT(payload).setProtectedHeader({ alg: "RS256", kid: this.keyId }).sign(this.privateKey);
     return token;
   }
@@ -1878,6 +2191,9 @@ var TestTokenFactory = class {
    */
   async getPublicJwks() {
     await this.ensureKeys();
+    if (!this.jwk) {
+      throw new Error("JWK not initialized");
+    }
     return {
       keys: [this.jwk]
     };
@@ -1898,21 +2214,195 @@ var TestTokenFactory = class {
 
 // libs/testing/src/server/test-server.ts
 import { spawn } from "child_process";
+
+// libs/testing/src/errors/index.ts
+var TestClientError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TestClientError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ServerStartError = class extends TestClientError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ServerStartError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// libs/testing/src/server/port-registry.ts
+import { createServer } from "net";
+var E2E_PORT_RANGES = {
+  // Core E2E tests (50000-50099)
+  "demo-e2e-public": { start: 5e4, size: 10 },
+  "demo-e2e-cache": { start: 50010, size: 10 },
+  "demo-e2e-config": { start: 50020, size: 10 },
+  "demo-e2e-direct": { start: 50030, size: 10 },
+  "demo-e2e-errors": { start: 50040, size: 10 },
+  "demo-e2e-hooks": { start: 50050, size: 10 },
+  "demo-e2e-multiapp": { start: 50060, size: 10 },
+  "demo-e2e-notifications": { start: 50070, size: 10 },
+  "demo-e2e-providers": { start: 50080, size: 10 },
+  "demo-e2e-standalone": { start: 50090, size: 10 },
+  // Auth E2E tests (50100-50199)
+  "demo-e2e-orchestrated": { start: 50100, size: 10 },
+  "demo-e2e-transparent": { start: 50110, size: 10 },
+  "demo-e2e-cimd": { start: 50120, size: 10 },
+  // Feature E2E tests (50200-50299)
+  "demo-e2e-skills": { start: 50200, size: 10 },
+  "demo-e2e-remote": { start: 50210, size: 10 },
+  "demo-e2e-openapi": { start: 50220, size: 10 },
+  "demo-e2e-ui": { start: 50230, size: 10 },
+  "demo-e2e-codecall": { start: 50240, size: 10 },
+  "demo-e2e-remember": { start: 50250, size: 10 },
+  "demo-e2e-elicitation": { start: 50260, size: 10 },
+  "demo-e2e-agents": { start: 50270, size: 10 },
+  "demo-e2e-transport-recreation": { start: 50280, size: 10 },
+  // Infrastructure E2E tests (50300-50399)
+  "demo-e2e-redis": { start: 50300, size: 10 },
+  "demo-e2e-serverless": { start: 50310, size: 10 },
+  // Mock servers and utilities (50900-50999)
+  "mock-oauth": { start: 50900, size: 10 },
+  "mock-api": { start: 50910, size: 10 },
+  "mock-cimd": { start: 50920, size: 10 },
+  // Dynamic/unknown projects (51000+)
+  default: { start: 51e3, size: 100 }
+};
+var reservedPorts = /* @__PURE__ */ new Map();
+var projectPortIndex = /* @__PURE__ */ new Map();
+function getPortRange(project) {
+  const key = project;
+  if (key in E2E_PORT_RANGES) {
+    return E2E_PORT_RANGES[key];
+  }
+  return E2E_PORT_RANGES.default;
+}
+async function reservePort(project, preferredPort) {
+  const range = getPortRange(project);
+  if (preferredPort !== void 0) {
+    const reservation = await tryReservePort(preferredPort, project);
+    if (reservation) {
+      return {
+        port: preferredPort,
+        release: async () => {
+          await releasePort(preferredPort);
+        }
+      };
+    }
+    console.warn(`[PortRegistry] Preferred port ${preferredPort} not available for ${project}, allocating from range`);
+  }
+  let index = projectPortIndex.get(project) ?? 0;
+  const maxAttempts = range.size;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const port = range.start + index % range.size;
+    index = (index + 1) % range.size;
+    if (reservedPorts.has(port)) {
+      continue;
+    }
+    const reservation = await tryReservePort(port, project);
+    if (reservation) {
+      projectPortIndex.set(project, index);
+      return {
+        port,
+        release: async () => {
+          await releasePort(port);
+        }
+      };
+    }
+  }
+  const dynamicPort = await findAvailablePortInRange(51e3, 52e3);
+  if (dynamicPort) {
+    const reservation = await tryReservePort(dynamicPort, project);
+    if (reservation) {
+      return {
+        port: dynamicPort,
+        release: async () => {
+          await releasePort(dynamicPort);
+        }
+      };
+    }
+  }
+  throw new Error(
+    `[PortRegistry] Could not reserve a port for ${project}. Range: ${range.start}-${range.start + range.size - 1}. Currently reserved: ${Array.from(reservedPorts.keys()).join(", ")}`
+  );
+}
+async function tryReservePort(port, project) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.listen(port, "::", () => {
+      reservedPorts.set(port, {
+        port,
+        project,
+        holder: server,
+        reservedAt: Date.now()
+      });
+      resolve(true);
+    });
+  });
+}
+async function releasePort(port) {
+  const reservation = reservedPorts.get(port);
+  if (!reservation) {
+    return;
+  }
+  return new Promise((resolve) => {
+    reservation.holder.close(() => {
+      reservedPorts.delete(port);
+      resolve();
+    });
+  });
+}
+async function findAvailablePortInRange(start, end) {
+  for (let port = start; port < end; port++) {
+    if (reservedPorts.has(port)) {
+      continue;
+    }
+    const available = await isPortAvailable(port);
+    if (available) {
+      return port;
+    }
+  }
+  return null;
+}
+async function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.listen(port, "::", () => {
+      server.close(() => {
+        resolve(true);
+      });
+    });
+  });
+}
+
+// libs/testing/src/server/test-server.ts
+var DEBUG_SERVER = process.env["DEBUG_SERVER"] === "1" || process.env["DEBUG"] === "1";
 var TestServer = class _TestServer {
   process = null;
   options;
   _info;
   logs = [];
-  constructor(options, port) {
+  portRelease = null;
+  constructor(options, port, portRelease) {
     this.options = {
       port,
+      project: options.project,
       command: options.command ?? "",
       cwd: options.cwd ?? process.cwd(),
       env: options.env ?? {},
       startupTimeout: options.startupTimeout ?? 3e4,
       healthCheckPath: options.healthCheckPath ?? "/health",
-      debug: options.debug ?? false
+      debug: options.debug ?? DEBUG_SERVER
     };
+    this.portRelease = portRelease ?? null;
     this._info = {
       baseUrl: `http://localhost:${port}`,
       port
@@ -1922,7 +2412,9 @@ var TestServer = class _TestServer {
    * Start a test server with custom command
    */
   static async start(options) {
-    const port = options.port ?? await findAvailablePort();
+    const project = options.project ?? "default";
+    const { port, release } = await reservePort(project, options.port);
+    await release();
     const server = new _TestServer(options, port);
     try {
       await server.startProcess();
@@ -1941,10 +2433,12 @@ var TestServer = class _TestServer {
         `Invalid project name: ${project}. Must contain only alphanumeric, underscore, and hyphen characters.`
       );
     }
-    const port = options.port ?? await findAvailablePort();
+    const { port, release } = await reservePort(project, options.port);
+    await release();
     const serverOptions = {
       ...options,
       port,
+      project,
       command: `npx nx serve ${project} --port ${port}`,
       cwd: options.cwd ?? process.cwd()
     };
@@ -2102,22 +2596,54 @@ var TestServer = class _TestServer {
       exitCode = code;
       this.log(`Server process exited with code ${code}`);
     });
-    await this.waitForReadyWithExitDetection(() => {
-      if (exitError) {
-        return { exited: true, error: exitError };
-      }
-      if (processExited) {
-        const recentLogs = this.logs.slice(-10).join("\n");
-        return {
-          exited: true,
-          error: new Error(`Server process exited unexpectedly with code ${exitCode}.
+    try {
+      await this.waitForReadyWithExitDetection(() => {
+        if (exitError) {
+          return { exited: true, error: exitError };
+        }
+        if (processExited) {
+          const allLogs = this.logs.join("\n");
+          const errorLogs = this.logs.filter((l) => l.includes("[ERROR]") || l.toLowerCase().includes("error")).join("\n");
+          return {
+            exited: true,
+            error: new ServerStartError(
+              `Server process exited unexpectedly with code ${exitCode}.
 
-Recent logs:
-${recentLogs}`)
-        };
-      }
-      return { exited: false };
-    });
+Command: ${this.options.command}
+CWD: ${this.options.cwd}
+Port: ${this.options.port}
+
+=== Error Logs ===
+${errorLogs || "No error logs captured"}
+
+=== Full Logs ===
+${allLogs || "No logs captured"}`
+            )
+          };
+        }
+        return { exited: false };
+      });
+    } catch (error) {
+      this.printLogsOnFailure("Server startup failed");
+      throw error;
+    }
+  }
+  /**
+   * Print server logs on failure for debugging
+   */
+  printLogsOnFailure(context) {
+    const allLogs = this.logs.join("\n");
+    if (allLogs) {
+      console.error(`
+[TestServer] ${context}`);
+      console.error(`[TestServer] Command: ${this.options.command}`);
+      console.error(`[TestServer] Port: ${this.options.port}`);
+      console.error(`[TestServer] CWD: ${this.options.cwd}`);
+      console.error(`[TestServer] === Server Logs ===
+${allLogs}`);
+      console.error(`[TestServer] === End Logs ===
+`);
+    }
   }
   /**
    * Wait for server to be ready, but also detect early process exit
@@ -2126,29 +2652,57 @@ ${recentLogs}`)
     const timeoutMs = this.options.startupTimeout;
     const deadline = Date.now() + timeoutMs;
     const checkInterval = 100;
+    let lastHealthCheckError = null;
+    let healthCheckAttempts = 0;
+    this.log(`Waiting for server to be ready (timeout: ${timeoutMs}ms)...`);
     while (Date.now() < deadline) {
       const exitStatus = checkExit();
       if (exitStatus.exited) {
-        throw exitStatus.error ?? new Error("Server process exited unexpectedly");
+        throw exitStatus.error ?? new ServerStartError("Server process exited unexpectedly");
       }
+      healthCheckAttempts++;
       try {
-        const response = await fetch(`${this._info.baseUrl}${this.options.healthCheckPath}`, {
+        const healthUrl = `${this._info.baseUrl}${this.options.healthCheckPath}`;
+        const response = await fetch(healthUrl, {
           method: "GET",
           signal: AbortSignal.timeout(1e3)
         });
         if (response.ok || response.status === 404) {
-          this.log("Server is ready");
+          this.log(`Server is ready after ${healthCheckAttempts} health check attempts`);
           return;
         }
-      } catch {
+        lastHealthCheckError = `HTTP ${response.status}: ${response.statusText}`;
+      } catch (err) {
+        lastHealthCheckError = err instanceof Error ? err.message : String(err);
+      }
+      const elapsed = Date.now() - (deadline - timeoutMs);
+      if (elapsed > 0 && elapsed % 5e3 < checkInterval) {
+        this.log(
+          `Still waiting for server... (${Math.round(elapsed / 1e3)}s elapsed, last error: ${lastHealthCheckError})`
+        );
       }
       await sleep2(checkInterval);
     }
     const finalExitStatus = checkExit();
     if (finalExitStatus.exited) {
-      throw finalExitStatus.error ?? new Error("Server process exited unexpectedly");
+      throw finalExitStatus.error ?? new ServerStartError("Server process exited unexpectedly");
     }
-    throw new Error(`Server did not become ready within ${timeoutMs}ms`);
+    const allLogs = this.logs.join("\n");
+    throw new ServerStartError(
+      `Server did not become ready within ${timeoutMs}ms.
+
+Command: ${this.options.command}
+CWD: ${this.options.cwd}
+Port: ${this.options.port}
+Health check URL: ${this._info.baseUrl}${this.options.healthCheckPath}
+Health check attempts: ${healthCheckAttempts}
+Last health check error: ${lastHealthCheckError ?? "none"}
+
+=== Server Logs ===
+${allLogs || "No logs captured"}
+
+TIP: Set DEBUG_SERVER=1 or DEBUG=1 environment variable for verbose output`
+    );
   }
   log(message) {
     if (this.options.debug) {
@@ -2156,22 +2710,6 @@ ${recentLogs}`)
     }
   }
 };
-async function findAvailablePort() {
-  const { createServer } = await import("net");
-  return new Promise((resolve, reject) => {
-    const server = createServer();
-    server.listen(0, () => {
-      const address = server.address();
-      if (address && typeof address !== "string") {
-        const port = address.port;
-        server.close(() => resolve(port));
-      } else {
-        reject(new Error("Could not get port"));
-      }
-    });
-    server.on("error", reject);
-  });
-}
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -2190,14 +2728,36 @@ async function initializeSharedResources() {
       serverInstance = TestServer.connect(currentConfig.baseUrl);
       serverStartedByUs = false;
     } else if (currentConfig.server) {
-      serverInstance = await TestServer.start({
-        port: currentConfig.port,
-        command: resolveServerCommand(currentConfig.server),
-        env: currentConfig.env,
-        startupTimeout: currentConfig.startupTimeout ?? 3e4,
-        debug: currentConfig.logLevel === "debug"
-      });
-      serverStartedByUs = true;
+      const serverCommand = resolveServerCommand(currentConfig.server);
+      const isDebug = currentConfig.logLevel === "debug" || process.env["DEBUG"] === "1" || process.env["DEBUG_SERVER"] === "1";
+      if (isDebug) {
+        console.log(`[TestFixture] Starting server: ${serverCommand}`);
+      }
+      try {
+        serverInstance = await TestServer.start({
+          project: currentConfig.project,
+          port: currentConfig.port,
+          command: serverCommand,
+          env: currentConfig.env,
+          startupTimeout: currentConfig.startupTimeout ?? 3e4,
+          debug: isDebug
+        });
+        serverStartedByUs = true;
+        if (isDebug) {
+          console.log(`[TestFixture] Server started at ${serverInstance.info.baseUrl}`);
+        }
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `Failed to start test server.
+
+Server entry: ${currentConfig.server}
+Project: ${currentConfig.project ?? "default"}
+Command: ${serverCommand}
+
+Error: ${errMsg}`
+        );
+      }
     } else {
       throw new Error(
         'test.use() requires either "server" (entry file path) or "baseUrl" (for external server) option'
@@ -2207,6 +2767,12 @@ async function initializeSharedResources() {
 }
 async function createTestFixtures() {
   await initializeSharedResources();
+  if (!serverInstance) {
+    throw new Error("Server instance not initialized");
+  }
+  if (!tokenFactory) {
+    throw new Error("Token factory not initialized");
+  }
   const clientInstance = await McpTestClient.create({
     baseUrl: serverInstance.info.baseUrl,
     transport: currentConfig.transport ?? "streamable-http",
@@ -2220,7 +2786,19 @@ async function createTestFixtures() {
     server
   };
 }
-async function cleanupTestFixtures(fixtures, _testFailed = false) {
+async function cleanupTestFixtures(fixtures, testFailed = false) {
+  if (testFailed && serverInstance) {
+    const logs = serverInstance.getLogs();
+    if (logs.length > 0) {
+      console.error("\n[TestFixture] === Server Logs (test failed) ===");
+      const recentLogs = logs.slice(-50);
+      if (logs.length > 50) {
+        console.error(`[TestFixture] (showing last 50 of ${logs.length} log entries)`);
+      }
+      console.error(recentLogs.join("\n"));
+      console.error("[TestFixture] === End Server Logs ===\n");
+    }
+  }
   if (fixtures.mcp.isConnected()) {
     await fixtures.mcp.disconnect();
   }