@ricsam/isolate-test-utils 0.1.10 → 0.1.11

package/dist/types/fs-context.d.ts

@@ -0,0 +1,30 @@
+import type ivm from "isolated-vm";
+import { MockFileSystem } from "./mock-fs.ts";
+export interface FsTestContext {
+    isolate: ivm.Isolate;
+    context: ivm.Context;
+    mockFs: MockFileSystem;
+    dispose(): void;
+}
+/**
+ * Create a test context with file system APIs set up using a mock file system.
+ *
+ * @example
+ * const ctx = await createFsTestContext();
+ *
+ * // Set up initial files
+ * ctx.mockFs.setFile("/test.txt", "Hello, World!");
+ *
+ * // Use file system APIs in the isolate
+ * const result = await ctx.context.eval(`
+ *   (async () => {
+ *     const root = await navigator.storage.getDirectory();
+ *     const fileHandle = await root.getFileHandle("test.txt");
+ *     const file = await fileHandle.getFile();
+ *     return await file.text();
+ *   })()
+ * `, { promise: true });
+ *
+ * ctx.dispose();
+ */
+export declare function createFsTestContext(): Promise<FsTestContext>;

package/dist/types/index.d.ts

@@ -0,0 +1,88 @@
+import type ivm from "isolated-vm";
+export interface TestContext {
+    isolate: ivm.Isolate;
+    context: ivm.Context;
+    dispose(): void;
+}
+export interface TestResult<T> {
+    result: T;
+    logs: Array<{
+        level: string;
+        args: unknown[];
+    }>;
+}
+/**
+ * Create a basic test context for isolated-vm tests.
+ * This creates a bare context without any APIs set up.
+ */
+export declare function createTestContext(): Promise<TestContext>;
+/**
+ * Create a test context with core APIs set up (Blob, File, URL, streams, etc.)
+ */
+export declare function createCoreTestContext(): Promise<TestContext>;
+/**
+ * Synchronously evaluate code and return typed result.
+ * Use this for simple expressions that don't involve promises.
+ *
+ * @example
+ * const result = evalCode<number>(ctx.context, "1 + 1");
+ * // result === 2
+ */
+export declare function evalCode<T = unknown>(context: ivm.Context, code: string): T;
+/**
+ * Asynchronously evaluate code that may return promises.
+ * Automatically wraps code to handle promise resolution.
+ *
+ * @example
+ * const result = await evalCodeAsync<string>(ctx.context, `
+ *   (async () => {
+ *     return "hello";
+ *   })()
+ * `);
+ */
+export declare function evalCodeAsync<T = unknown>(context: ivm.Context, code: string): Promise<T>;
+/**
+ * Evaluate code and return the result as JSON (for complex objects).
+ * Useful when you need to extract structured data from the isolate.
+ *
+ * @example
+ * const data = evalCodeJson<{ name: string }>(ctx.context, `
+ *   JSON.stringify({ name: "test" })
+ * `);
+ */
+export declare function evalCodeJson<T = unknown>(context: ivm.Context, code: string): T;
+/**
+ * Evaluate async code and return the result as JSON (for complex objects).
+ *
+ * @example
+ * const data = await evalCodeJsonAsync<{ status: number }>(ctx.context, `
+ *   (async () => {
+ *     const response = await fetch("...");
+ *     return JSON.stringify({ status: response.status });
+ *   })()
+ * `);
+ */
+export declare function evalCodeJsonAsync<T = unknown>(context: ivm.Context, code: string): Promise<T>;
+/**
+ * Inject values into the isolate's global scope before running code.
+ *
+ * @example
+ * await injectGlobals(ctx.context, {
+ *   testInput: "hello",
+ *   testConfig: { debug: true }
+ * });
+ * const result = evalCode<string>(ctx.context, "testInput");
+ */
+export declare function injectGlobals(context: ivm.Context, values: Record<string, unknown>): Promise<void>;
+export { MockFileSystem } from "./mock-fs.ts";
+export { createFsTestContext } from "./fs-context.ts";
+export type { FsTestContext } from "./fs-context.ts";
+export { createRuntimeTestContext } from "./runtime-context.ts";
+export type { RuntimeTestContext } from "./runtime-context.ts";
+export { startIntegrationServer } from "./server.ts";
+export type { IntegrationServer } from "./server.ts";
+export { runTestCode } from "./native-input-test.ts";
+export type { TestRunner, TestRuntime } from "./native-input-test.ts";
+export { createFetchTestContext } from "./fetch-context.ts";
+export type { FetchTestContext } from "./fetch-context.ts";
+export type { FileSystemHandler } from "@ricsam/isolate-fs";

