@ricsam/isolate-test-utils 0.0.1 → 0.1.2

package/src/native-input-test.ts

@@ -0,0 +1,412 @@
+import ivm from "isolated-vm";
+
+export interface TestRuntime {
+  logs: Record<string, unknown>;
+  result: unknown;
+}
+
+export interface TestRunner {
+  input(inputs: Record<string, unknown>): TestRuntime;
+}
+
+/**
+ * Run isolate code with native objects as input and capture logs
+ *
+ * This utility allows testing whether native objects passed INTO the isolate
+ * behave like isolate instances. It converts native web API classes (Headers,
+ * Request, Response, URL, Blob, File, FormData) to their isolate equivalents
+ * before executing the test code.
+ *
+ * @example
+ * const runtime = runTestCode(ctx.context, `
+ *   const headers = testingInput.headers;
+ *   log("instanceof", headers instanceof Headers);
+ *   log("contentType", headers.get("content-type"));
+ * `).input({
+ *   headers: new Headers({ "content-type": "application/json" })
+ * });
+ *
+ * expect(runtime.logs.instanceof).toBe(true);
+ * expect(runtime.logs.contentType).toBe("application/json");
+ */
+export function runTestCode(context: ivm.Context, code: string): TestRunner {
+  return {
+    input(inputs: Record<string, unknown>): TestRuntime {
+      const logs: Record<string, unknown> = {};
+
+      // Setup log capture - log(tag, value) stores as logs[tag] = value
+      // Values are unmarshalled back to native types for bidirectional testing
+      const logCallback = new ivm.Callback(
+        (tag: string, valueJson: string) => {
+          const value = JSON.parse(valueJson);
+          logs[tag] = unmarshalFromJson(value);
+        }
+      );
+      context.global.setSync("__log_callback__", logCallback);
+
+      // Create a wrapper log function that serializes values
+      context.evalSync(`
+        globalThis.log = function(tag, value) {
+          __log_callback__(tag, JSON.stringify(__serializeForLog__(value)));
+        };
+
+        globalThis.__serializeForLog__ = function(value) {
+          if (typeof Headers !== 'undefined' && value instanceof Headers) {
+            const pairs = [];
+            for (const [k, v] of value) pairs.push([k, v]);
+            return { __type__: 'Headers', pairs };
+          }
+          if (typeof Request !== 'undefined' && value instanceof Request) {
+            const headers = [];
+            for (const [k, v] of value.headers) headers.push([k, v]);
+            return {
+              __type__: 'Request',
+              url: value.url,
+              method: value.method,
+              headers,
+              mode: value.mode,
+              credentials: value.credentials,
+              cache: value.cache,
+              redirect: value.redirect,
+              referrer: value.referrer,
+              referrerPolicy: value.referrerPolicy,
+              integrity: value.integrity,
+            };
+          }
+          if (typeof Response !== 'undefined' && value instanceof Response) {
+            const headers = [];
+            for (const [k, v] of value.headers) headers.push([k, v]);
+            return {
+              __type__: 'Response',
+              status: value.status,
+              statusText: value.statusText,
+              ok: value.ok,
+              headers,
+              type: value.type,
+              redirected: value.redirected,
+              url: value.url,
+            };
+          }
+          if (typeof FormData !== 'undefined' && value instanceof FormData) {
+            const entries = [];
+            for (const [k, v] of value) {
+              if (typeof File !== 'undefined' && v instanceof File) {
+                entries.push([k, { __type__: 'File', name: v.name, type: v.type, lastModified: v.lastModified }]);
+              } else {
+                entries.push([k, v]);
+              }
+            }
+            return { __type__: 'FormData', entries };
+          }
+          if (value instanceof URL) {
+            return { __type__: 'URL', href: value.href };
+          }
+          if (value instanceof File) {
+            return { __type__: 'File', name: value.name, type: value.type, lastModified: value.lastModified };
+          }
+          if (value instanceof Blob) {
+            return { __type__: 'Blob', type: value.type, size: value.size };
+          }
+          if (Array.isArray(value)) {
+            return value.map(v => __serializeForLog__(v));
+          }
+          if (value && typeof value === 'object' && value.constructor === Object) {
+            const result = {};
+            for (const [k, v] of Object.entries(value)) {
+              result[k] = __serializeForLog__(v);
+            }
+            return result;
+          }
+          return value;
+        };
+      `);
+
+      // Marshal inputs with special handling for native web API classes
+      marshalInputs(context, inputs);
+
+      // Run the code
+      let returnValue: unknown = undefined;
+      try {
+        returnValue = context.evalSync(code);
+      } catch (error) {
+        // Clean up before re-throwing
+        context.evalSync(`
+          delete globalThis.testingInput;
+          delete globalThis.log;
+          delete globalThis.__log_callback__;
+          delete globalThis.__serializeForLog__;
+        `);
+        throw error;
+      }
+
+      // Cleanup
+      context.evalSync(`
+        delete globalThis.testingInput;
+        delete globalThis.log;
+        delete globalThis.__log_callback__;
+        delete globalThis.__serializeForLog__;
+      `);
+
+      return { logs, result: returnValue };
+    },
+  };
+}
+
+/**
+ * Marshal inputs into the isolate, converting native web API classes
+ */
+function marshalInputs(
+  context: ivm.Context,
+  inputs: Record<string, unknown>
+): void {
+  // Create the testingInput object in the isolate
+  context.evalSync(`globalThis.testingInput = {};`);
+
+  for (const [key, value] of Object.entries(inputs)) {
+    marshalValue(context, `testingInput.${key}`, value);
+  }
+}
+
+/**
+ * Marshal a single value into the isolate at the given path
+ */
+function marshalValue(
+  context: ivm.Context,
+  path: string,
+  value: unknown
+): void {
+  // Check for native Headers
+  if (value instanceof Headers) {
+    const pairs: [string, string][] = [];
+    value.forEach((v, k) => pairs.push([k, v]));
+    const pairsJson = JSON.stringify(pairs);
+    context.evalSync(`${path} = new Headers(${pairsJson});`);
+    return;
+  }
+
+  // Check for native Request
+  if (value instanceof Request) {
+    // First marshal the headers
+    const headerPairs: [string, string][] = [];
+    value.headers.forEach((v, k) => headerPairs.push([k, v]));
+    const headersJson = JSON.stringify(headerPairs);
+
+    const urlJson = JSON.stringify(value.url);
+    const methodJson = JSON.stringify(value.method);
+    const modeJson = JSON.stringify(value.mode);
+    const credentialsJson = JSON.stringify(value.credentials);
+    const cacheJson = JSON.stringify(value.cache);
+    const redirectJson = JSON.stringify(value.redirect);
+    const referrerJson = JSON.stringify(value.referrer);
+    const referrerPolicyJson = JSON.stringify(value.referrerPolicy);
+    const integrityJson = JSON.stringify(value.integrity);
+
+    context.evalSync(`
+      ${path} = new Request(${urlJson}, {
+        method: ${methodJson},
+        headers: new Headers(${headersJson}),
+        mode: ${modeJson},
+        credentials: ${credentialsJson},
+        cache: ${cacheJson},
+        redirect: ${redirectJson},
+        referrer: ${referrerJson},
+        referrerPolicy: ${referrerPolicyJson},
+        integrity: ${integrityJson},
+      });
+    `);
+    return;
+  }
+
+  // Check for native Response
+  if (value instanceof Response) {
+    const headerPairs: [string, string][] = [];
+    value.headers.forEach((v, k) => headerPairs.push([k, v]));
+    const headersJson = JSON.stringify(headerPairs);
+
+    const statusJson = JSON.stringify(value.status);
+    const statusTextJson = JSON.stringify(value.statusText);
+
+    context.evalSync(`
+      ${path} = new Response(null, {
+        status: ${statusJson},
+        statusText: ${statusTextJson},
+        headers: new Headers(${headersJson}),
+      });
+    `);
+    return;
+  }
+
+  // Check for native FormData
+  if (value instanceof FormData) {
+    context.evalSync(`${path} = new FormData();`);
+
+    for (const [key, entryValue] of value.entries()) {
+      const keyJson = JSON.stringify(key);
+
+      if (entryValue instanceof File) {
+        const nameJson = JSON.stringify(entryValue.name);
+        const typeJson = JSON.stringify(entryValue.type);
+        const lastModifiedJson = JSON.stringify(entryValue.lastModified);
+        context.evalSync(`
+          ${path}.append(${keyJson}, new File([], ${nameJson}, { type: ${typeJson}, lastModified: ${lastModifiedJson} }));
+        `);
+      } else {
+        const valueJson = JSON.stringify(entryValue);
+        context.evalSync(`${path}.append(${keyJson}, ${valueJson});`);
+      }
+    }
+    return;
+  }
+
+  // Check for native URL
+  if (value instanceof URL) {
+    const hrefJson = JSON.stringify(value.href);
+    context.evalSync(`${path} = new URL(${hrefJson});`);
+    return;
+  }
+
+  // Check for native File (before Blob, since File extends Blob)
+  if (value instanceof File) {
+    const nameJson = JSON.stringify(value.name);
+    const typeJson = JSON.stringify(value.type);
+    const lastModifiedJson = JSON.stringify(value.lastModified);
+    context.evalSync(
+      `${path} = new File([], ${nameJson}, { type: ${typeJson}, lastModified: ${lastModifiedJson} });`
+    );
+    return;
+  }
+
+  // Check for native Blob
+  if (value instanceof Blob) {
+    const typeJson = JSON.stringify(value.type);
+    context.evalSync(`${path} = new Blob([], { type: ${typeJson} });`);
+    return;
+  }
+
+  // Handle arrays recursively
+  if (Array.isArray(value)) {
+    context.evalSync(`${path} = [];`);
+    for (let i = 0; i < value.length; i++) {
+      marshalValue(context, `${path}[${i}]`, value[i]);
+    }
+    return;
+  }
+
+  // Handle plain objects recursively
+  if (value && typeof value === "object" && value.constructor === Object) {
+    context.evalSync(`${path} = {};`);
+    for (const [key, val] of Object.entries(value)) {
+      // Use bracket notation for safe property access
+      marshalValue(context, `${path}[${JSON.stringify(key)}]`, val);
+    }
+    return;
+  }
+
+  // For primitives, set directly via JSON
+  const valueJson = JSON.stringify(value);
+  context.evalSync(`${path} = ${valueJson};`);
+}
+
+/**
+ * Unmarshal a value from JSON, converting special __type__ markers back to native instances
+ */
+function unmarshalFromJson(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((v) => unmarshalFromJson(v));
+  }
+
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+
+    // Check for special type markers
+    if (obj.__type__ === "Headers") {
+      const pairs = obj.pairs as [string, string][];
+      const headers = new Headers();
+      for (const [k, v] of pairs) {
+        headers.append(k, v);
+      }
+      return headers;
+    }
+
+    if (obj.__type__ === "Request") {
+      const headers = new Headers();
+      for (const [k, v] of obj.headers as [string, string][]) {
+        headers.append(k, v);
+      }
+      return new Request(obj.url as string, {
+        method: obj.method as string,
+        headers,
+        mode: obj.mode as Request["mode"],
+        credentials: obj.credentials as Request["credentials"],
+        cache: obj.cache as Request["cache"],
+        redirect: obj.redirect as Request["redirect"],
+        referrer: obj.referrer as string,
+        referrerPolicy: obj.referrerPolicy as Request["referrerPolicy"],
+        integrity: obj.integrity as string,
+      });
+    }
+
+    if (obj.__type__ === "Response") {
+      const headers = new Headers();
+      for (const [k, v] of obj.headers as [string, string][]) {
+        headers.append(k, v);
+      }
+      return new Response(null, {
+        status: obj.status as number,
+        statusText: obj.statusText as string,
+        headers,
+      });
+    }
+
+    if (obj.__type__ === "FormData") {
+      const formData = new FormData();
+      for (const [k, v] of obj.entries as [string, unknown][]) {
+        if (
+          typeof v === "object" &&
+          v !== null &&
+          (v as Record<string, unknown>).__type__ === "File"
+        ) {
+          const fileObj = v as Record<string, unknown>;
+          formData.append(
+            k,
+            new File([], fileObj.name as string, {
+              type: fileObj.type as string,
+              lastModified: fileObj.lastModified as number,
+            })
+          );
+        } else {
+          formData.append(k, v as string);
+        }
+      }
+      return formData;
+    }
+
+    if (obj.__type__ === "URL") {
+      return new URL(obj.href as string);
+    }
+
+    if (obj.__type__ === "File") {
+      return new File([], obj.name as string, {
+        type: obj.type as string,
+        lastModified: obj.lastModified as number,
+      });
+    }
+
+    if (obj.__type__ === "Blob") {
+      return new Blob([], { type: obj.type as string });
+    }
+
+    // Plain object - recursively unmarshal properties
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      result[k] = unmarshalFromJson(v);
+    }
+    return result;
+  }
+
+  return value;
+}

