feat(waitforpendingrequests): add waitForPendingRequests api

Author: unadlib

README.md

@@ -189,6 +189,14 @@ await page.route("**/api/users", async (route) => {
 
 Batch behaviour stays automatic: additional `requestMock` calls issued in the same macrotask are grouped, forwarded, and resolved together.
 
+Need to pause the test until everything in-flight resolves? Call `waitForPendingRequests` to block on the current set of pending requests (anything started after the call is not included):
+
+```ts
+// After routing a few requests
+await mockClient.waitForPendingRequests();
+// Safe to assert on the results produced by the mocked responses
+```
+
 ## Describe Requests with Metadata
 
 `requestMock` accepts an optional third argument (`RequestMockOptions`) that is forwarded without modification to the MCP server. The most important field in that object is `metadata`, which lets the test process describe each request with the exact OpenAPI/JSON Schema fragment, sample payloads, or test context that the AI client needs to build a response.
@@ -261,6 +269,7 @@ The library exports primitives so you can embed the workflow inside bespoke runn
 
 - `TestMockMCPServer` starts and stops the WebSocket plus MCP tooling bridge programmatically.
 - `BatchMockCollector` provides a low-level batching client used directly inside test environments.
+- `BatchMockCollector.waitForPendingRequests()` waits for the currently pending mock requests to settle (resolves when all finish, rejects if any fail).
 - `connect(options)` instantiates `BatchMockCollector` and waits for the WebSocket connection to open.
 
 Each class accepts logger overrides, timeout tweaks, and other ergonomics surfaced in the technical design.

src/client/batch-mock-collector.ts

@@ -56,6 +56,7 @@ interface PendingRequest {
   resolve: (data: unknown) => void;
   reject: (error: Error) => void;
   timeoutId: NodeJS.Timeout;
+  completion: Promise<PromiseSettledResult<void>>;
 }
 
 const DEFAULT_TIMEOUT = 60_000;
@@ -132,10 +133,15 @@ export class BatchMockCollector {
       metadata: options.metadata,
     };
 
+    let settleCompletion!: (result: PromiseSettledResult<void>) => void;
+    const completion = new Promise<PromiseSettledResult<void>>((resolve) => {
+      settleCompletion = resolve;
+    });
+
     return new Promise<T>((resolve, reject) => {
       const timeoutId = setTimeout(() => {
-        this.pendingRequests.delete(requestId);
-        reject(
+        this.rejectRequest(
+          requestId,
           new Error(
             `Mock request timed out after ${this.timeout}ms: ${method} ${endpoint}`
           )
@@ -145,18 +151,40 @@ export class BatchMockCollector {
       this.pendingRequests.set(requestId, {
         request,
         resolve: (data) => {
+          settleCompletion({ status: "fulfilled", value: undefined });
           resolve(data as T);
         },
         reject: (error) => {
+          settleCompletion({ status: "rejected", reason: error });
           reject(error);
         },
         timeoutId,
+        completion,
       });
 
       this.enqueueRequest(requestId);
     });
   }
 
+  /**
+   * Wait for all requests that are currently pending to settle. Requests
+   * created after this method is called are not included.
+   */
+  async waitForPendingRequests(): Promise<void> {
+    const pendingCompletions = Array.from(this.pendingRequests.values()).map(
+      (pending) => pending.completion
+    );
+
+    const results = await Promise.all(pendingCompletions);
+    const rejected = results.find(
+      (result): result is PromiseRejectedResult => result.status === "rejected"
+    );
+
+    if (rejected) {
+      throw rejected.reason;
+    }
+  }
+
   /**
    * Close the underlying connection and fail all pending requests.
    */

test/index.test.ts

@@ -122,6 +122,45 @@ describe("BatchMockCollector", () => {
 
     await collector.close();
   });
+
+  it("waits for pending requests to settle", async () => {
+    wss = new WebSocketServer({ port: 0 });
+    const address = wss.address() as AddressInfo;
+
+    wss.on("connection", (socket) => {
+      socket.on("message", (data) => {
+        const message = JSON.parse(data.toString()) as BatchMockRequestMessage;
+        setTimeout(() => {
+          const response: BatchMockResponseMessage = {
+            type: BATCH_MOCK_RESPONSE,
+            batchId: "batch-test",
+            mocks: message.requests.map((request) => ({
+              requestId: request.requestId,
+              data: { endpoint: request.endpoint },
+            })),
+          };
+          socket.send(JSON.stringify(response));
+        }, 5);
+      });
+    });
+
+    const collector = await connect({
+      port: address.port,
+      timeout: 1_000,
+      batchDebounceMs: 0,
+    });
+
+    const usersPromise = collector.requestMock("/api/users", "GET");
+    const ordersPromise = collector.requestMock("/api/orders", "GET");
+
+    await collector.waitForPendingRequests();
+    const [users, orders] = await Promise.all([usersPromise, ordersPromise]);
+
+    expect(users).toEqual({ endpoint: "/api/users" });
+    expect(orders).toEqual({ endpoint: "/api/orders" });
+
+    await collector.close();
+  });
 });
 
 describe("TestMockMCPServer", () => {