@ricsam/isolate-test-utils 0.0.1 → 0.1.2

package/src/index.ts

@@ -0,0 +1,177 @@
+import type ivm from "isolated-vm";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface TestContext {
+  isolate: ivm.Isolate;
+  context: ivm.Context;
+  dispose(): void;
+}
+
+export interface TestResult<T> {
+  result: T;
+  logs: Array<{ level: string; args: unknown[] }>;
+}
+
+// ============================================================================
+// Context Creation
+// ============================================================================
+
+/**
+ * Create a basic test context for isolated-vm tests.
+ * This creates a bare context without any APIs set up.
+ */
+export async function createTestContext(): Promise<TestContext> {
+  const ivm = await import("isolated-vm");
+  const isolate = new ivm.default.Isolate();
+  const context = await isolate.createContext();
+
+  return {
+    isolate,
+    context,
+    dispose() {
+      context.release();
+      isolate.dispose();
+    },
+  };
+}
+
+/**
+ * Create a test context with core APIs set up (Blob, File, URL, streams, etc.)
+ */
+export async function createCoreTestContext(): Promise<TestContext> {
+  const ivm = await import("isolated-vm");
+  const { setupCore } = await import("@ricsam/isolate-core");
+
+  const isolate = new ivm.default.Isolate();
+  const context = await isolate.createContext();
+  const coreHandle = await setupCore(context);
+
+  return {
+    isolate,
+    context,
+    dispose() {
+      coreHandle.dispose();
+      context.release();
+      isolate.dispose();
+    },
+  };
+}
+
+// ============================================================================
+// Code Evaluation Helpers
+// ============================================================================
+
+/**
+ * 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 function evalCode<T = unknown>(context: ivm.Context, code: string): T {
+  return context.evalSync(code) as 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 async function evalCodeAsync<T = unknown>(
+  context: ivm.Context,
+  code: string
+): Promise<T> {
+  return (await context.eval(code, { promise: true })) as 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 function evalCodeJson<T = unknown>(context: ivm.Context, code: string): T {
+  const jsonString = context.evalSync(code) as string;
+  return JSON.parse(jsonString) as 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 async function evalCodeJsonAsync<T = unknown>(
+  context: ivm.Context,
+  code: string
+): Promise<T> {
+  const jsonString = (await context.eval(code, { promise: true })) as string;
+  return JSON.parse(jsonString) as 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 async function injectGlobals(
+  context: ivm.Context,
+  values: Record<string, unknown>
+): Promise<void> {
+  const global = context.global;
+
+  for (const [key, value] of Object.entries(values)) {
+    if (typeof value === "function") {
+      const ivm = await import("isolated-vm");
+      global.setSync(key, new ivm.default.Callback(value as (...args: unknown[]) => unknown));
+    } else if (typeof value === "object" && value !== null) {
+      // For objects, serialize as JSON and inject
+      context.evalSync(`globalThis.${key} = ${JSON.stringify(value)}`);
+    } else {
+      // For primitives, set directly
+      global.setSync(key, value);
+    }
+  }
+}
+
+// ============================================================================
+// Exports from other modules
+// ============================================================================
+
+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";
+
+// Re-export useful types
+export type { FileSystemHandler } from "@ricsam/isolate-fs";

package/src/mock-fs.ts

@@ -0,0 +1,246 @@
+import type { FileSystemHandler } from "@ricsam/isolate-fs";
+
+/**
+ * In-memory file system implementation for testing.
+ * Implements the FileSystemHandler interface from @ricsam/isolate-fs.
+ */
+export class MockFileSystem implements FileSystemHandler {
+  files = new Map<
+    string,
+    { data: Uint8Array; lastModified: number; type: string }
+  >();
+  directories = new Set<string>(["/"]);
+
+  async getFileHandle(
+    path: string,
+    options?: { create?: boolean }
+  ): Promise<void> {
+    const exists = this.files.has(path);
+    if (!exists && !options?.create) {
+      throw new Error("[NotFoundError]File not found: " + path);
+    }
+    if (this.directories.has(path)) {
+      throw new Error("[TypeMismatchError]Path is a directory: " + path);
+    }
+    if (!exists && options?.create) {
+      this.files.set(path, {
+        data: new Uint8Array(0),
+        lastModified: Date.now(),
+        type: "",
+      });
+    }
+  }
+
+  async getDirectoryHandle(
+    path: string,
+    options?: { create?: boolean }
+  ): Promise<void> {
+    const exists = this.directories.has(path);
+    if (!exists && !options?.create) {
+      throw new Error("[NotFoundError]Directory not found: " + path);
+    }
+    if (this.files.has(path)) {
+      throw new Error("[TypeMismatchError]Path is a file: " + path);
+    }
+    if (!exists && options?.create) {
+      this.directories.add(path);
+    }
+  }
+
+  async removeEntry(
+    path: string,
+    options?: { recursive?: boolean }
+  ): Promise<void> {
+    if (this.files.has(path)) {
+      this.files.delete(path);
+      return;
+    }
+
+    if (this.directories.has(path)) {
+      const prefix = path === "/" ? "/" : path + "/";
+      const hasChildren =
+        [...this.files.keys()].some((p) => p.startsWith(prefix)) ||
+        [...this.directories].some((p) => p !== path && p.startsWith(prefix));
+
+      if (hasChildren && !options?.recursive) {
+        throw new Error("[InvalidModificationError]Directory not empty: " + path);
+      }
+
+      for (const p of this.files.keys()) {
+        if (p.startsWith(prefix)) {
+          this.files.delete(p);
+        }
+      }
+      for (const p of this.directories) {
+        if (p.startsWith(prefix) || p === path) {
+          this.directories.delete(p);
+        }
+      }
+      return;
+    }
+
+    throw new Error("[NotFoundError]Entry not found: " + path);
+  }
+
+  async readDirectory(
+    path: string
+  ): Promise<Array<{ name: string; kind: "file" | "directory" }>> {
+    if (!this.directories.has(path)) {
+      throw new Error("[NotFoundError]Directory not found: " + path);
+    }
+
+    const prefix = path === "/" ? "/" : path + "/";
+    const entries: Array<{ name: string; kind: "file" | "directory" }> = [];
+    const seen = new Set<string>();
+
+    for (const p of this.files.keys()) {
+      if (p.startsWith(prefix)) {
+        const rest = p.slice(prefix.length);
+        const name = rest.split("/")[0];
+        if (name && !rest.includes("/") && !seen.has(name)) {
+          seen.add(name);
+          entries.push({ name, kind: "file" });
+        }
+      }
+    }
+
+    for (const p of this.directories) {
+      if (p !== path && p.startsWith(prefix)) {
+        const rest = p.slice(prefix.length);
+        const name = rest.split("/")[0];
+        if (name && !rest.includes("/") && !seen.has(name)) {
+          seen.add(name);
+          entries.push({ name, kind: "directory" });
+        }
+      }
+    }
+
+    return entries;
+  }
+
+  async readFile(
+    path: string
+  ): Promise<{ data: Uint8Array; size: number; lastModified: number; type: string }> {
+    const file = this.files.get(path);
+    if (!file) {
+      throw new Error("[NotFoundError]File not found: " + path);
+    }
+    return {
+      data: file.data,
+      size: file.data.length,
+      lastModified: file.lastModified,
+      type: file.type,
+    };
+  }
+
+  async writeFile(
+    path: string,
+    data: Uint8Array,
+    position?: number
+  ): Promise<void> {
+    const existing = this.files.get(path);
+    if (!existing) {
+      throw new Error("[NotFoundError]File not found: " + path);
+    }
+
+    if (position !== undefined && position > 0) {
+      const newSize = Math.max(existing.data.length, position + data.length);
+      const newData = new Uint8Array(newSize);
+      newData.set(existing.data);
+      newData.set(data, position);
+      existing.data = newData;
+    } else if (position === 0) {
+      const newSize = Math.max(existing.data.length, data.length);
+      const newData = new Uint8Array(newSize);
+      newData.set(existing.data);
+      newData.set(data, 0);
+      existing.data = newData;
+    } else {
+      existing.data = data;
+    }
+    existing.lastModified = Date.now();
+  }
+
+  async truncateFile(path: string, size: number): Promise<void> {
+    const file = this.files.get(path);
+    if (!file) {
+      throw new Error("[NotFoundError]File not found: " + path);
+    }
+    if (size < file.data.length) {
+      file.data = file.data.slice(0, size);
+    } else if (size > file.data.length) {
+      const newData = new Uint8Array(size);
+      newData.set(file.data);
+      file.data = newData;
+    }
+    file.lastModified = Date.now();
+  }
+
+  async getFileMetadata(
+    path: string
+  ): Promise<{ size: number; lastModified: number; type: string }> {
+    const file = this.files.get(path);
+    if (!file) {
+      throw new Error("[NotFoundError]File not found: " + path);
+    }
+    return {
+      size: file.data.length,
+      lastModified: file.lastModified,
+      type: file.type,
+    };
+  }
+
+  // Test helper methods
+
+  /**
+   * Reset the mock file system to its initial state (empty, with only root directory)
+   */
+  reset(): void {
+    this.files.clear();
+    this.directories.clear();
+    this.directories.add("/");
+  }
+
+  /**
+   * Convenience method to set a file with string or binary content
+   */
+  setFile(path: string, content: string | Uint8Array, type?: string): void {
+    const data =
+      typeof content === "string"
+        ? new TextEncoder().encode(content)
+        : content;
+    this.files.set(path, {
+      data,
+      lastModified: Date.now(),
+      type: type ?? "",
+    });
+  }
+
+  /**
+   * Get file content as Uint8Array, or undefined if not found
+   */
+  getFile(path: string): Uint8Array | undefined {
+    return this.files.get(path)?.data;
+  }
+
+  /**
+   * Get file content as string, or undefined if not found
+   */
+  getFileAsString(path: string): string | undefined {
+    const data = this.getFile(path);
+    if (!data) return undefined;
+    return new TextDecoder().decode(data);
+  }
+
+  /**
+   * Create a directory (and any necessary parent directories)
+   */
+  createDirectory(path: string): void {
+    const parts = path.split("/").filter(Boolean);
+    let current = "";
+    for (const part of parts) {
+      current += "/" + part;
+      this.directories.add(current);
+    }
+  }
+}