@ricsam/isolate-test-environment 0.0.1 → 0.1.2

package/README.md

@@ -1,45 +1,91 @@
 # @ricsam/isolate-test-environment
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ricsam/isolate-test-environment`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Test primitives for running tests in sandboxed V8. Provides a Jest/Vitest-compatible API.
+
+```typescript
+import { setupTestEnvironment, runTests } from "@ricsam/isolate-test-environment";
+
+const handle = await setupTestEnvironment(context);
+```
+
+**Injected Globals:**
+- `describe`, `it`, `test` (with `.skip`, `.only`, `.todo` modifiers)
+- `beforeAll`, `afterAll`, `beforeEach`, `afterEach`
+- `expect` with matchers and `.not` modifier
+
+**Expect Matchers:**
+- `toBe(expected)` - Strict equality (`===`)
+- `toEqual(expected)` - Deep equality
+- `toStrictEqual(expected)` - Strict deep equality (includes prototype checks)
+- `toBeTruthy()`, `toBeFalsy()`
+- `toBeNull()`, `toBeUndefined()`, `toBeDefined()`
+- `toContain(item)` - Array/string includes
+- `toThrow(expected?)` - Function throws
+- `toBeInstanceOf(cls)` - Instance check
+- `toHaveLength(length)` - Array/string length
+- `toMatch(pattern)` - String/regex match
+- `toHaveProperty(path, value?)` - Object property check
+
+**Usage in Isolate:**
+
+```javascript
+describe("Math operations", () => {
+  beforeEach(() => {
+    // setup before each test
+  });
+
+  it("should add numbers", () => {
+    expect(1 + 1).toBe(2);
+  });
+
+  it("should multiply numbers", async () => {
+    await Promise.resolve();
+    expect(2 * 3).toEqual(6);
+  });
+
+  describe("edge cases", () => {
+    it.skip("should handle infinity", () => {
+      expect(1 / 0).toBe(Infinity);
+    });
+
+    it.todo("should handle NaN");
+  });
+});
+
+// Negation with .not
+expect(1).not.toBe(2);
+expect([1, 2]).not.toContain(3);
+```
+
+**Running tests from host:**
+
+```typescript
+import { setupTestEnvironment, runTests } from "@ricsam/isolate-test-environment";
+
+// Setup test environment
+const handle = await setupTestEnvironment(context);
+
+// Load test code
+await context.eval(userProvidedTestCode, { promise: true });
+
+// 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();
+```