@ricsam/quickjs-test-environment

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

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

const handle = setupTestEnvironment(context, {
  onTestPass: (test) => console.log(`✓ ${test.fullName}`),
  onTestFail: (test) => console.log(`✗ ${test.fullName}: ${test.error?.message}`),
  onRunComplete: (results) => {
    console.log(`\n${results.passed}/${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();

Event Handlers:

| Handler | Description | |---------|-------------| | onSuiteStart | Called when a describe block begins | | onSuiteEnd | Called when a describe block completes | | onTestStart | Called before each test runs | | onTestPass | Called when a test passes | | onTestFail | Called when a test fails | | onRunComplete | Called after all tests complete |