@schmock/core 1.2.2 → 1.3.0

package/dist/builder.d.ts

@@ -11,6 +11,8 @@ export declare class CallableMockInstance {
     private logger;
     private requestHistory;
     private callableRef;
+    private server;
+    private serverInfo;
     constructor(globalConfig?: Schmock.GlobalConfig);
     defineRoute(route: Schmock.RouteKey, generator: Schmock.Generator, config: Schmock.RouteConfig): this;
     setCallableRef(ref: Schmock.CallableMockInstance): void;
@@ -22,6 +24,8 @@ export declare class CallableMockInstance {
     reset(): void;
     resetHistory(): void;
     resetState(): void;
+    listen(port?: number, hostname?: string): Promise<Schmock.ServerInfo>;
+    close(): void;
     handle(method: Schmock.HttpMethod, path: string, options?: Schmock.RequestOptions): Promise<Schmock.Response>;
     /**
      * Apply configured response delay

package/dist/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AA0EA;;;;GAIG;AACH,qBAAa,oBAAoB;IAQnB,OAAO,CAAC,YAAY;IAPhC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA2C;gBAE1C,YAAY,GAAE,OAAO,CAAC,YAAiB;IAa3D,WAAW,CACT,KAAK,EAAE,OAAO,CAAC,QAAQ,EACvB,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,MAAM,EAAE,OAAO,CAAC,WAAW,GAC1B,IAAI;IAqFP,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,oBAAoB,GAAG,IAAI;IAIvD,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI;IAoBlC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE;IAS5E,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAS3D,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAS7D,WAAW,CACT,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAC3B,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,GAAG,SAAS;IAYpC,KAAK,IAAI,IAAI;IAab,YAAY,IAAI,IAAI;IAKpB,UAAU,IAAI,IAAI;IASZ,MAAM,CACV,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,GAC/B,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAoL5B;;;;OAIG;YACW,UAAU;IAcxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAwDrB;;;;;;;;;;OAUG;YACW,iBAAiB;IAqG/B;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IA0BjB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CActB"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AA4EA;;;;GAIG;AACH,qBAAa,oBAAoB;IAUnB,OAAO,CAAC,YAAY;IAThC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA2C;IAC9D,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAiC;gBAE/B,YAAY,GAAE,OAAO,CAAC,YAAiB;IAa3D,WAAW,CACT,KAAK,EAAE,OAAO,CAAC,QAAQ,EACvB,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,MAAM,EAAE,OAAO,CAAC,WAAW,GAC1B,IAAI;IAqFP,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,oBAAoB,GAAG,IAAI;IAIvD,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI;IAoBlC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE;IAS5E,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAS3D,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAS7D,WAAW,CACT,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAC3B,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,GAAG,SAAS;IAYpC,KAAK,IAAI,IAAI;IAcb,YAAY,IAAI,IAAI;IAKpB,UAAU,IAAI,IAAI;IAWlB,MAAM,CAAC,IAAI,SAAI,EAAE,QAAQ,SAAc,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;IAmFrE,KAAK,IAAI,IAAI;IAUP,MAAM,CACV,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,GAC/B,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAoL5B;;;;OAIG;YACW,UAAU;IAcxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAwDrB;;;;;;;;;;OAUG;YACW,iBAAiB;IAqG/B;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IA0BjB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CActB"}

package/dist/builder.js

@@ -1,4 +1,5 @@
-import { isStatusTuple } from "./constants.js";
+import { createServer } from "node:http";
+import { isStatusTuple, toHttpMethod } from "./constants.js";
 import { PluginError, RouteDefinitionError, RouteNotFoundError, SchmockError, } from "./errors.js";
 import { parseRouteKey } from "./parser.js";
 function errorMessage(error) {
@@ -57,6 +58,8 @@ export class CallableMockInstance {
     logger;
     requestHistory = [];
     callableRef;
+    server;
+    serverInfo;
     constructor(globalConfig = {}) {
         this.globalConfig = globalConfig;
         this.logger = new DebugLogger(globalConfig.debug || false);
@@ -181,6 +184,7 @@ export class CallableMockInstance {
     }
     // ===== Reset / Lifecycle =====
     reset() {
+        this.close();
         this.routes = [];
         this.staticRoutes.clear();
         this.plugins = [];
@@ -204,6 +208,82 @@ export class CallableMockInstance {
         }
         this.logger.log("lifecycle", "State cleared");
     }
+    // ===== Standalone Server =====
+    listen(port = 0, hostname = "127.0.0.1") {
+        if (this.server) {
+            throw new SchmockError("Server is already running", "SERVER_ALREADY_RUNNING");
+        }
+        const httpServer = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+            const method = toHttpMethod(req.method ?? "GET");
+            const path = url.pathname;
+            const headers = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                if (typeof value === "string") {
+                    headers[key] = value;
+                }
+            }
+            const query = {};
+            url.searchParams.forEach((value, key) => {
+                query[key] = value;
+            });
+            const chunks = [];
+            req.on("data", (chunk) => chunks.push(chunk));
+            req.on("end", () => {
+                const raw = Buffer.concat(chunks).toString();
+                let body;
+                const contentType = headers["content-type"] ?? "";
+                if (raw && contentType.includes("json")) {
+                    try {
+                        body = JSON.parse(raw);
+                    }
+                    catch {
+                        body = raw;
+                    }
+                }
+                else if (raw) {
+                    body = raw;
+                }
+                void this.handle(method, path, { headers, body, query }).then((schmockResponse) => {
+                    const responseHeaders = {
+                        ...schmockResponse.headers,
+                    };
+                    if (!responseHeaders["content-type"] &&
+                        schmockResponse.body !== undefined &&
+                        typeof schmockResponse.body !== "string") {
+                        responseHeaders["content-type"] = "application/json";
+                    }
+                    const responseBody = schmockResponse.body === undefined
+                        ? undefined
+                        : typeof schmockResponse.body === "string"
+                            ? schmockResponse.body
+                            : JSON.stringify(schmockResponse.body);
+                    res.writeHead(schmockResponse.status, responseHeaders);
+                    res.end(responseBody);
+                });
+            });
+        });
+        this.server = httpServer;
+        return new Promise((resolve, reject) => {
+            httpServer.on("error", reject);
+            httpServer.listen(port, hostname, () => {
+                const addr = httpServer.address();
+                const actualPort = addr !== null && typeof addr === "object" ? addr.port : port;
+                this.serverInfo = { port: actualPort, hostname };
+                this.logger.log("server", `Listening on ${hostname}:${actualPort}`);
+                resolve(this.serverInfo);
+            });
+        });
+    }
+    close() {
+        if (!this.server) {
+            return;
+        }
+        this.server.close();
+        this.server = undefined;
+        this.serverInfo = undefined;
+        this.logger.log("server", "Server stopped");
+    }
     async handle(method, path, options) {
         const requestId = crypto.randomUUID();
         this.logger.log("request", `[${requestId}] ${method} ${path}`, {

package/dist/index.d.ts

@@ -24,5 +24,5 @@
 export declare function schmock(config?: Schmock.GlobalConfig): Schmock.CallableMockInstance;
 export { HTTP_METHODS, isHttpMethod, isStatusTuple, ROUTE_NOT_FOUND_CODE, toHttpMethod, } from "./constants.js";
 export { PluginError, ResourceLimitError, ResponseGenerationError, RouteDefinitionError, RouteNotFoundError, RouteParseError, SchemaGenerationError, SchemaValidationError, SchmockError, } from "./errors.js";
-export type { CallableMockInstance, Generator, GeneratorFunction, GlobalConfig, HttpMethod, Plugin, PluginContext, PluginResult, RequestContext, RequestOptions, RequestRecord, Response, ResponseBody, ResponseResult, RouteConfig, RouteKey, StaticData, } from "./types.js";
+export type { CallableMockInstance, Generator, GeneratorFunction, GlobalConfig, HttpMethod, Plugin, PluginContext, PluginResult, RequestContext, RequestOptions, RequestRecord, Response, ResponseBody, ResponseResult, RouteConfig, RouteKey, ServerInfo, StaticData, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,GAC5B,OAAO,CAAC,oBAAoB,CAiC9B;AAGD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,MAAM,EACN,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,GAC5B,OAAO,CAAC,oBAAoB,CAmC9B;AAGD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,MAAM,EACN,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -42,6 +42,8 @@ export function schmock(config) {
         reset: instance.reset.bind(instance),
         resetHistory: instance.resetHistory.bind(instance),
         resetState: instance.resetState.bind(instance),
+        listen: instance.listen.bind(instance),
+        close: instance.close.bind(instance),
     });
     instance.setCallableRef(callableInstance);
     return callableInstance;

package/dist/types.d.ts

@@ -15,4 +15,5 @@ export type PluginContext = Schmock.PluginContext;
 export type PluginResult = Schmock.PluginResult;
 export type StaticData = Schmock.StaticData;
 export type RequestRecord = Schmock.RequestRecord;
+export type ServerInfo = Schmock.ServerInfo;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;AAC1C,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;AAChE,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AACpC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;AAC1C,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;AAChE,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AACpC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/core",
   "description": "Core functionality for Schmock",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "build": "bun build:lib && bun build:types",
-    "build:lib": "bun build --minify --outdir=dist src/index.ts",
+    "build:lib": "bun build --minify --target node --outdir=dist src/index.ts",
     "build:types": "rm -f tsconfig.tsbuildinfo && tsc --build",
     "pretest": "rm -f src/*.js src/*.d.ts || true",
     "test": "vitest",

package/src/builder.ts

@@ -1,4 +1,6 @@
-import { isStatusTuple } from "./constants.js";
+import type { Server } from "node:http";
+import { createServer } from "node:http";
+import { isStatusTuple, toHttpMethod } from "./constants.js";
 import {
   PluginError,
   RouteDefinitionError,
@@ -84,6 +86,8 @@ export class CallableMockInstance {
   private logger: DebugLogger;
   private requestHistory: Schmock.RequestRecord[] = [];
   private callableRef: Schmock.CallableMockInstance | undefined;
+  private server: Server | undefined;
+  private serverInfo: Schmock.ServerInfo | undefined;
 
   constructor(private globalConfig: Schmock.GlobalConfig = {}) {
     this.logger = new DebugLogger(globalConfig.debug || false);
@@ -254,6 +258,7 @@ export class CallableMockInstance {
   // ===== Reset / Lifecycle =====
 
   reset(): void {
+    this.close();
     this.routes = [];
     this.staticRoutes.clear();
     this.plugins = [];
@@ -280,6 +285,101 @@ export class CallableMockInstance {
     this.logger.log("lifecycle", "State cleared");
   }
 
+  // ===== Standalone Server =====
+
+  listen(port = 0, hostname = "127.0.0.1"): Promise<Schmock.ServerInfo> {
+    if (this.server) {
+      throw new SchmockError(
+        "Server is already running",
+        "SERVER_ALREADY_RUNNING",
+      );
+    }
+
+    const httpServer = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      const method = toHttpMethod(req.method ?? "GET");
+      const path = url.pathname;
+
+      const headers: Record<string, string> = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === "string") {
+          headers[key] = value;
+        }
+      }
+
+      const query: Record<string, string> = {};
+      url.searchParams.forEach((value, key) => {
+        query[key] = value;
+      });
+
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", () => {
+        const raw = Buffer.concat(chunks).toString();
+        let body: unknown;
+        const contentType = headers["content-type"] ?? "";
+        if (raw && contentType.includes("json")) {
+          try {
+            body = JSON.parse(raw);
+          } catch {
+            body = raw;
+          }
+        } else if (raw) {
+          body = raw;
+        }
+
+        void this.handle(method, path, { headers, body, query }).then(
+          (schmockResponse) => {
+            const responseHeaders: Record<string, string> = {
+              ...schmockResponse.headers,
+            };
+            if (
+              !responseHeaders["content-type"] &&
+              schmockResponse.body !== undefined &&
+              typeof schmockResponse.body !== "string"
+            ) {
+              responseHeaders["content-type"] = "application/json";
+            }
+
+            const responseBody =
+              schmockResponse.body === undefined
+                ? undefined
+                : typeof schmockResponse.body === "string"
+                  ? schmockResponse.body
+                  : JSON.stringify(schmockResponse.body);
+
+            res.writeHead(schmockResponse.status, responseHeaders);
+            res.end(responseBody);
+          },
+        );
+      });
+    });
+
+    this.server = httpServer;
+
+    return new Promise((resolve, reject) => {
+      httpServer.on("error", reject);
+      httpServer.listen(port, hostname, () => {
+        const addr = httpServer.address();
+        const actualPort =
+          addr !== null && typeof addr === "object" ? addr.port : port;
+        this.serverInfo = { port: actualPort, hostname };
+        this.logger.log("server", `Listening on ${hostname}:${actualPort}`);
+        resolve(this.serverInfo);
+      });
+    });
+  }
+
+  close(): void {
+    if (!this.server) {
+      return;
+    }
+    this.server.close();
+    this.server = undefined;
+    this.serverInfo = undefined;
+    this.logger.log("server", "Server stopped");
+  }
+
   async handle(
     method: Schmock.HttpMethod,
     path: string,

package/src/index.ts

@@ -52,6 +52,8 @@ export function schmock(
       reset: instance.reset.bind(instance),
       resetHistory: instance.resetHistory.bind(instance),
       resetState: instance.resetState.bind(instance),
+      listen: instance.listen.bind(instance),
+      close: instance.close.bind(instance),
     },
   );
 
@@ -98,5 +100,6 @@ export type {
   ResponseResult,
   RouteConfig,
   RouteKey,
+  ServerInfo,
   StaticData,
 } from "./types.js";

package/src/server.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { schmock } from "./index";
+
+describe("Standalone Server", () => {
+  let mock: Schmock.CallableMockInstance;
+
+  afterEach(() => {
+    mock?.close();
+  });
+
+  it("returns actual port when port=0", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    const info = await mock.listen(0);
+    expect(info.port).toBeGreaterThan(0);
+    expect(info.hostname).toBe("127.0.0.1");
+  });
+
+  it("propagates request headers", async () => {
+    mock = schmock();
+    mock("GET /headers", ({ headers }) => ({
+      auth: headers.authorization,
+    }));
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/headers`, {
+      headers: { authorization: "Bearer secret" },
+    });
+    const body = await res.json();
+    expect(body.auth).toBe("Bearer secret");
+  });
+
+  it("handles concurrent requests", async () => {
+    mock = schmock();
+    mock("GET /slow", () => ({ value: "done" }));
+    const info = await mock.listen(0);
+
+    const results = await Promise.all(
+      Array.from({ length: 10 }, () =>
+        fetch(`http://127.0.0.1:${info.port}/slow`).then((r) => r.json()),
+      ),
+    );
+
+    for (const body of results) {
+      expect(body.value).toBe("done");
+    }
+  });
+
+  it("parses text body when content-type is not JSON", async () => {
+    mock = schmock();
+    mock("POST /text", ({ body: reqBody }) => ({ received: reqBody }));
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/text`, {
+      method: "POST",
+      headers: { "content-type": "text/plain" },
+      body: "hello world",
+    });
+    const resBody = await res.json();
+    expect(resBody.received).toBe("hello world");
+  });
+
+  it("returns 204 with no body for undefined response", async () => {
+    mock = schmock();
+    mock("DELETE /item", () => undefined);
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/item`, {
+      method: "DELETE",
+    });
+    expect(res.status).toBe(204);
+  });
+
+  it("reset stops the server", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/test`);
+    expect(res.status).toBe(200);
+
+    mock.reset();
+
+    try {
+      await fetch(`http://127.0.0.1:${info.port}/test`);
+      expect.unreachable("Should have thrown");
+    } catch {
+      // Expected: connection refused
+    }
+  });
+
+  it("handles route params in server mode", async () => {
+    mock = schmock();
+    mock("GET /users/:id", ({ params }) => ({ id: params.id }));
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/users/42`);
+    const body = await res.json();
+    expect(body.id).toBe("42");
+  });
+
+  it("double listen throws", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    await mock.listen(0);
+    expect(() => mock.listen(0)).toThrow("Server is already running");
+  });
+
+  it("close is idempotent", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    await mock.listen(0);
+    mock.close();
+    expect(() => mock.close()).not.toThrow();
+  });
+});

package/src/steps/standalone-server.steps.ts

@@ -0,0 +1,233 @@
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { expect } from "vitest";
+import { schmock } from "../index";
+
+const feature = await loadFeature("../../features/standalone-server.feature");
+
+describeFeature(feature, ({ Scenario }) => {
+  let mock: Schmock.CallableMockInstance;
+  let serverInfo: Schmock.ServerInfo;
+  let httpResponse: Response;
+
+  function baseUrl(): string {
+    return `http://${serverInfo.hostname}:${serverInfo.port}`;
+  }
+
+  Scenario("Start and stop a simple server", ({ Given, When, Then, And }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    Then("the server should be running", () => {
+      expect(serverInfo.port).toBeGreaterThan(0);
+    });
+
+    When("I fetch {string} from the server", async (_, route: string) => {
+      const [, path] = route.split(" ");
+      httpResponse = await fetch(`${baseUrl()}${path}`);
+    });
+
+    Then("the HTTP response status should be {int}", (_, status: number) => {
+      expect(httpResponse.status).toBe(status);
+    });
+
+    And(
+      "the HTTP response body should have {string} equal to {string}",
+      async (_, key: string, value: string) => {
+        const body = await httpResponse.json();
+        expect(body[key]).toBe(value);
+      },
+    );
+
+    When("I stop the server", () => {
+      mock.close();
+    });
+
+    Then("the server should not be running", async () => {
+      try {
+        await fetch(`${baseUrl()}/hello`);
+        expect.unreachable("Should not be able to connect");
+      } catch {
+        // Connection refused — server is down
+      }
+    });
+  });
+
+  Scenario("Handle POST with JSON body", ({ Given, When, Then, And }) => {
+    Given("I create a mock echoing POST at {string}", (_, path: string) => {
+      mock = schmock();
+      mock(`POST ${path}`, ({ body }) => body);
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And(
+      "I fetch {string} with JSON body:",
+      async (_, route: string, docString: string) => {
+        const [method, path] = route.split(" ");
+        httpResponse = await fetch(`${baseUrl()}${path}`, {
+          method,
+          headers: { "content-type": "application/json" },
+          body: docString,
+        });
+      },
+    );
+
+    Then(
+      "the response status from POST should be {int}",
+      (_, status: number) => {
+        expect(httpResponse.status).toBe(status);
+      },
+    );
+
+    And(
+      "the response body from POST should have {string} equal to {string}",
+      async (_, key: string, value: string) => {
+        const body = await httpResponse.json();
+        expect(body[key]).toBe(value);
+      },
+    );
+
+    When("I stop the server", () => {
+      mock.close();
+    });
+  });
+
+  Scenario(
+    "Return 404 for unregistered routes",
+    ({ Given, When, And, Then }) => {
+      Given("I create a mock with a GET /hello route", () => {
+        mock = schmock();
+        mock("GET /hello", { message: "hello" });
+      });
+
+      When("I start the server on a random port", async () => {
+        serverInfo = await mock.listen(0);
+      });
+
+      And("I fetch {string} from the server", async (_, route: string) => {
+        const [, path] = route.split(" ");
+        httpResponse = await fetch(`${baseUrl()}${path}`);
+      });
+
+      Then("the HTTP response status should be {int}", (_, status: number) => {
+        expect(httpResponse.status).toBe(status);
+      });
+
+      When("I stop the server", () => {
+        mock.close();
+      });
+    },
+  );
+
+  Scenario("Query parameters are forwarded", ({ Given, When, And, Then }) => {
+    let parsedBody: Record<string, string>;
+
+    Given(
+      "I create a mock reflecting query params at {string}",
+      (_, route: string) => {
+        const [method, path] = route.split(" ");
+        mock = schmock();
+        mock(`${method} ${path}` as Schmock.RouteKey, ({ query }) => query);
+      },
+    );
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And("I fetch {string} from the server", async (_, route: string) => {
+      const [, pathWithQuery] = route.split(" ");
+      httpResponse = await fetch(`${baseUrl()}${pathWithQuery}`);
+      parsedBody = await httpResponse.json();
+    });
+
+    Then("the HTTP response status should be {int}", (_, status: number) => {
+      expect(httpResponse.status).toBe(status);
+    });
+
+    And(
+      "the HTTP response body should have {string} equal to {string}",
+      (_, key: string, value: string) => {
+        expect(parsedBody[key]).toBe(value);
+      },
+    );
+
+    And(
+      "the query param {string} should equal {string}",
+      (_, key: string, value: string) => {
+        expect(parsedBody[key]).toBe(value);
+      },
+    );
+
+    When("I stop the server", () => {
+      mock.close();
+    });
+  });
+
+  Scenario("Double listen throws an error", ({ Given, When, Then }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    Then("starting the server again should throw", () => {
+      expect(() => mock.listen(0)).toThrow("Server is already running");
+      mock.close();
+    });
+  });
+
+  Scenario("Close is idempotent", ({ Given, When, And, Then }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And("I stop the server", () => {
+      mock.close();
+    });
+
+    Then("stopping the server again should not throw", () => {
+      expect(() => mock.close()).not.toThrow();
+    });
+  });
+
+  Scenario("Reset stops the server", ({ Given, When, And, Then }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And("I reset the mock", () => {
+      mock.reset();
+    });
+
+    Then("the server should not be running", async () => {
+      try {
+        await fetch(`${baseUrl()}/hello`);
+        expect.unreachable("Should not be able to connect");
+      } catch {
+        // Connection refused — server is down
+      }
+    });
+  });
+});

package/src/types.ts

@@ -18,3 +18,4 @@ export type PluginContext = Schmock.PluginContext;
 export type PluginResult = Schmock.PluginResult;
 export type StaticData = Schmock.StaticData;
 export type RequestRecord = Schmock.RequestRecord;
+export type ServerInfo = Schmock.ServerInfo;