vitest-pool-assemblyscript

Status

This project is relatively new to the scene, but is stable and is being improved every day. Please give it a try!

All listed features are working and assumed to be bug-free (please report any).

| Item | Status | |---|---| | describe() and test() APIs | - stable- no breaking changes expected | | expect() API | - stable- no breaking changes expected- more matchers coming soon | | Code Coverage / Instrumentation | - function coverage stable across platforms- branch & line coverage coming soon | | Hybrid Coverage Provider | - stable- v8 JS delegation, side-by-side JS coverage- istanbul JS delegation coming soon

See Also:

• Current Limitations & Roadmap
• Frequently Asked Questions
• Report a Bug / Request a Feature

Quick Start

1. Install

npm install -D vitest vitest-pool-assemblyscript assemblyscript

2. Configure Vitest

Create or update vitest.config.ts. See the Configuration Guide for all supported vitest options, pool options, coverage configuration, and multi-project setups.

vitest 4.x:

import { defineConfig } from 'vitest/config';
import { createAssemblyScriptPool } from 'vitest-pool-assemblyscript/config';

export default defineConfig({
  test: {
    include: ['test/assembly/**/*.as.test.ts'],
    pool: createAssemblyScriptPool(),
  },
  coverage: {
    provider: 'custom',
    customProviderModule: 'vitest-pool-assemblyscript/coverage',
    assemblyScriptInclude: ['assembly/**/*.ts'],
    enabled: true,
  },
});

vitest 3.x:

import { defineAssemblyScriptConfig } from 'vitest-pool-assemblyscript/v3/config';

export default defineAssemblyScriptConfig({
  test: {
    include: ['test/assembly/**/*.as.test.ts'],
    pool: 'vitest-pool-assemblyscript/v3',
  },
  // coverage configuration mirrors v4
});

3. Write a Test

Create a test file (e.g. test/assembly/example-file.as.test.ts):

import { test, describe, expect } from "vitest-pool-assemblyscript/assembly";

test("basic math", () => {
  expect(2 + 2).toBe(4);
});

describe("an example suite", () => {
  test("string equality", () => {
    expect("hello").toBe("hello");
    expect("hello").not.toBe("world");
  });
});

4. Run

npx vitest run

Features

Vitest Integration

• Use familiar vitest commands, CLI spec and test filtering, watch mode
• Works with Vitest UI, reporters, and coverage tools
• Project (workspace) config allows coexisting AssemblyScript pools and JavaScript pools
• Hybrid Coverage Provider unifies test reports from multiple pools (delegating to v8 for JS/TS coverage)
• Coverage reporting using any vitest reporter (html, lcov, json, etc)
• Dual vitest 3.x / 4.x support

Per-Test WASM Isolation

• Each AssemblyScript test file is compiled to a WASM binary once
• Each test case runs in a fresh WASM instance (reusing the compiled binary)
• One crashing test doesn't kill the rest within the same suite
• toThrowError() matcher can be used to catch and expect specific errors (which trap and abort)

Familiar Developer Experience

• Suite and test definition using describe() and test() in AssemblyScript
• Inline test option configuration for common vitest options: timeout, retry, skip, only, fails
• Assertion matching API based on vitest/jest expect() API
  • .not, toBe, toBeCloseTo, toEqual (with caveats*), toStrictEqual, toBeGreaterThan, toBeGreaterThanOrEqual, toBeLessThan, toBeLessThanOrEqual, toHaveLength, toThrowError, toBeTruthy, toBeFalsy, toBeNull, toBeNullable, toBeNaN
  • See Matchers API for details and differences from JavaScript
• Highlighted diffs for assertion and runtime failures, which point to source code
• Source-mapped WASM error stack traces (accurate AssemblyScript source function file:line:column)
• AssemblyScript console output captured and provided to vitest for display
• AssemblyScript compiler errors output plainly to the console for debugging
• AssemblyScript source code coverage based on WASM execution, including uncovered source
• No AssemblyScript boilerplate patterns for: run(), endTest(), fs.readFile, WebAssembly.Instance, etc

Performance & Customization

• Parallel execution thread pools
• In-memory binaries and source maps for minimal file I/O
• Lightweight coverage instrumentation using separate WASM memory (no intermediate JS boundary crossing, no user memory conflicts)
• Coverage for inlined (@inline) code
• Enforced hard timeouts for long-running WASM via thread termination, with intelligent resume
• Configurable AssemblyScript compiler options
• Configurable test memory size
• User-provided WASM imports with access to test memory

Frequently Asked Questions

