@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

bun add @ricsam/quickjs-test-environment

Setup

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

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

// 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) |