package/src/runtime-context.ts

@@ -0,0 +1,120 @@
+import type ivm from "isolated-vm";
+import { MockFileSystem } from "./mock-fs.ts";
+
+export interface MockResponse {
+  status?: number;
+  body?: string;
+  headers?: Record<string, string>;
+}
+
+export interface RuntimeTestContextOptions {
+  /** Enable file system APIs with mock file system */
+  fs?: boolean;
+}
+
+export interface RuntimeTestContext {
+  isolate: ivm.Isolate;
+  context: ivm.Context;
+  /** Advance virtual time and process pending timers */
+  tick(ms?: number): Promise<void>;
+  dispose(): void;
+  /** Captured console.log calls */
+  logs: Array<{ level: string; args: unknown[] }>;
+  /** Captured fetch calls */
+  fetchCalls: Array<{ url: string; method: string; headers: [string, string][] }>;
+  /** Set the mock response for the next fetch call */
+  setMockResponse(response: MockResponse): void;
+  /** Mock file system (only available if fs option is true) */
+  mockFs: MockFileSystem;
+}
+
+/**
+ * Create a full runtime test context with all APIs set up.
+ * Includes console logging capture, fetch mocking, and optionally file system.
+ *
+ * @example
+ * const ctx = await createRuntimeTestContext({ fs: true });
+ *
+ * // Set up mock response for fetch
+ * ctx.setMockResponse({ status: 200, body: '{"data": "test"}' });
+ *
+ * // Run code
+ * await ctx.context.eval(`
+ *   (async () => {
+ *     console.log("Starting fetch...");
+ *     const response = await fetch("https://api.example.com/data");
+ *     const data = await response.json();
+ *     console.log("Got data:", data);
+ *   })()
+ * `, { promise: true });
+ *
+ * // Check logs
+ * console.log(ctx.logs); // [{ level: "log", args: ["Starting fetch..."] }, ...]
+ *
+ * // Check fetch calls
+ * console.log(ctx.fetchCalls); // [{ url: "https://api.example.com/data", method: "GET", ... }]
+ *
+ * ctx.dispose();
+ */
+export async function createRuntimeTestContext(
+  options?: RuntimeTestContextOptions
+): Promise<RuntimeTestContext> {
+  const opts = options ?? {};
+  const { createRuntime } = await import("@ricsam/isolate-runtime");
+  const { clearAllInstanceState } = await import("@ricsam/isolate-core");
+
+  // Clear any previous instance state
+  clearAllInstanceState();
+
+  // State for capturing logs and fetch calls
+  const logs: Array<{ level: string; args: unknown[] }> = [];
+  const fetchCalls: Array<{
+    url: string;
+    method: string;
+    headers: [string, string][];
+  }> = [];
+
+  let mockResponse: MockResponse = { status: 200, body: "" };
+
+  // Create mock file system
+  const mockFs = new MockFileSystem();
+
+  // Create runtime with configured handlers
+  const runtime = await createRuntime({
+    console: {
+      onLog: (level: string, ...args: unknown[]) => {
+        logs.push({ level, args });
+      },
+    },
+    fetch: {
+      onFetch: async (request: Request) => {
+        // Capture fetch call
+        fetchCalls.push({
+          url: request.url,
+          method: request.method,
+          headers: [...request.headers.entries()],
+        });
+
+        // Return mock response
+        return new Response(mockResponse.body ?? "", {
+          status: mockResponse.status ?? 200,
+          headers: mockResponse.headers,
+        });
+      },
+    },
+    fs: opts.fs ? { getDirectory: async () => mockFs } : undefined,
+  });
+
+  return {
+    isolate: runtime.isolate,
+    context: runtime.context,
+    tick: runtime.tick.bind(runtime),
+    dispose: runtime.dispose.bind(runtime),
+    logs,
+    fetchCalls,
+    setMockResponse(response: MockResponse) {
+      mockResponse = response;
+    },
+    mockFs,
+  };
+}

