@ricsam/isolate-runtime 0.1.14 → 0.1.16

package/README.md

@@ -115,19 +115,16 @@ interface RuntimeOptions {
   cwd?: string;
   /** Enable test environment (describe, it, expect) */
   testEnvironment?: boolean | TestEnvironmentOptions;
-  /** Playwright options - user provides page object */
+  /** Playwright options (handler-first public API) */
   playwright?: PlaywrightOptions;
 }
 
 interface PlaywrightOptions {
-  page: import("playwright").Page;
+  handler: (op: PlaywrightOperation) => Promise<PlaywrightResult>;
   timeout?: number;
   /** Print browser console logs to stdout */
   console?: boolean;
-  /** Browser console log callback (from the page, not sandbox) */
-  onBrowserConsoleLog?: (entry: { level: string; stdout: string; timestamp: number }) => void;
-  onNetworkRequest?: (info: { url: string; method: string; headers: Record<string, string>; timestamp: number }) => void;
-  onNetworkResponse?: (info: { url: string; status: number; headers: Record<string, string>; timestamp: number }) => void;
+  onEvent?: (event: PlaywrightEvent) => void;
 }
 ```
 
@@ -309,20 +306,27 @@ type TestEvent =
 
 ## Playwright Integration
 
-Run browser automation with untrusted code. **You provide the Playwright page object**:
+Run browser automation with untrusted code. Public API is handler-first:
+
+```typescript
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
+
+playwright: { handler: defaultPlaywrightHandler(page) }
+```
 
 ### Script Mode (No Tests)
 
 ```typescript
 import { createRuntime } from "@ricsam/isolate-runtime";
 import { chromium } from "playwright";
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
 
 const browser = await chromium.launch({ headless: true });
 const page = await browser.newPage();
 
 const runtime = await createRuntime({
   playwright: {
-    page,
+    handler: defaultPlaywrightHandler(page),
     console: true, // Print browser console to stdout
   },
 });
@@ -349,6 +353,7 @@ Combine `testEnvironment` and `playwright` for browser testing. Playwright exten
 ```typescript
 import { createRuntime } from "@ricsam/isolate-runtime";
 import { chromium } from "playwright";
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
 
 const browser = await chromium.launch({ headless: true });
 const page = await browser.newPage();
@@ -356,8 +361,12 @@ const page = await browser.newPage();
 const runtime = await createRuntime({
   testEnvironment: true, // Provides describe, it, expect
   playwright: {
-    page,
-    onBrowserConsoleLog: (entry) => console.log("[browser]", entry.stdout),
+    handler: defaultPlaywrightHandler(page),
+    onEvent: (event) => {
+      if (event.type === "browserConsoleLog") {
+        console.log("[browser]", event.stdout);
+      }
+    },
   },
 });
 
@@ -383,6 +392,74 @@ await runtime.dispose();
 await browser.close();
 ```
 
+### Multi-Page Testing
+
+For tests that need multiple pages or browser contexts, provide `createPage` and/or `createContext` callbacks:
+
+```typescript
+import { createRuntime } from "@ricsam/isolate-runtime";
+import { chromium } from "playwright";
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
+
+const browser = await chromium.launch({ headless: true });
+const browserContext = await browser.newContext();
+const page = await browserContext.newPage();
+
+const runtime = await createRuntime({
+  testEnvironment: true,
+  playwright: {
+    handler: defaultPlaywrightHandler(page, {
+      // Called when isolate code calls context.newPage()
+      createPage: async (context) => context.newPage(),
+      // Called when isolate code calls browser.newContext()
+      createContext: async (options) => browser.newContext(options),
+    }),
+  },
+});
+
+await runtime.eval(`
+  test('multi-page test', async () => {
+    // Create additional pages
+    const page2 = await context.newPage();
+
+    // Navigate independently
+    await page.goto('https://example.com/page1');
+    await page2.goto('https://example.com/page2');
+
+    // Work with multiple pages
+    await page.locator('#button').click();
+    await page2.locator('#input').fill('text');
+
+    await page2.close();
+  });
+
+  test('multi-context test', async () => {
+    // Create isolated context (separate cookies, storage)
+    const ctx2 = await browser.newContext();
+    const page2 = await ctx2.newPage();
+
+    // Cookies are isolated between contexts
+    await context.addCookies([{ name: 'test', value: '1', domain: 'example.com', path: '/' }]);
+    const ctx1Cookies = await context.cookies();
+    const ctx2Cookies = await ctx2.cookies();
+
+    expect(ctx1Cookies.some(c => c.name === 'test')).toBe(true);
+    expect(ctx2Cookies.some(c => c.name === 'test')).toBe(false);
+
+    await ctx2.close();
+  });
+`);
+
+const results = await runtime.testEnvironment.runTests();
+await runtime.dispose();
+await browser.close();
+```
+
+**Behavior without lifecycle callbacks:**
+- `context.newPage()` without `createPage`: Throws error
+- `browser.newContext()` without `createContext`: Throws error
+- `context.cookies()`, `context.addCookies()`, `context.clearCookies()`: Work without callbacks
+
 ## Included APIs
 
 - Core (Blob, File, streams, URL, TextEncoder/Decoder)
@@ -394,20 +471,7 @@ await browser.close();
 - Fetch API
 - File System (if handler provided)
 - Test Environment (if enabled)
-- Playwright (if page provided)
-
-## Legacy API
-
-For backwards compatibility with code that needs direct isolate/context access:
-
-```typescript
-import { createLegacyRuntime } from "@ricsam/isolate-runtime";
-
-const runtime = await createLegacyRuntime();
-// runtime.isolate and runtime.context are available
-await runtime.context.eval(`console.log("Hello")`);
-runtime.dispose(); // sync
-```
+- Playwright (if handler provided)
 
 ## License