package/dist/types/mock-fs.d.ts

@@ -0,0 +1,59 @@
+import type { FileSystemHandler } from "@ricsam/isolate-fs";
+/**
+ * In-memory file system implementation for testing.
+ * Implements the FileSystemHandler interface from @ricsam/isolate-fs.
+ */
+export declare class MockFileSystem implements FileSystemHandler {
+    files: Map<string, {
+        data: Uint8Array;
+        lastModified: number;
+        type: string;
+    }>;
+    directories: Set<string>;
+    getFileHandle(path: string, options?: {
+        create?: boolean;
+    }): Promise<void>;
+    getDirectoryHandle(path: string, options?: {
+        create?: boolean;
+    }): Promise<void>;
+    removeEntry(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readDirectory(path: string): Promise<Array<{
+        name: string;
+        kind: "file" | "directory";
+    }>>;
+    readFile(path: string): Promise<{
+        data: Uint8Array;
+        size: number;
+        lastModified: number;
+        type: string;
+    }>;
+    writeFile(path: string, data: Uint8Array, position?: number): Promise<void>;
+    truncateFile(path: string, size: number): Promise<void>;
+    getFileMetadata(path: string): Promise<{
+        size: number;
+        lastModified: number;
+        type: string;
+    }>;
+    /**
+     * Reset the mock file system to its initial state (empty, with only root directory)
+     */
+    reset(): void;
+    /**
+     * Convenience method to set a file with string or binary content
+     */
+    setFile(path: string, content: string | Uint8Array, type?: string): void;
+    /**
+     * Get file content as Uint8Array, or undefined if not found
+     */
+    getFile(path: string): Uint8Array | undefined;
+    /**
+     * Get file content as string, or undefined if not found
+     */
+    getFileAsString(path: string): string | undefined;
+    /**
+     * Create a directory (and any necessary parent directories)
+     */
+    createDirectory(path: string): void;
+}

package/dist/types/native-input-test.d.ts

@@ -0,0 +1,29 @@
+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 declare function runTestCode(context: ivm.Context, code: string): TestRunner;

package/dist/types/runtime-context.d.ts

@@ -0,0 +1,73 @@
+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 {
+    /** 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;
+        stdout: string;
+    }>;
+    /** 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;
+    /**
+     * 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;
+}
+/**
+ * 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 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", stdout: "Starting fetch..." }, ...]
+ *
+ * // Check fetch calls
+ * console.log(ctx.fetchCalls); // [{ url: "https://api.example.com/data", method: "GET", ... }]
+ *
+ * await ctx.dispose();
+ */
+export declare function createRuntimeTestContext(options?: RuntimeTestContextOptions): Promise<RuntimeTestContext>;

package/dist/types/server.d.ts

@@ -0,0 +1,53 @@
+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 declare function startIntegrationServer(port?: number): Promise<IntegrationServer>;

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@ricsam/isolate-test-utils",
-  "version": "0.1.10",
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "version": "0.1.11",
+  "main": "./dist/cjs/index.cjs",
+  "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
-      "import": "./src/index.ts",
-      "types": "./src/index.ts"
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "import": "./dist/mjs/index.mjs"
     },
     "./fs": {
-      "import": "./src/fs-context.ts",
-      "types": "./src/fs-context.ts"
+      "types": "./dist/types/fs-context.d.ts",
+      "require": "./dist/cjs/fs-context.cjs",
+      "import": "./dist/mjs/fs-context.mjs"
     },
     "./runtime": {
-      "import": "./src/runtime-context.ts",
-      "types": "./src/runtime-context.ts"
+      "types": "./dist/types/runtime-context.d.ts",
+      "require": "./dist/cjs/runtime-context.cjs",
+      "import": "./dist/mjs/runtime-context.mjs"
     }
   },
   "scripts": {
@@ -26,12 +28,6 @@
   "dependencies": {
     "isolated-vm": "^6"
   },
-  "devDependencies": {
-    "@ricsam/isolate-fs": "*",
-    "@ricsam/isolate-runtime": "*",
-    "@types/node": "^24",
-    "typescript": "^5"
-  },
   "peerDependencies": {
     "isolated-vm": "^6",
     "@ricsam/isolate-console": "*",
@@ -50,5 +46,36 @@
     "@ricsam/isolate-runtime": {
       "optional": true
     }
-  }
-}
+  },
+  "author": "ricsam <oss@ricsam.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/isolate.git",
+    "directory": "packages/test-utils"
+  },
+  "bugs": {
+    "url": "https://github.com/ricsam/isolate/issues"
+  },
+  "homepage": "https://github.com/ricsam/isolate#readme",
+  "keywords": [
+    "isolated-vm",
+    "sandbox",
+    "javascript",
+    "runtime",
+    "fetch",
+    "filesystem",
+    "streams",
+    "v8",
+    "isolate"
+  ],
+  "description": "Utilities for isolated-vm - run JavaScript in a sandboxed V8 environment with web-standard APIs",
+  "module": "./dist/mjs/index.mjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}