Q: How does this work? A: Vitest has a custom pool API that lets you define the execution environment for the tests it runs (internally, vitest uses its own pools to run JavaScript and TypeScript tests). This custom pool uses the AssemblyScript compiler to compile each test file to WASM, instruments the WASM binary for code coverage, then runs each test in an isolated WASM instance and reports results back to vitest through its standard RPC reporting mechanism.

More detailed information can be found in Pool Architecture and Coverage Architecture

Q: So it is really using vitest? A: Yes! It's a real vitest pool, not a clone of vitest - it hooks directly into the framework, receiving tests to run from vitest and reporting results back. The pool implements its own compilation, test execution, and matchers in AS, designed to mirror the vitest expect() API. We don't use vite build integration, but that's the tradeoff of a custom pool - you can bring any execution environment to vitest.

The overall goal is tight vitest experience integration - most CLI commands, reporters, UI, and project configurations should work as you'd expect, and test runner behavior should match vitest's JS pool runner for features we've implemented (retries, timeouts, skip, only, fails, etc.). Some features aren't implemented yet due to effort and prioritization, and others necessarily differ given AssemblyScript's static typing and execution model. See the configuration guide and limitations / roadmap for specifics.

Q: Will this work on my machine? A: Probably! WASM coverage instrumentation requires native binaries, and we ship prebuilt binaries for most common platforms. If your platform isn't listed, the npm package installation will fallback to trying to build the native code using a local C++ toolchain.

Q: Do you support older versions of AssemblyScript? A: It's tested against 0.28.9 currently, and that's the version I have any real experience with. Older versions might work but aren't actively tested. If you're stuck on an older version and run into issues, you're welcome to open an issue.

Q: Is this an official vitest project? A: No, this is a third-party community project. It's not affiliated with or endorsed by the vitest team, though we're grateful for their extensible architecture that makes projects like this possible, and the other open-source projects that provide vital functionality and reference architecture.

Q: Are you a company? A bot? A: Just a person! This started as a hobby project to improve my own AssemblyScript testing workflow and to learn something about deep WASM internals, and it's grown from there. I used Claude Code for initial scaffolding and to help dig into the native instrumentation side, but everything goes through me, and my intention is to contribute something useful and high-quality to the community. Feedback and contributions are welcome.

Compatibility

| Dependency | Supported Versions | |---|---| | Node.js | (20*), 22, 24+ | | Vitest | 3.2.x, 4.x.x | | AssemblyScript | 0.28.9+ (more?) |

ℹ️ *Node 20 Support: If you don't need code coverage, Node 20 should continue to work for test execution.

WASM coverage instrumentation is implemented using WebAssembly multi-memory to isolate coverage counters from user test memory. This feature shipped in V8 12.0 / Node 22.

Platforms with prebuilt native binaries for coverage instrumentation & debug info:

| | x64 | arm64 | |---|---|---| | Linux (glibc) | ✓ | ✓ | | Linux (musl/Alpine) | ✓ | | | macOS | ✓ | ✓ | | Windows | ✓ | ✓ |

Writing Tests

Import test, describe, expect from vitest-pool-assemblyscript/assembly. These functions are designed to follow the vitest API as closely as possible, so that everything is familiar and easy to reason about.

• it is available as an alias for test
• describe and test have inline modifiers to quickly change their run mode (see below)
• TestOptions allows per-test inline configuration of additional options (aligned with vitest behavior)

import { test, it, describe, expect, TestOptions } from "vitest-pool-assemblyscript/assembly";
import { add } from "../assembly/math.ts";

test("a test", () => {
  expect(1 + 1).toBe(2);
  expect(add(3, 2)).toBe(5);
});

describe("a suite of math operations", () => {
  test("another test", () => {
    expect(3 - 1).toBe(2);
  });

  describe("a nested suite of float operations", () => {
    it("tests something else", () => {
      expect(0.1 + 0.2).toBeCloseTo(0.3);
    });
  });
});

Inline Run Mode Modifiers: .skip, .only, .fails

These modify the way in which tests run in relation to each other, and/or how they report results.

They follow vitest JS-pool behavior.

test.skip("not ready yet", () => {
  // test will register it exists, show as skipped
});

test.only("debugging this test", () => {
  // test will run by itself in this file
});

test.fails("conditions are expected to fail, so test will actually pass", () => {
  expect(false).toBeTruthy();
});

test.fails("conditions are expected to fail but do not, so test will actually fail", () => {
  expect(true).toBeTruthy();
});

describe.skip("entire suite skipped", () => { /* ... */ });

describe.only("only this suite runs", () => { /* ... */ });

Inline Test Options

TestOptions provides chainable configuration for the vitest behavioral options: timeout, retry, skip, only, and fails

