@ricsam/isolate-test-utils 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @ricsam/isolate-test-utils
 
+## 0.1.6
+
+### Patch Changes
+
+- new version
+- Updated dependencies
+  - @ricsam/isolate-console@0.1.6
+  - @ricsam/isolate-core@0.1.6
+  - @ricsam/isolate-fetch@0.1.6
+  - @ricsam/isolate-fs@0.1.6
+  - @ricsam/isolate-runtime@0.1.7
+
+## 0.1.5
+
+### Patch Changes
+
+- new API
+- Updated dependencies
+  - @ricsam/isolate-runtime@0.1.5
+  - @ricsam/isolate-console@0.1.5
+  - @ricsam/isolate-core@0.1.5
+  - @ricsam/isolate-fetch@0.1.5
+  - @ricsam/isolate-fs@0.1.5
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,75 @@
+# @ricsam/isolate-test-utils
+
+Testing utilities for isolated-vm V8 sandbox development.
+
+## Installation
+
+```bash
+npm add @ricsam/isolate-test-utils
+```
+
+## Usage
+
+```typescript
+import { createRuntimeTestContext } from "@ricsam/isolate-test-utils";
+
+// Create a test context with all APIs set up
+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 captured logs
+console.log(ctx.logs);
+// [{ level: "log", args: ["Starting fetch..."] }, ...]
+
+// Check captured fetch calls
+console.log(ctx.fetchCalls);
+// [{ url: "https://api.example.com/data", method: "GET", headers: [...] }]
+
+// Cleanup
+ctx.dispose();
+```
+
+## RuntimeTestContext
+
+```typescript
+interface RuntimeTestContext {
+  isolate: ivm.Isolate;
+  context: ivm.Context;
+  tick(ms?: number): Promise<void>;
+  dispose(): void;
+  logs: Array<{ level: string; args: unknown[] }>;
+  fetchCalls: Array<{ url: string; method: string; headers: [string, string][] }>;
+  setMockResponse(response: MockResponse): void;
+  mockFs: MockFileSystem;
+}
+
+interface MockResponse {
+  status?: number;
+  body?: string;
+  headers?: Record<string, string>;
+}
+```
+
+## Options
+
+```typescript
+interface RuntimeTestContextOptions {
+  fs?: boolean; // Enable file system APIs with mock file system
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/isolate-test-utils",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/index.test.ts

@@ -328,16 +328,17 @@ describe("createFsTestContext", () => {
 describe("createRuntimeTestContext", () => {
   let ctx: RuntimeTestContext | undefined;
 
-  afterEach(() => {
-    ctx?.dispose();
+  afterEach(async () => {
+    await ctx?.dispose();
     ctx = undefined;
   });
 
   test("creates full runtime context", async () => {
     ctx = await createRuntimeTestContext();
-    assert.ok(ctx.isolate);
-    assert.ok(ctx.context);
-    assert.ok(typeof ctx.tick === "function");
+    assert.ok(typeof ctx.eval === "function");
+    assert.ok(typeof ctx.clearTimers === "function");
+    assert.ok(typeof ctx.dispatchRequest === "function");
+    assert.ok(typeof ctx.dispose === "function");
     assert.ok(Array.isArray(ctx.logs));
     assert.ok(Array.isArray(ctx.fetchCalls));
   });
@@ -345,14 +346,14 @@ describe("createRuntimeTestContext", () => {
   test("captures console logs", async () => {
     ctx = await createRuntimeTestContext();
 
-    ctx.context.evalSync('console.log("test message")');
-    ctx.context.evalSync('console.warn("warning message")');
+    await ctx.eval('console.log("test message")');
+    await ctx.eval('console.warn("warning message")');
 
     assert.strictEqual(ctx.logs.length, 2);
-    assert.strictEqual(ctx.logs[0].level, "log");
-    assert.deepStrictEqual(ctx.logs[0].args, ["test message"]);
-    assert.strictEqual(ctx.logs[1].level, "warn");
-    assert.deepStrictEqual(ctx.logs[1].args, ["warning message"]);
+    assert.strictEqual(ctx.logs[0]!.level, "log");
+    assert.deepStrictEqual(ctx.logs[0]!.args, ["test message"]);
+    assert.strictEqual(ctx.logs[1]!.level, "warn");
+    assert.deepStrictEqual(ctx.logs[1]!.args, ["warning message"]);
   });
 
   test("captures and mocks fetch calls", async () => {
@@ -364,42 +365,40 @@ describe("createRuntimeTestContext", () => {
       headers: { "Content-Type": "application/json" },
     });
 
-    const result = await ctx.context.eval(
-      `
-      (async () => {
-        const response = await fetch("https://api.example.com/data");
-        const json = await response.json();
-        return JSON.stringify({ status: response.status, data: json });
-      })()
-    `,
-      { promise: true }
-    );
+    await ctx.eval(`
+      const response = await fetch("https://api.example.com/data");
+      const json = await response.json();
+      setResult({ status: response.status, data: json });
+    `);
 
-    const parsed = JSON.parse(result as string);
-    assert.strictEqual(parsed.status, 200);
-    assert.deepStrictEqual(parsed.data, { data: "test" });
+    const result = ctx.getResult<{ status: number; data: { data: string } }>();
+    assert.strictEqual(result?.status, 200);
+    assert.deepStrictEqual(result?.data, { data: "test" });
 
     assert.strictEqual(ctx.fetchCalls.length, 1);
-    assert.strictEqual(ctx.fetchCalls[0].url, "https://api.example.com/data");
-    assert.strictEqual(ctx.fetchCalls[0].method, "GET");
+    assert.strictEqual(ctx.fetchCalls[0]!.url, "https://api.example.com/data");
+    assert.strictEqual(ctx.fetchCalls[0]!.method, "GET");
   });
 
-  test("tick advances timers", async () => {
+  test("timers fire automatically with real time", async () => {
     ctx = await createRuntimeTestContext();
 
-    ctx.context.evalSync(`
+    await ctx.eval(`
       globalThis.timerFired = false;
-      setTimeout(() => { globalThis.timerFired = true; }, 100);
+      setTimeout(() => { globalThis.timerFired = true; }, 20);
     `);
 
