as-test 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Change Log
 
+## 2026-02-25 - v0.5.3
+
+### CLI, Modes & Matrix
+
+- feat: support mode fan-out behavior consistently across `ast build`, `ast run`, and `ast test`.
+- feat: when no `--mode` is provided and modes are configured, run using configured modes.
+- feat: add matrix-style per-file output with mode-aware timing:
+  - non-verbose: average time
+  - verbose: per-mode times.
+- feat: add real-time matrix line updates in the default reporter and normalize timing precision to one decimal.
+- feat: support comma-separated bare selectors (for example `ast test box,custom,generics,string`) across build/run/test selectors.
+
+### Config Merge & Env Behavior
+
+- fix: apply mode config as field-level merge over base config instead of replacing entire sections.
+- fix: merge `buildOptions.args` between base config and mode config.
+- fix: pass config env variables to both build and run processes for mode execution.
+
+### Build Pipeline & Feature Flags
+
+- feat: include the exact build command in build failure output.
+- feat: allow `buildOptions.cmd` to override default command generation while still appending user build args.
+- feat: support CLI feature toggles:
+  - `--enable coverage` / `--disable coverage`
+  - `--enable try-as` / `--disable try-as`.
+
+### Reporter & Summaries
+
+- fix: move mode summary rendering into the default reporter (via run-complete event payload).
+- feat: include `modeSummary` for single-mode runs.
+- feat: include mode and snapshot totals in final summary output.
+- fix: `--clean` output now behaves as non-TTY in default reporter:
+  - no in-place line editing,
+  - no suite expand/collapse logs,
+  - final per-file verdict lines only.
+
+### Coverage & Transform
+
+- fix: ignore AssemblyScript builtin/compiler helper calls during coverage instrumentation (including `isString`, `changetype<T>`, `idof<T>`, `sizeof<T>`).
+- fix: mock transform now collects mocked import targets across sources so WASI mock imports are rewritten reliably (resolves import-shape runtime failures).
+
+## 2026-02-24 - v0.5.2
+
+### Runtime & Serialization
+
+- refactor: remove `json-as` dependency by inlining portable serialization and deserialization helpers into the runtime.
+
+### CLI
+
+- fix: enforce deterministic alphanumeric test input ordering for `ast build`, `ast run`, and `ast test`.
+
+### Dependencies
+
+- chore: remove unused runtime dependencies `as-variant` and `gradient-string`.
+
+## 2026-02-23
+
+### Runtime Matrix & Mode Execution
+
+- feat: add `--mode <name[,name...]>` support for `ast build`, `ast run`, and `ast test`, including multi-mode fan-out in one command.
+- feat: add config `modes` map for per-mode overrides (`buildOptions`, `runOptions`, `env`, and optional output/log/coverage/snapshot directories).
+- feat: when running with `--mode`, compile artifacts are emitted as `<name>.<mode>.<type>.wasm` (where `type` is `wasi` or `bindings`).
+
+### Bindings Runner Naming
+
+- feat: switch default bindings runner path to `./.as-test/runners/default.bindings.js`.
+- fix: keep backward compatibility with deprecated `./.as-test/runners/default.run.js` and legacy `*.run.js` bindings helper files.
+- feat: add runtime warnings for deprecated bindings runner path usage and automatic fallback to `default.bindings.js` when needed.
+
+### Init, Examples & Docs
+
+- feat: `init` now writes both `.as-test/runners/default.wasi.js` and `.as-test/runners/default.bindings.js`.
+- docs: update README runtime examples and mode artifact naming guidance for `--mode`.
+- docs: refresh `examples/` docs/configs for `default.bindings.js` and add a mode matrix example config.
+
+## 2026-02-18
+
+### Reporter & CLI
+
+- feat: add built-in TAP v13 reporter (`tap`) for `ast run` and `ast test`.
+- feat: add reporter selection flags `--tap` and `--reporter <name|path>`.
+- feat: when TAP reporter is active, write a single TAP artifact by default to `./.as-test/reports/report.tap`.
+- feat: allow reporter object config (`name`, `options`, `outDir`, `outFile`) for TAP output control, including `single-file` (default) and `per-file`.
+- feat: emit GitHub Actions `::error` annotations for failed TAP assertions (with file/line/col when available).
+- fix: keep TAP stdout clean by routing runtime passthrough output to stderr in TAP mode.
+- fix: ensure reporter flag values are not treated as test selectors in `ast test`.
+
+### Mocking API & Transform
+
+- feat: add `unmockFn(oldFn)` and `unmockImport(path)` APIs to complement `mockFn` and `mockImport`.
+- feat: add `snapshotImport(imp, version)` and `restoreImport(imp, version)` to snapshot and restore a single import mock by version.
+- feat: support both import path strings and import functions for `imp`, and `string`/`i32` versions.
+- feat: `snapshotImport` also supports callback form (`snapshotImport(imp, () => ...)`) that snapshots to default version `"default"`.
+- feat: update transform/runtime handling so `unmockFn` stops later function-call rewrites and `unmockImport` clears the active import mock mapping.
+
+### Config & Docs
+
+- docs: document built-in TAP usage in README (`--tap`, `--reporter tap`, and config-based usage).
+- docs: update config schema reporter description to include built-in `default` and `tap` values.
+- docs: add README mocking section covering `mockFn`, `unmockFn`, `mockImport`, and `unmockImport`.
+
 ## 2026-02-16 - v0.5.1
 
 ### Miscellaneous

