AssemblyScript Unit Test Framework

Common errors

• Cannot find module 'assemblyscript-unittest-framework' or its corresponding type declarations.

  cause The `assemblyscript-unittest-framework` package is not installed or TypeScript cannot find its declaration files.
  fix Run `npm install assemblyscript-unittest-framework` (or `yarn add`) and ensure `typescript` and `ts-node` are correctly configured if using TypeScript.

• Error: No test files found. Please provide files option in config.

  cause The `TestRunner` was initialized without valid `files` configuration, or the paths provided did not match any test files.
  fix Verify that the `files` array in your `TestRunner` configuration correctly points to your AssemblyScript test files (e.g., `files: ['./assembly/**/*.spec.ts']`) and that the paths are resolveable from your runner script's context.

• TypeError: Cannot read properties of undefined (reading 'addReporter')

  cause `addReporter` was called on an undefined `runner` object, often due to an error during `TestRunner` instantiation or incorrect import.
  fix Ensure `TestRunner` is correctly imported as a named export (`import { TestRunner } from 'assemblyscript-unittest-framework';`) and that `new TestRunner(...)` is called with valid arguments before attempting to call its methods.

• WebAssembly.instantiate(): Imports argument must be an object

  cause This error typically occurs if the AssemblyScript compiler (used by the framework) or the test runtime expects specific imports for the WASM module that are not being provided or are malformed.
  fix Check your AssemblyScript `asc` compiler options within `TestRunner` config. Ensure `warpo` is correctly installed as a peer dependency. Also, verify that your AssemblyScript code has all necessary `import` statements if relying on external WASM functions.

Warnings

• breaking The default value of the `isolated` configuration option switched from `true` to `false`. This means tests will run in a shared WASM instance by default, potentially affecting state between tests if not properly managed.
  Fix: If you relied on isolated execution, explicitly set `isolated: true` in your `TestRunner` configuration: `new TestRunner({ isolated: true, ... });`
• breaking The `endTest` API has been removed. Test completion is now handled implicitly by the framework.
  Fix: Remove any calls to `endTest` from your AssemblyScript test files. The framework will manage test lifecycle automatically.
• breaking The `--testcase` CLI argument was removed, indicating a shift in how specific test cases are targeted from the command line.
  Fix: Review the current CLI options or programmatic `TestRunner` configuration for targeting specific tests, typically through file patterns or test filtering options in the configuration object.
• gotcha Version 1.3.1 included an urgent update for the `chalk` dependency to `5.6.2` due to a malicious version (`chalk@5.6.1`) being published. While this was a dependency issue, it highlights the importance of keeping dependencies up to date.
  Fix: Always ensure your `node_modules` are clean and install fresh dependencies. If you were on affected versions, run `npm audit fix` or manually update `chalk` (if it appears as a direct dependency) and `assemblyscript-unittest-framework` to the latest version.
• gotcha For writing tests in AssemblyScript, the `test`, `expect`, `describe`, etc., APIs are imported from `assemblyscript-unittest`, not `assemblyscript-unittest-framework`.
  Fix: Ensure your AssemblyScript test files use `import { test, expect } from "assemblyscript-unittest";` for the core testing APIs.

Install

• npm install assemblyscript-unittest-framework npm
• yarn add assemblyscript-unittest-framework yarn
• pnpm add assemblyscript-unittest-framework pnpm

Imports

• TestRunner
  wrong:

  const TestRunner = require('assemblyscript-unittest-framework').TestRunner;

  correct:

  import { TestRunner } from 'assemblyscript-unittest-framework';

  Use named import for the `TestRunner` class, which is the primary interface for configuring and running tests. CommonJS `require` is not the recommended or idiomatic way for modern Node.js usage with this library.
• ConsoleReporter
  wrong:

  import ConsoleReporter from 'assemblyscript-unittest-framework/reporter';

  correct:

  import { ConsoleReporter } from 'assemblyscript-unittest-framework';

  The `ConsoleReporter` class is a named export from the main package, used to output test results to the console. Do not attempt to import it from a subpath or as a default export.
• createConfig
  wrong:

  import { Configuration } from 'assemblyscript-unittest-framework';

  correct:

  import { createConfig } from 'assemblyscript-unittest-framework';

  While configuration objects are passed to `TestRunner`, specific utility functions like `createConfig` may be available for building robust configurations. Direct interface imports (e.g., `Configuration`) are less common for direct usage than helper functions.

Quickstart

This quickstart demonstrates how to set up and run AssemblyScript unit tests using the framework. It includes a `package.json` for dependencies and scripts, a sample AssemblyScript test file (`index.spec.ts`) using the `assemblyscript-unittest` APIs, and a TypeScript runner script (`run.ts`) that initializes and executes the `TestRunner` with `ConsoleReporter`.

/* package.json */
{
  "name": "my-as-tests",
  "version": "1.0.0",
  "description": "Example AssemblyScript tests",
  "main": "./dist/run.js",
  "type": "module",
  "scripts": {
    "test": "node --loader ts-node/esm run.ts",
    "build:assembly": "asc assembly/index.spec.ts --target release --explicit-start --noEmit",
    "build:runner": "tsc"
  },
  "devDependencies": {
    "assemblyscript": ">=0.25.1",
    "warpo": ">=2.2.0",
    "assemblyscript-unittest-framework": "^2.1.0",
    "ts-node": "^10.9.1",
    "typescript": "^5.0.0"
  }
}

/* assembly/index.spec.ts */
import { test, describe, expect, beforeEach, afterEach } from "assemblyscript-unittest";

describe("My math functions", () => {
  let sum: i32;

  beforeEach(() => {
    sum = 0;
  });

  afterEach(() => {
    // Clean up if necessary
  });

  test("should add two numbers correctly", () => {
    sum = 1 + 2;
    expect<i32>(sum).toBe(3, "1 + 2 should be 3");
  });

  test("should handle negative numbers", () => {
    sum = -1 + (-2);
    expect<i32>(sum).toBe(-3, "-1 + -2 should be -3");
  });
});

/* run.ts */
import { TestRunner, ConsoleReporter } from 'assemblyscript-unittest-framework';
import { resolve } from 'path';

async function main(): Promise<void> {
  const runner = new TestRunner({
    files: [resolve(__dirname, './assembly/**/*.spec.ts')],
    rootDir: resolve(__dirname, './assembly'),
    // Options for AssemblyScript compiler
    asc: [
      '--target', 'release',
      '--explicitStart',
      '--noEmitDts'
    ],
    // Control isolated execution (default changed to false in v2.0.0)
    isolated: false,
    // Optional: Pass environment variables to WASM instance
    // env: { DEBUG: "true" }
  });

  runner.addReporter(new ConsoleReporter());

  const success = await runner.run();
  if (!success) {
    process.exit(1);
  }
}

main().catch(err => {
  console.error('Test Runner Error:', err);
  process.exit(1);
});