package/src/server.ts

@@ -0,0 +1,150 @@
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+
+export interface MockServerResponse {
+  status?: number;
+  body?: string;
+  headers?: Record<string, string>;
+}
+
+export interface RecordedRequest {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+export interface IntegrationServer {
+  /** The base URL of the server (e.g., "http://localhost:3000") */
+  url: string;
+  /** The port the server is listening on */
+  port: number;
+  /** Close the server */
+  close(): Promise<void>;
+  /** Set the response for a specific path */
+  setResponse(path: string, response: MockServerResponse): void;
+  /** Set a default response for any unmatched path */
+  setDefaultResponse(response: MockServerResponse): void;
+  /** Get all recorded requests */
+  getRequests(): RecordedRequest[];
+  /** Clear all recorded requests */
+  clearRequests(): void;
+  /** Clear all configured responses */
+  clearResponses(): void;
+}
+
+/**
+ * Start an HTTP server for integration tests.
+ * Useful for testing fetch operations against a real server.
+ *
+ * @example
+ * const server = await startIntegrationServer();
+ *
+ * server.setResponse("/api/data", {
+ *   status: 200,
+ *   body: JSON.stringify({ message: "Hello" }),
+ *   headers: { "Content-Type": "application/json" }
+ * });
+ *
+ * // In your test
+ * const response = await fetch(`${server.url}/api/data`);
+ * const data = await response.json();
+ *
+ * // Check what requests were made
+ * const requests = server.getRequests();
+ * console.log(requests[0].path); // "/api/data"
+ *
+ * await server.close();
+ */
+export async function startIntegrationServer(
+  port?: number
+): Promise<IntegrationServer> {
+  const responses = new Map<string, MockServerResponse>();
+  const requests: RecordedRequest[] = [];
+  let defaultResponse: MockServerResponse = { status: 404, body: "Not Found" };
+
+  const server: Server = createServer(
+    async (req: IncomingMessage, res: ServerResponse) => {
+      const path = req.url ?? "/";
+      const method = req.method ?? "GET";
+
+      // Read request body
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) {
+        chunks.push(chunk as Buffer);
+      }
+      const body = chunks.length > 0 ? Buffer.concat(chunks).toString() : undefined;
+
+      // Record the request
+      const headers: Record<string, string> = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === "string") {
+          headers[key] = value;
+        } else if (Array.isArray(value)) {
+          headers[key] = value.join(", ");
+        }
+      }
+      requests.push({ method, path, headers, body });
+
+      // Find and send response
+      const mockResponse = responses.get(path) ?? defaultResponse;
+
+      res.statusCode = mockResponse.status ?? 200;
+
+      if (mockResponse.headers) {
+        for (const [key, value] of Object.entries(mockResponse.headers)) {
+          res.setHeader(key, value);
+        }
+      }
+
+      res.end(mockResponse.body ?? "");
+    }
+  );
+
+  // Find an available port
+  const actualPort = await new Promise<number>((resolve, reject) => {
+    server.listen(port ?? 0, () => {
+      const address = server.address();
+      if (address && typeof address === "object") {
+        resolve(address.port);
+      } else {
+        reject(new Error("Failed to get server address"));
+      }
+    });
+    server.on("error", reject);
+  });
+
+  return {
+    url: `http://localhost:${actualPort}`,
+    port: actualPort,
+
+    async close() {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+
+    setResponse(path: string, response: MockServerResponse) {
+      responses.set(path, response);
+    },
+
+    setDefaultResponse(response: MockServerResponse) {
+      defaultResponse = response;
+    },
+
+    getRequests() {
+      return [...requests];
+    },
+
+    clearRequests() {
+      requests.length = 0;
+    },
+
+    clearResponses() {
+      responses.clear();
+      defaultResponse = { status: 404, body: "Not Found" };
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}