• While you define them slightly differently in AssemblyScript than JavaScript, their behavior matches the same options in vitest
• Options can be placed before or after the callback
• Suite options (in describe) are inherited by nested tests and nested suites

// options before callback
test("with timeout", TestOptions.timeout(500), () => { /* ... */ });

// options after callback
test("with retry", () => { /* ... */ }, TestOptions.retry(3));

// chained options
test("with both", TestOptions.timeout(500).retry(2), () => { /* ... */ });

// suite-level options are inherited by nested tests
describe("slow tests", TestOptions.timeout(1000), () => {
  test("inherits suite timeout", () => { /* ... */ });

  // test-level options override suite options
  test("custom retry", TestOptions.retry(5), () => { /* ... */ });
});

// modifiers and options can be combined
test.fails("expected failure with retry", TestOptions.retry(3), () => {
  expect(false).toBeTruthy();
});

Lifecycle Hooks (Setup & Teardown)

Coming Soon!

Test Matchers

We aim to follow the vitest/jest expect() API as closely as possible, with some necessary differences given AssemblyScript's static-typing.

See the AssemblyScript Pool Matchers API documentation for details on the available expect() methods you can use within your tests.

Current Limitations & Roadmap

Limitations

These are known limitations which are currently being worked on.

• Function-level coverage only: No statement, branch, or line coverage yet
• No lifecycle hooks: No setup/teardown hooks yet
• Watch mode handles specs only: Re-runs test files when they are directly changed, but not yet based on changed source files
• toEqual doesn't reflect: Doesn't yet support deep inspection of user-defined objects

Near Future Roadmap

Epic: Enhanced block-level coverage

• Block-level statement coverage (line granularity)
• Branch coverage using CFG analysis
• All 4 coverage types (function, statement, branch, line)

Epic: Testing DX

• Lifecycle hooks (beforeEach, afterEach, beforeAll, afterAll)
• Watch mode: re-run applicable tests on source file changes
• toEqual reflection for deep equality inspection of user objects
• describe.for/each and test.for/each
• expect.soft to prevent fail-fast behavior
• Allow delegating JS/TS to istanbul coverage provider in addition to v8
• Maybe: Per-file compilation setting override

Epic: Expand expect matcher API

• Planned: toBeDefined, toBeUndefined, toContain, toContainEqual
• Likely: toBeOneOf, toBeTypeOf, toBeInstanceOf, toHaveProperty, toMatch

Epic: Spy and Mock

• Intend to support

✖️ Out of Scope (Currently):

• Generic JS-harness testing of any precompiled WASM binary
• Compiler & matcher integration with other compile-to-WASM languages (e.g. Rust and C++ with Emscripten)
  • I would LOVE to expand this project to cover additional cases, supporting pluggable compilers, ast parsing, and matchers for different WASM ecosystems and toolchains
  • Not in scope now because of time and effort
  • If you want to pay me to work on this, please get in touch!

Performance

Many efforts have been made to compile and run tests as quickly as possible. Some optimizations that have been most useful:

• Separate compile and test execution thread pools, worker thread entry points, and runners for quicker startup and thread respawn after test timeouts
• Compile threads tuned to take advantage of significant Node V8 engine warmup time savings on consecutive AssemblyScript compilations (this is an ongoing investigation as I want to see how it behaves when scaled up significantly)
• In-memory compiled files and source maps to eliminate intermediate disk I/O
• Enforced hard timeouts for long-running WASM tests via thread termination, with intelligent resume

As such, it is capable of compiling dozens of test files comprising hundreds of tests in a few seconds, and is likely faster on your machine than mine:

Prior Work

There are several core pieces of software without which this project would not be possible.

• This project makes direct use of the AssemblyScript language and its fantastic compiler. AS is a joy to work with when it comes to WASM because it's so familiar to everyday TypeScript usage.
• The key component that allows us to perform WASM instrumentation is Binaryen, a C++ toolchain infrastructure library for WebAssembly. We started by using the fantastic binaryen.js - a JS port also from the folks behind AssemblyScript, and eventually migrated to the native library for some advanced source-map regeneration features.
• Thanks to the Vitest team for creating the framework in the first place and making it extensible for different runtimes. Their internal pools were used as reference throughout development.
• Thanks to @cloudflare/vitest-pool-workers for providing the leading example of a 3rd party vitest custom pool out in the wild.
• Particular gratitude is also owed to assemblyscript-unittest-framework for inspiring our test discovery and instrumentation expression-walking approaches.

License

Licensed under the MIT

Portions of this software have been derived from third-party works which are licenced under different terms. These uses have been noted and are accompanied by their respective licenses in the project license and/or in applicable source code.