package/CHANGELOG.md

@@ -1,119 +0,0 @@
-# @ricsam/isolate-test-utils
-
-## 0.1.10
-
-### Patch Changes
-
-- new console.log handling
-- Updated dependencies
-  - @ricsam/isolate-console@0.1.10
-  - @ricsam/isolate-runtime@0.1.11
-  - @ricsam/isolate-fetch@0.1.11
-
-## 0.1.9
-
-### Patch Changes
-
-- target node when building
-- Updated dependencies
-  - @ricsam/isolate-console@0.1.9
-  - @ricsam/isolate-core@0.1.9
-  - @ricsam/isolate-fetch@0.1.9
-  - @ricsam/isolate-fs@0.1.9
-  - @ricsam/isolate-runtime@0.1.10
-
-## 0.1.8
-
-### Patch Changes
-
-- various updates
-- Updated dependencies
-  - @ricsam/isolate-console@0.1.8
-  - @ricsam/isolate-core@0.1.8
-  - @ricsam/isolate-fetch@0.1.8
-  - @ricsam/isolate-fs@0.1.8
-  - @ricsam/isolate-runtime@0.1.9
-
-## 0.1.7
-
-### Patch Changes
-
-- fix bugs
-- Updated dependencies
-  - @ricsam/isolate-fetch@0.1.7
-  - @ricsam/isolate-core@0.1.7
-  - @ricsam/isolate-fs@0.1.7
-  - @ricsam/isolate-console@0.1.7
-  - @ricsam/isolate-runtime@0.1.8
-
-## 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
-
-- new packages
-- Updated dependencies
-  - @ricsam/isolate-console@0.1.4
-  - @ricsam/isolate-core@0.1.4
-  - @ricsam/isolate-fetch@0.1.4
-  - @ricsam/isolate-fs@0.1.4
-  - @ricsam/isolate-runtime@0.1.4
-
-## 0.1.3
-
-### Patch Changes
-
-- add playwright package
-- Updated dependencies
-  - @ricsam/isolate-console@0.1.3
-  - @ricsam/isolate-core@0.1.3
-  - @ricsam/isolate-fetch@0.1.3
-  - @ricsam/isolate-fs@0.1.3
-  - @ricsam/isolate-runtime@0.1.3
-
-## 0.1.2
-
-### Patch Changes
-
-- new build script
-- Updated dependencies
-  - @ricsam/isolate-console@0.1.2
-  - @ricsam/isolate-core@0.1.2
-  - @ricsam/isolate-fetch@0.1.2
-  - @ricsam/isolate-fs@0.1.2
-  - @ricsam/isolate-runtime@0.1.2
-
-## 0.1.1
-
-### Patch Changes
-
-- initial release
-- Updated dependencies
-  - @ricsam/isolate-console@0.1.1
-  - @ricsam/isolate-core@0.1.1
-  - @ricsam/isolate-fetch@0.1.1
-  - @ricsam/isolate-fs@0.1.1
-  - @ricsam/isolate-runtime@0.1.1

