@ricsam/isolate-test-environment 0.1.3 → 0.1.6

package/README.md

@@ -2,18 +2,67 @@
 
 Test primitives for running tests in sandboxed V8. Provides a Jest/Vitest-compatible API.
 
+## Installation
+
+```bash
+npm add @ricsam/isolate-test-environment
+```
+
+## Usage with isolate-runtime (Recommended)
+
+The easiest way to use this package is through `@ricsam/isolate-runtime`:
+
+```typescript
+import { createRuntime } from "@ricsam/isolate-runtime";
+
+const runtime = await createRuntime({
+  testEnvironment: {
+    onEvent: (event) => {
+      // Receive lifecycle events during test execution
+      if (event.type === "testEnd") {
+        const icon = event.test.status === "pass" ? "✓" : "✗";
+        console.log(`${icon} ${event.test.fullName}`);
+      }
+    },
+  },
+});
+
+await runtime.eval(`
+  describe("math", () => {
+    it("adds numbers", () => {
+      expect(1 + 1).toBe(2);
+    });
+    it.todo("subtract numbers");
+  });
+`);
+
+const results = await runtime.testEnvironment.runTests();
+console.log(`${results.passed}/${results.total} passed, ${results.todo} todo`);
+
+// Check if tests exist before running
+if (runtime.testEnvironment.hasTests()) {
+  console.log(`Found ${runtime.testEnvironment.getTestCount()} tests`);
+}
+```
+
+## Low-level Usage (Direct ivm)
+
+For advanced use cases with direct isolated-vm access:
+
 ```typescript
 import { setupTestEnvironment, runTests } from "@ricsam/isolate-test-environment";
 
 const handle = await setupTestEnvironment(context);
 ```
 
-**Injected Globals:**
+## Injected Globals
+
 - `describe`, `it`, `test` (with `.skip`, `.only`, `.todo` modifiers)
 - `beforeAll`, `afterAll`, `beforeEach`, `afterEach`
 - `expect` with matchers and `.not` modifier
 
-**Expect Matchers:**
+## Expect Matchers
+
 - `toBe(expected)` - Strict equality (`===`)
 - `toEqual(expected)` - Deep equality
 - `toStrictEqual(expected)` - Strict deep equality (includes prototype checks)
@@ -26,7 +75,7 @@ const handle = await setupTestEnvironment(context);
 - `toMatch(pattern)` - String/regex match
 - `toHaveProperty(path, value?)` - Object property check
 
-**Usage in Isolate:**
+## Usage in Isolate
 
 ```javascript
 describe("Math operations", () => {
@@ -57,35 +106,107 @@ expect(1).not.toBe(2);
 expect([1, 2]).not.toContain(3);
 ```
 
-**Running tests from host:**
+## Running Tests from Host
 
 ```typescript
-import { setupTestEnvironment, runTests } from "@ricsam/isolate-test-environment";
-
-// Setup test environment
-const handle = await setupTestEnvironment(context);
+import { setupTestEnvironment, runTests, hasTests, getTestCount } from "@ricsam/isolate-test-environment";
+
+// Setup test environment with optional event callback
+const handle = await setupTestEnvironment(context, {
+  onEvent: (event) => {
+    switch (event.type) {
+      case "runStart":
+        console.log(`Running ${event.testCount} tests in ${event.suiteCount} suites`);
+        break;
+      case "testEnd":
+        console.log(`${event.test.status}: ${event.test.fullName}`);
+        break;
+    }
+  },
+});
 
 // Load test code
 await context.eval(userProvidedTestCode, { promise: true });
 
+// Check if any tests were registered
+if (hasTests(context)) {
+  console.log(`Found ${getTestCount(context)} tests`);
+}
+
 // Run all registered tests
 const results = await runTests(context);
 console.log(`${results.passed}/${results.total} passed`);
 
-// Results structure:
-// {
-//   passed: number,
-//   failed: number,
-//   skipped: number,
-//   total: number,
-//   results: Array<{
-//     name: string,
-//     passed: boolean,
-//     error?: string,
-//     duration: number,
-//     skipped?: boolean
-//   }>
-// }
-
 handle.dispose();
-```
+```
+
+## Types
+
+### RunResults
+
+```typescript
+interface RunResults {
+  passed: number;
+  failed: number;
+  skipped: number;
+  todo: number;
+  total: number;
+  duration: number;
+  success: boolean;        // true if no failures
+  suites: SuiteResult[];   // suite-level results
+  tests: TestResult[];     // individual test results
+}
+```
+
+### TestResult
+
+```typescript
+interface TestResult {
+  name: string;
+  suitePath: string[];     // suite ancestry
+  fullName: string;        // "suite > nested > test name"
+  status: "pass" | "fail" | "skip" | "todo";
+  duration: number;
+  error?: TestError;
+}
+
+interface TestError {
+  message: string;
+  stack?: string;
+  expected?: unknown;      // for assertion failures
+  actual?: unknown;
+  matcherName?: string;    // e.g., "toBe", "toEqual"
+}
+```
+
+### SuiteResult
+
+```typescript
+interface SuiteResult {
+  name: string;
+  path: string[];          // ancestry path
+  fullName: string;        // "outer > inner"
+  depth: number;           // nesting level (0 for root)
+  passed: number;
+  failed: number;
+  skipped: number;
+  todo: number;
+  duration: number;
+}
+```
+
+### TestEvent
+
+```typescript
+type TestEvent =
+  | { type: "runStart"; testCount: number; suiteCount: number }
+  | { type: "suiteStart"; suite: SuiteInfo }
+  | { type: "suiteEnd"; suite: SuiteResult }
+  | { type: "testStart"; test: TestInfo }
+  | { type: "testEnd"; test: TestResult }
+  | { type: "runEnd"; results: RunResults };
+```
+
+## License
+
+MIT