package/README.md

@@ -5,8 +5,11 @@
 <details>
 <summary>Table of Contents</summary>
 
+- [Why as-test](#why-as-test)
 - [Installation](#installation)
+- [Examples](#examples)
 - [Writing Tests](#writing-tests)
+- [Mocking](#mocking)
 - [Snapshots](#snapshots)
 - [Coverage](#coverage)
 - [Custom Reporters](#custom-reporters)
@@ -16,6 +19,20 @@
 
 </details>
 
+## Why as-test
+
+Most AssemblyScript testing tools are tied to a single runtime, usually Node.js. This works for development, but it doesn’t reflect how your code runs in production.
+If you deploy to WASI, Wazero, or a custom runtime, you often end up mocking everything and maintaining parallel logic just for tests.
+as-test solves this by letting you run tests on your actual target runtime, while only mocking what’s necessary.
+
+Key benefits
+
+- Runtime-agnostic: test on WASI, bindings, or custom runners
+- Minimal mocking: keep real imports when possible
+- Production-like testing: catch runtime-specific issues early
+- Inline mocking and snapshots
+- Custom reporters and coverage
+
 ## Installation
 
 The installation script will set everything up for you:
@@ -28,6 +45,17 @@ Alternatively, you can install it manually:
 npm install as-test --save-dev
 ```
 
+## Examples
+
+Full runnable examples live in `examples/`, including:
+
+- complete spec files for core features
+- import mocking and import snapshot patterns
+- mode-based runtime matrix config in `examples/as-test.config.json`
+- a dedicated config you can run directly
+
+See `examples/README.md` for the walkthrough.
+
 ## Writing Tests
 
 Create `assembly/__tests__/math.spec.ts`:
@@ -46,7 +74,7 @@ describe("math", () => {
 });
 ```
 
-### Test file selection (`ast test`)
+### File selection (`ast run`, `ast build`, `ast test`)
 
 No selectors:
 
@@ -77,6 +105,14 @@ Multiple selectors:
 ast test sleep array ./assembly/__tests__/snapshot.spec.ts
 ```
 
+Comma-separated bare suite names:
+
+```bash
+ast test box,custom,generics,string
+ast run box,custom,generics,string
+ast build box,custom,generics,string
+```
+
 If nothing matches, `ast test` exits non-zero with:
 
 ```text
@@ -86,10 +122,76 @@ No test files matched: ...
 ### Useful flags
 
 - `--config <path>`: use another config file
+- `--mode <name[,name...]>`: run one or multiple named config modes (if omitted and `modes` is configured, as-test runs all configured modes)
 - `--update-snapshots`: write snapshot updates
 - `--no-snapshot`: disable snapshot assertions for the run
 - `--show-coverage`: print uncovered coverage points
+- `--enable <feature>`: enable as-test feature (`coverage`, `try-as`)
+- `--disable <feature>`: disable as-test feature (`coverage`, `try-as`)
 - `--verbose`: keep expanded suite/test lines and update running `....` statuses in place
+- `--clean`: disable in-place TTY updates and print only final per-file verdict lines. Useful for CI/CD.
+
+Example:
+
+```bash
+ast build --enable try-as
+ast test --disable coverage
+```
+
+## Mocking
+
+Use these helpers when you need to replace behavior during tests:
+
+- `mockFn(oldFn, newFn)`: rewrites subsequent calls to `oldFn` in the same spec file to use `newFn`
+- `unmockFn(oldFn)`: stops that rewrite for subsequent calls
+- `mockImport("module.field", fn)`: sets the runtime mock for an external import
+- `unmockImport("module.field")`: clears the runtime mock for an external import
+- `snapshotImport<T = Function | string>(imp: T, version: string | i32)`: snapshots a single import mock
+- `snapshotImport<T = Function | string>(imp: T, capture: () => unknown)`: runs `capture` and snapshots using version `"default"`
+- `restoreImport<T = Function | string>(imp: T, version: string | i32)`: restores a single import mock
+
+Example:
+
+```ts
+import {
+  expect,
+  it,
+  mockFn,
+  mockImport,
+  restoreImport,
+  run,
+  snapshotImport,
+  unmockFn,
+  unmockImport,
+} from "as-test";
+import { foo } from "./mock";
+
+mockImport("mock.foo", (): string => "buz");
+mockFn(foo, (): string => "baz " + foo());
+
+it("mocked function", () => {
+  expect(foo()).toBe("baz buz");
+});
+
+unmockFn(foo);
+
+it("function restored", () => {
+  expect(foo()).toBe("buz");
+});
+
+snapshotImport(foo, 1);
+mockImport("mock.foo", (): string => "temp");
+snapshotImport("mock.foo", "v2");
+restoreImport(foo, 1);
+
+snapshotImport("mock.foo", () => foo()); // snapshots to version "default"
+restoreImport("mock.foo", "default");
+
+unmockImport("mock.foo");
+mockImport("mock.foo", (): string => "buz");
+
+run();
+```
 
 ## Snapshots
 
@@ -152,10 +254,13 @@ Example:
   "snapshotDir": "./.as-test/snapshots",
   "config": "none",
   "coverage": true,
+  "env": {},
   "buildOptions": {
+    "cmd": "",
     "args": [],
     "target": "wasi"
   },
+  "modes": {},
   "runOptions": {
     "runtime": {
       "cmd": "node ./.as-test/runners/default.wasi.js <file>"
@@ -172,11 +277,162 @@ Key fields:
 - `logs`: log output dir or `"none"`
 - `coverageDir`: coverage output dir or `"none"`
 - `snapshotDir`: snapshot storage dir
+- `env`: environment variables injected into build and runtime processes
+- `buildOptions.cmd`: optional custom build command template; when set it replaces default build command and flags. Supports `<file>`, `<name>`, `<outFile>`, `<target>`, `<mode>`
 - `buildOptions.target`: `wasi` or `bindings`
+- `modes`: named overrides for command/target/args/runtime/env/artifact directories (selected via `--mode`); `mode.env` overrides top-level `env`
 - `runOptions.runtime.cmd`: runtime command, supports `<file>` and `<name>`; if its script path is missing, as-test falls back to the default runner for the selected target
-- `runOptions.reporter`: optional custom reporter module path
+- `runOptions.reporter`: reporter selection as a string or object
+
+Example multi-runtime matrix:
+
+```json
+{
+  "modes": {
+    "wasi-simd": {
+      "buildOptions": {
+        "target": "wasi",
+        "args": ["--enable", "simd"]
+      },
+      "runOptions": {
+        "runtime": {
+          "cmd": "wasmer run <file>"
+        }
+      }
+    },
+    "wasi-nosimd": {
+      "buildOptions": {
+        "target": "wasi"
+      },
+      "runOptions": {
+        "runtime": {
+          "cmd": "wasmer run <file>"
+        }
+      }
+    },
+    "bindings-node-simd": {
+      "buildOptions": {
+        "target": "bindings",
+        "args": ["--enable", "simd"]
+      },
+      "runOptions": {
+        "runtime": {
+          "cmd": "node ./.as-test/runners/default.bindings.js <file>"
+        }
+      }
+    }
+  }
+}
+```
+
+Run all modes:
+
+```bash
+ast test --mode wasi-simd,wasi-nosimd,bindings-node-simd
+```
+
+Summary totals:
+
+- `Modes` in the default reporter is config-scoped (`total` is all configured modes)
+- when selecting fewer modes with `--mode`, unselected modes are counted as `skipped`
+- `Files` in the default reporter is also config-scoped (`total` is all files from configured input patterns)
+- when selecting fewer files, unselected files are counted as `skipped`
+
+When using `--mode`, compiled artifacts are emitted as:
+
+```text
+<test-name>.<mode>.<target>.wasm
+```
+
+Example:
+
+```text
+math.wasi-simd.wasi.wasm
+math.bindings-node-simd.bindings.wasm
+```
+
+Bindings runner naming:
+
+- preferred: `./.as-test/runners/default.bindings.js`
+- deprecated but supported: `./.as-test/runners/default.run.js`
+
+`ast init` now scaffolds both local runners:
+
+- `.as-test/runners/default.wasi.js`
+- `.as-test/runners/default.bindings.js`
+
+## Custom Reporters
+
+Built-in TAP reporter (useful for CI, including GitHub Actions):
+
+```bash
+ast run --reporter tap
+```
 
-## Custom Reporter
+TAP output is written to `./.as-test/reports/report.tap` by default.
+
+Or in config:
+
+```json
+{
+  "runOptions": {
+    "reporter": "tap"
+  }
+}
+```
+
+Or with reporter object config:
+
+```json
+{
+  "runOptions": {
+    "reporter": {
+      "name": "tap",
+      "options": ["single-file"],
+      "outDir": "./.as-test/reports"
+    }
+  }
+}
+```
+
+`options` supports `single-file` (default) and `per-file`.
+
+Single-file explicit path:
+
+```json
+{
+  "runOptions": {
+    "reporter": {
+      "name": "tap",
+      "outFile": "./.as-test/reports/report.tap"
+    }
+  }
+}
+```
+
+In GitHub Actions, failed TAP points emit `::error` annotations with file and line when available.
+
+Example GitHub workflow (Bun + Wasmtime + TAP summary):
+
+```yaml
+name: Run Tests
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jcbhmr/setup-wasmtime@v2
+      - uses: oven-sh/setup-bun@v1
+      - run: bun install
+      - run: bun run test --update-snapshots --tap
+      - uses: test-summary/action@v2
+        if: always()
+        with:
+          paths: ".as-test/reports/*.tap"
+```
 
 Set reporter path in config:
 
@@ -188,6 +444,13 @@ Set reporter path in config:
 }
 ```
 
+It's even possible to use something like [tap-summary](https://github.com/zoubin/tap-summary) to summarize the test results!
+
+```bash
+npm install -g tap-summary
+ast test --reporter tap | tap-summary
+```
+
 Reporter module should export `createReporter` (named or default):
 
 ```js
@@ -205,6 +468,8 @@ export function createReporter(context) {
 }
 ```
 
+With these hooks, you can emit machine-readable output (for example TAP/JSON) while still keeping the default human-readable terminal view for local runs.
+
 ## Assertions
 
 Skip helpers:

package/as-test.config.schema.json

@@ -80,10 +80,23 @@
       ],
       "default": true
     },
+    "env": {
+      "type": "object",
+      "description": "Environment variables injected when building/running.",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "default": {}
+    },
     "buildOptions": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "cmd": {
+          "type": "string",
+          "description": "Custom build command template. When set, this replaces the default asc command/flags/output handling. Supports placeholders: <file>, <name>, <outFile>, <target>, <mode>.",
+          "default": ""
+        },
         "args": {
           "type": "array",
           "items": {
@@ -98,10 +111,135 @@
         }
       },
       "default": {
+        "cmd": "",
         "args": [],
         "target": "wasi"
       }
     },
+    "modes": {
+      "type": "object",
+      "description": "Named build/run modes. Each mode can override target/args/runtime/env and artifact directories.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "outDir": {
+            "type": "string",
+            "description": "Mode-specific build output directory. If omitted, defaults to <outDir>/<mode-name>."
+          },
+          "logs": {
+            "type": "string",
+            "description": "Mode-specific log output directory."
+          },
+          "coverageDir": {
+            "type": "string",
+            "description": "Mode-specific coverage output directory."
+          },
+          "snapshotDir": {
+            "type": "string",
+            "description": "Mode-specific snapshot directory."
+          },
+          "config": {
+            "type": "string",
+            "description": "Mode-specific asconfig path or \"none\"."
+          },
+          "coverage": {
+            "description": "Mode-specific coverage settings.",
+            "oneOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {
+                  "enabled": {
+                    "type": "boolean"
+                  },
+                  "includeSpecs": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            ]
+          },
+          "buildOptions": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "cmd": {
+                "type": "string",
+                "description": "Mode-specific custom build command template."
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "target": {
+                "type": "string",
+                "enum": ["wasi", "bindings"]
+              }
+            }
+          },
+          "runOptions": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "runtime": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "cmd": {
+                    "type": "string",
+                    "description": "Mode-specific runtime command."
+                  }
+                }
+              },
+              "reporter": {
+                "description": "Mode-specific reporter config.",
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "name": {
+                        "type": "string"
+                      },
+                      "options": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "outDir": {
+                        "type": "string"
+                      },
+                      "outFile": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["name"]
+                  }
+                ]
+              }
+            }
+          },
+          "env": {
+            "type": "object",
+            "description": "Environment variables injected when building/running this mode.",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "default": {}
+    },
     "runOptions": {
       "type": "object",
       "additionalProperties": false,
@@ -121,8 +259,39 @@
           }
         },
         "reporter": {
-          "type": "string",
-          "description": "Optional path to a custom reporter module.",
+          "description": "Reporter selection. Use a string for built-in/default/custom path, or an object for named reporter configuration.",
+          "oneOf": [
+            {
+              "type": "string",
+              "description": "\"\" or \"default\" uses built-in default reporter, \"tap\" uses built-in TAP v13 reporter, otherwise treated as custom module path."
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "Reporter name or module path. Built-in values: \"default\", \"tap\"."
+                },
+                "options": {
+                  "type": "array",
+                  "description": "Reporter options. TAP supports \"single-file\" (default) and \"per-file\".",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "outDir": {
+                  "type": "string",
+                  "description": "TAP output directory. Defaults to \"./.as-test/reports\"."
+                },
+                "outFile": {
+                  "type": "string",
+                  "description": "TAP output file path for single-file mode. Defaults to \"./.as-test/reports/report.tap\"."
+                }
+              },
+              "required": ["name"]
+            }
+          ],
           "default": ""
         }
       },

package/assembly/coverage.ts

@@ -23,6 +23,26 @@ export function __REGISTER(point: CoverPoint): void {
   Coverage.SN.hashes.set(point.hash, point);
 }
 
+export function __REGISTER_RAW(
+  file: string,
+  hash: string,
+  line: i32,
+  column: i32,
+  type: string,
+): void {
+  if (Coverage.SN.allIndex.has(hash)) return;
+  const point = new CoverPoint();
+  point.file = file;
+  point.hash = hash;
+  point.line = line;
+  point.column = column;
+  point.type = type;
+  Coverage.SN.points++;
+  Coverage.SN.allIndex.set(hash, Coverage.SN.all.length);
+  Coverage.SN.all.push(point);
+  Coverage.SN.hashes.set(hash, point);
+}
+
 export function __COVER(hash: string): void {
   if (Coverage.SN.allIndex.has(hash)) {
     const index = Coverage.SN.allIndex.get(hash);