-    // Timer should not have fired yet
-    assert.strictEqual(evalCode<boolean>(ctx.context, "timerFired"), false);
+    // Timer should not have fired yet - check via setResult
+    await ctx.eval('setResult(globalThis.timerFired)');
+    assert.strictEqual(ctx.getResult<boolean>(), false);
+    ctx.clearResult();
 
-    // Advance time
-    await ctx.tick(100);
+    // Wait for real time to pass
+    await new Promise((r) => setTimeout(r, 50));
 
     // Timer should have fired
-    assert.strictEqual(evalCode<boolean>(ctx.context, "timerFired"), true);
+    await ctx.eval('setResult(globalThis.timerFired)');
+    assert.strictEqual(ctx.getResult<boolean>(), true);
   });
 });
 
@@ -447,10 +446,10 @@ describe("startIntegrationServer", () => {
 
     const requests = server.getRequests();
     assert.strictEqual(requests.length, 1);
-    assert.strictEqual(requests[0].method, "POST");
-    assert.strictEqual(requests[0].path, "/api/endpoint");
-    assert.strictEqual(requests[0].headers["x-custom"], "value");
-    assert.strictEqual(requests[0].body, "request body");
+    assert.strictEqual(requests[0]!.method, "POST");
+    assert.strictEqual(requests[0]!.path, "/api/endpoint");
+    assert.strictEqual(requests[0]!.headers["x-custom"], "value");
+    assert.strictEqual(requests[0]!.body, "request body");
   });
 
   test("clears requests", async () => {

package/src/runtime-context.ts

@@ -1,4 +1,3 @@
-import type ivm from "isolated-vm";
 import { MockFileSystem } from "./mock-fs.ts";
 
 export interface MockResponse {
@@ -13,11 +12,14 @@ export interface RuntimeTestContextOptions {
 }
 
 export interface RuntimeTestContext {
-  isolate: ivm.Isolate;
-  context: ivm.Context;
-  /** Advance virtual time and process pending timers */
-  tick(ms?: number): Promise<void>;
-  dispose(): void;
+  /** Execute code in the runtime (ES module mode, supports top-level await) */
+  eval(code: string): Promise<void>;
+  /** Clear all pending timers */
+  clearTimers(): void;
+  /** Dispatch an HTTP request to the serve() handler */
+  dispatchRequest(request: Request): Promise<Response>;
+  /** Dispose all resources */
+  dispose(): Promise<void>;
   /** Captured console.log calls */
   logs: Array<{ level: string; args: unknown[] }>;
   /** Captured fetch calls */
@@ -26,6 +28,13 @@ export interface RuntimeTestContext {
   setMockResponse(response: MockResponse): void;
   /** Mock file system (only available if fs option is true) */
   mockFs: MockFileSystem;
+  /**
+   * Get a result from the isolate. Call `await setResult(value)` in your eval code
+   * to pass a value back to the host.
+   */
+  getResult<T = unknown>(): T | undefined;
+  /** Clear the stored result */
+  clearResult(): void;
 }
 
 /**
@@ -38,15 +47,17 @@ export interface RuntimeTestContext {
  * // 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 });
+ * // Run code and pass result back via setResult
+ * await ctx.eval(`
+ *   console.log("Starting fetch...");
+ *   const response = await fetch("https://api.example.com/data");
+ *   const data = await response.json();
+ *   console.log("Got data:", data);
+ *   setResult(data);
+ * `);
+ *
+ * // Get the result
+ * console.log(ctx.getResult()); // { data: "test" }
  *
  * // Check logs
  * console.log(ctx.logs); // [{ level: "log", args: ["Starting fetch..."] }, ...]
@@ -54,7 +65,7 @@ export interface RuntimeTestContext {
  * // Check fetch calls
  * console.log(ctx.fetchCalls); // [{ url: "https://api.example.com/data", method: "GET", ... }]
  *
- * ctx.dispose();
+ * await ctx.dispose();
  */
 export async function createRuntimeTestContext(
   options?: RuntimeTestContextOptions
@@ -75,6 +86,7 @@ export async function createRuntimeTestContext(
   }> = [];
 
   let mockResponse: MockResponse = { status: 200, body: "" };
+  let storedResult: unknown = undefined;
 
   // Create mock file system
   const mockFs = new MockFileSystem();
@@ -82,33 +94,43 @@ export async function createRuntimeTestContext(
   // Create runtime with configured handlers
   const runtime = await createRuntime({
     console: {
-      onLog: (level: string, ...args: unknown[]) => {
-        logs.push({ level, args });
+      onEntry: (entry) => {
+        if (entry.type === "output") {
+          logs.push({ level: entry.level, args: entry.args });
+        } else if (entry.type === "assert") {
+          logs.push({ level: "error", args: ["Assertion failed:", ...entry.args] });
+        }
       },
     },
-    fetch: {
-      onFetch: async (request: Request) => {
-        // Capture fetch call
-        fetchCalls.push({
-          url: request.url,
-          method: request.method,
-          headers: [...request.headers.entries()],
-        });
+    fetch: 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,
-        });
-      },
+      // Return mock response
+      return new Response(mockResponse.body ?? "", {
+        status: mockResponse.status ?? 200,
+        headers: mockResponse.headers,
+      });
     },
     fs: opts.fs ? { getDirectory: async () => mockFs } : undefined,
+    customFunctions: {
+      setResult: {
+        fn: (value: unknown) => {
+          storedResult = value;
+        },
+        type: 'sync',
+      },
+    },
   });
 
   return {
-    isolate: runtime.isolate,
-    context: runtime.context,
-    tick: runtime.tick.bind(runtime),
+    eval: runtime.eval.bind(runtime),
+    clearTimers: runtime.timers.clearAll.bind(runtime.timers),
+    dispatchRequest: runtime.fetch.dispatchRequest.bind(runtime.fetch),
     dispose: runtime.dispose.bind(runtime),
     logs,
     fetchCalls,
@@ -116,5 +138,11 @@ export async function createRuntimeTestContext(
       mockResponse = response;
     },
     mockFs,
+    getResult<T = unknown>(): T | undefined {
+      return storedResult as T | undefined;
+    },
+    clearResult() {
+      storedResult = undefined;
+    },
   };
 }

package/tsconfig.json

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