package/src/fetch-context.ts

@@ -1,33 +0,0 @@
-import type ivm from "isolated-vm";
-import type { TestContext } from "./index.ts";
-
-export interface FetchTestContext extends TestContext {
-  // Context with fetch APIs set up
-}
-
-/**
- * Create a test context with fetch APIs set up (Headers, Request, Response, FormData, fetch)
- */
-export async function createFetchTestContext(): Promise<FetchTestContext> {
-  const ivmModule = await import("isolated-vm");
-  const { setupFetch, clearAllInstanceState } = await import(
-    "@ricsam/isolate-fetch"
-  );
-
-  const isolate = new ivmModule.default.Isolate();
-  const context = await isolate.createContext();
-
-  clearAllInstanceState();
-
-  const fetchHandle = await setupFetch(context);
-
-  return {
-    isolate,
-    context,
-    dispose() {
-      fetchHandle.dispose();
-      context.release();
-      isolate.dispose();
-    },
-  };
-}

package/src/fs-context.ts

@@ -1,65 +0,0 @@
-import type ivm from "isolated-vm";
-import { MockFileSystem } from "./mock-fs.ts";
-
-export interface FsTestContext {
-  isolate: ivm.Isolate;
-  context: ivm.Context;
-  mockFs: MockFileSystem;
-  dispose(): void;
-}
-
-/**
- * Create a test context with file system APIs set up using a mock file system.
- *
- * @example
- * const ctx = await createFsTestContext();
- *
- * // Set up initial files
- * ctx.mockFs.setFile("/test.txt", "Hello, World!");
- *
- * // Use file system APIs in the isolate
- * const result = await ctx.context.eval(`
- *   (async () => {
- *     const root = await navigator.storage.getDirectory();
- *     const fileHandle = await root.getFileHandle("test.txt");
- *     const file = await fileHandle.getFile();
- *     return await file.text();
- *   })()
- * `, { promise: true });
- *
- * ctx.dispose();
- */
-export async function createFsTestContext(): Promise<FsTestContext> {
-  const ivmModule = await import("isolated-vm");
-  const { setupCore, clearAllInstanceState } = await import(
-    "@ricsam/isolate-core"
-  );
-  const { setupFs } = await import("@ricsam/isolate-fs");
-
-  const isolate = new ivmModule.default.Isolate();
-  const context = await isolate.createContext();
-
-  // Clear any previous instance state
-  clearAllInstanceState();
-
-  // Create mock file system
-  const mockFs = new MockFileSystem();
-
-  // Setup core APIs (required for Blob, File, streams)
-  const coreHandle = await setupCore(context);
-
-  // Setup file system APIs with mock handler
-  const fsHandle = await setupFs(context, { getDirectory: async () => mockFs });
-
-  return {
-    isolate,
-    context,
-    mockFs,
-    dispose() {
-      fsHandle.dispose();
-      coreHandle.dispose();
-      context.release();
-      isolate.dispose();
-    },
-  };
-}