@ricsam/quickjs-test-environment

Test primitives for running tests in sandboxed QuickJS. Provides a Bun/Jest/Vitest-compatible API with event-based result streaming.

> Note: This is a low-level package. For most use cases, use @ricsam/quickjs-runtime with createRuntime({ testEnvironment: true }) instead.

Installation

``bash
bun add @ricsam/quickjs-test-environment
`

Setup

`typescript
import { setupTestEnvironment } from "@ricsam/quickjs-test-environment";

const handle = setupTestEnvironment(context, {
onEvent: (event) => {
if (event.type === "testEnd") {
const icon = event.test.status === "pass" ? "✓" : "✗";
console.log(${icon} ${event.test.fullName});
if (event.test.error) {
console.log( Error: ${event.test.error.message});
}
} else if (event.type === "runEnd") {
console.log(\n${event.results.passed}/${event.results.total} tests passed);
}
},
});
`

Injected Globals

- describe, it, test (with .skip, .only, .todo modifiers)
- beforeAll, afterAll, beforeEach, afterEach
- expect with matchers (toBe, toEqual, toThrow, etc.) and modifiers (.not, .resolves, .rejects)

Usage in QuickJS

`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);
});
});
});
`

Running Tests from Host

`typescript
// Load untrusted test code
context.evalCode(userProvidedTestCode);

// Check test count
console.log(Found ${handle.getTestCount()} tests);

// Run all registered tests
const results = await handle.run();
console.log(${results.passed}/${results.total} passed);

// Reset for re-running (optional)
handle.reset();

handle.dispose();
`

TestEvent Types

| Event Type | Description |
|------------|-------------|
| runStart | Emitted when test run begins (includes testCount, suiteCount) |
| suiteStart | Emitted when a describe block begins |
| suiteEnd | Emitted when a describe block completes |
| testStart | Emitted before each test runs |
| testEnd | Emitted when a test completes (includes status: pass/fail/skip/todo) |
| runEnd | Emitted after all tests complete (includes full results`) |