{"id":10517,"library":"assemblyscript-unittest-framework","title":"AssemblyScript Unit Test Framework","description":"assemblyscript-unittest-framework is a comprehensive testing solution for AssemblyScript and WebAssembly projects. It provides a robust suite of features including function mocking, code coverage statistics, and a rich expectation API. The current stable version is 2.1.0, with an active release cadence reflecting continuous development and feature additions, often multiple releases within a few months. This framework distinguishes itself by enabling developers to write tests directly in AssemblyScript and execute them within a Node.js environment, bridging the gap between host and WASM execution. Key differentiators include its dedicated support for the AssemblyScript ecosystem, offering deep integration for compiling and running WASM tests, and providing advanced capabilities like isolated test execution (configurable since v2.0.0) and detailed reporting.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/wasm-ecosystem/assemblyscript-unittest-framework","tags":["javascript","Assemblyscript","WASM","test"],"install":[{"cmd":"npm install assemblyscript-unittest-framework","lang":"bash","label":"npm"},{"cmd":"yarn add assemblyscript-unittest-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add assemblyscript-unittest-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for compiling AssemblyScript code into WebAssembly modules for testing.","package":"assemblyscript","optional":false},{"reason":"Peer dependency for advanced WebAssembly execution and interaction, supported since v2.1.0.","package":"warpo","optional":false}],"imports":[{"note":"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.","wrong":"const TestRunner = require('assemblyscript-unittest-framework').TestRunner;","symbol":"TestRunner","correct":"import { TestRunner } from 'assemblyscript-unittest-framework';"},{"note":"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.","wrong":"import ConsoleReporter from 'assemblyscript-unittest-framework/reporter';","symbol":"ConsoleReporter","correct":"import { ConsoleReporter } from 'assemblyscript-unittest-framework';"},{"note":"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.","wrong":"import { Configuration } from 'assemblyscript-unittest-framework';","symbol":"createConfig","correct":"import { createConfig } from 'assemblyscript-unittest-framework';"}],"quickstart":{"code":"/* package.json */\n{\n  \"name\": \"my-as-tests\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Example AssemblyScript tests\",\n  \"main\": \"./dist/run.js\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"test\": \"node --loader ts-node/esm run.ts\",\n    \"build:assembly\": \"asc assembly/index.spec.ts --target release --explicit-start --noEmit\",\n    \"build:runner\": \"tsc\"\n  },\n  \"devDependencies\": {\n    \"assemblyscript\": \">=0.25.1\",\n    \"warpo\": \">=2.2.0\",\n    \"assemblyscript-unittest-framework\": \"^2.1.0\",\n    \"ts-node\": \"^10.9.1\",\n    \"typescript\": \"^5.0.0\"\n  }\n}\n\n/* assembly/index.spec.ts */\nimport { test, describe, expect, beforeEach, afterEach } from \"assemblyscript-unittest\";\n\ndescribe(\"My math functions\", () => {\n  let sum: i32;\n\n  beforeEach(() => {\n    sum = 0;\n  });\n\n  afterEach(() => {\n    // Clean up if necessary\n  });\n\n  test(\"should add two numbers correctly\", () => {\n    sum = 1 + 2;\n    expect<i32>(sum).toBe(3, \"1 + 2 should be 3\");\n  });\n\n  test(\"should handle negative numbers\", () => {\n    sum = -1 + (-2);\n    expect<i32>(sum).toBe(-3, \"-1 + -2 should be -3\");\n  });\n});\n\n/* run.ts */\nimport { TestRunner, ConsoleReporter } from 'assemblyscript-unittest-framework';\nimport { resolve } from 'path';\n\nasync function main(): Promise<void> {\n  const runner = new TestRunner({\n    files: [resolve(__dirname, './assembly/**/*.spec.ts')],\n    rootDir: resolve(__dirname, './assembly'),\n    // Options for AssemblyScript compiler\n    asc: [\n      '--target', 'release',\n      '--explicitStart',\n      '--noEmitDts'\n    ],\n    // Control isolated execution (default changed to false in v2.0.0)\n    isolated: false,\n    // Optional: Pass environment variables to WASM instance\n    // env: { DEBUG: \"true\" }\n  });\n\n  runner.addReporter(new ConsoleReporter());\n\n  const success = await runner.run();\n  if (!success) {\n    process.exit(1);\n  }\n}\n\nmain().catch(err => {\n  console.error('Test Runner Error:', err);\n  process.exit(1);\n});\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"If you relied on isolated execution, explicitly set `isolated: true` in your `TestRunner` configuration: `new TestRunner({ isolated: true, ... });`","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove any calls to `endTest` from your AssemblyScript test files. The framework will manage test lifecycle automatically.","message":"The `endTest` API has been removed. Test completion is now handled implicitly by the framework.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The `--testcase` CLI argument was removed, indicating a shift in how specific test cases are targeted from the command line.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.3.1"},{"fix":"Ensure your AssemblyScript test files use `import { test, expect } from \"assemblyscript-unittest\";` for the core testing APIs.","message":"For writing tests in AssemblyScript, the `test`, `expect`, `describe`, etc., APIs are imported from `assemblyscript-unittest`, not `assemblyscript-unittest-framework`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install assemblyscript-unittest-framework` (or `yarn add`) and ensure `typescript` and `ts-node` are correctly configured if using TypeScript.","cause":"The `assemblyscript-unittest-framework` package is not installed or TypeScript cannot find its declaration files.","error":"Cannot find module 'assemblyscript-unittest-framework' or its corresponding type declarations."},{"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.","cause":"The `TestRunner` was initialized without valid `files` configuration, or the paths provided did not match any test files.","error":"Error: No test files found. Please provide files option in config."},{"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.","cause":"`addReporter` was called on an undefined `runner` object, often due to an error during `TestRunner` instantiation or incorrect import.","error":"TypeError: Cannot read properties of undefined (reading 'addReporter')"},{"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.","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.","error":"WebAssembly.instantiate(): Imports argument must be an object"}],"ecosystem":"npm"}