as-test 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Change Log
 
+## 2026-02-16 - v0.5.0
+
+### CLI & Runtime
+
+- feat: `ast test` supports selectors by name, path, or glob and resolves bare names against configured spec directories.
+- feat: `ast test` now runs per-file sequentially (`build #1 -> run #1 -> ...`) and prints one aggregated final summary.
+- fix: `ast test` exits non-zero when no `.spec.ts` files match selectors/config input.
+- fix: `ast build` is silent on success and only prints concise stderr details on failure.
+- feat: add `--verbose` mode for expanded live suite/test status output without collapsing nodes.
+- fix: suppress noisy Node WASI experimental warning lines during test execution.
+- refactor: runtime config is `runOptions.runtime.cmd` (legacy `runtime.run` and `runOptions.run` remain supported).
+- fix: if the configured runtime script path is missing, automatically fall back to the target default runner.
+
+### Reporter & API
+
+- feat: add skip helpers `xdescribe`, `xtest`, `xit`, and `xexpect`.
+- feat: include skipped counts for files, suites, and tests in final summaries.
+- feat: add string boundary matchers `toStartWith()` and `toEndWith()`.
+- feat: add `toBeTruthy()`, `toBeFalsy()`, `toBeCloseTo()`, `toMatch()`, optional message support in `expect(value, message)`, and snapshot matcher `toMatchSnapshot(name?)`.
+- fix: improve assertion correctness across `.not`, type matcher labels, hook execution frequency, non-primitive `toBe()` handling, and failure source locations.
+
+### Coverage
+
+- feat: add `--show-coverage` and support object-style coverage config (`{ enabled, includeSpecs }`).
+- fix: limit coverage to source files (`.ts`/`.as`), excluding `node_modules` and AssemblyScript stdlib paths.
+- fix: skip writing coverage artifacts when no valid source files remain after filtering.
+- fix: dedupe identical coverage points across sequential runs and stabilize point/file ordering in reports.
+
+### Init, Config & Docs
+
+- feat: `init` supports positional install directory (`as-test init ./path`) in addition to `--dir`.
+- feat: `init` supports example modes (`minimal`, `full`, `none`) and scaffolds target-specific local runners.
+- feat: WASI init adds `@assemblyscript/wasi-shim`; bindings init scaffolds `.as-test/runners/default.run.js`.
+- refactor: default WASI runtime path is `./.as-test/runners/default.wasi.js`; generated runners are ESM-only.
+- docs: refresh README and schema docs for current CLI behavior, config fields, runtime fallback, coverage, and reporter usage.
+
+### Tooling
+
+- chore: add release validation workflow via `release:check` and tighten package publish file selection.
+
 ## 2025-05-28 - v0.4.4
 
 - deps: update json-as to `v1.1.13`

package/README.md

@@ -1,138 +1,252 @@
-<h5 align="center">
-  <pre>
-<span style="font-size: 0.8em;"> █████  ███████       ████████ ███████ ███████ ████████ 
-██   ██ ██               ██    ██      ██         ██    
-███████ ███████ █████    ██    █████   ███████    ██    
-██   ██      ██          ██    ██           ██    ██    
-██   ██ ███████          ██    ███████ ███████    ██    
-                                                        </span>
-    AssemblyScript - v0.4.3
-</pre>
-</h5>
+<h1 align="center"><pre>╔═╗ ╔═╗    ╔═╗ ╔═╗ ╔═╗ ╔═╗
+╠═╣ ╚═╗ ══  ║  ╠═  ╚═╗  ║ 
+╩ ╩ ╚═╝     ╩  ╚═╝ ╚═╝  ╩ </pre></h1>
 
-A lightweight testing framework for AssemblyScript.
+<details>
+<summary>Table of Contents</summary>
 
-🔹 Minimal and fast – Run your tests without unnecessary overhead.
+- [Installation](#installation)
+- [Writing Tests](#writing-tests)
+- [Snapshots](#snapshots)
+- [Coverage](#coverage)
+- [Custom Reporters](#custom-reporters)
+- [Assertions](#assertions)
+- [License](#license)
+- [Contact](#contact)
 
-🔹 Familiar API – Inspired by modern JavaScript testing frameworks.
+</details>
 
-🔹 Powerful mocking – Easily override functions and track calls.
-
-🔹 Seamless CI/CD integration – Works effortlessly in automation pipelines.
-
-🔹 Universal environment – Run your tests on any platform, runtime, or bindings.
-
-## 💾 Installation
+## Installation
 
+The installation script will set everything up for you:
 ```bash
-npm install as-test
-npm intall json-as
+npx as-test init --dir ./path-to-install
 ```
 
-Initialize your test setup with:
-
+Alternatively, you can install it manually:
 ```bash
-as-test init
+npm install as-test --save-dev
 ```
 
-This creates a test directory at `assembly/__tests__/` with a sample test file.
-
-## 📝 Writing Tests
+## Writing Tests
 
-Create a new test file in `assembly/__tests__/`, for example, `math.spec.ts`:
+Create `assembly/__tests__/math.spec.ts`:
 
-```js
+```ts
 import { describe, test, expect, run } from "as-test";
 
-describe("Math operations", () => {
-  test("Addition", () => {
+describe("math", () => {
+  test("addition", () => {
     expect(1 + 2).toBe(3);
   });
 
-  test("Subtraction", () => {
-    expect(5 - 2).toBe(3);
-  });
-
-  test("Multiplication", () => {
-    expect(3 * 3).toBe(9);
+  test("close to", () => {
+    expect(3.14159).toBeCloseTo(3.14, 2);
   });
 });
-
-run();
 ```
 
-## 🔍 Examples
+### Test file selection (`ast test`)
 
-### 🏗️ Mocking Functions
+No selectors:
 
-Use `mockFn` to override functions during testing:
+```bash
+ast test
+```
 
-```js
-import { mockFn } from "as-test";
+Uses configured input patterns from `as-test.config.json`.
 
-// Mock console.log
-mockFn<void>("console.log", (data: string): void => {
-    console.log("[MOCKED]: " + data);
-});
+By name:
 
-run();
+```bash
+ast test sleep
 ```
 
-Or override imported functions with `mockImport`.
+Resolves to `<configured-input-dir>/sleep.spec.ts`.
 
-### ⚒️ Setup and Teardown
+By explicit path or glob:
 
-Use `beforeAll` and `afterAll` to run code before and after a test is run.
+```bash
+ast test ./assembly/__tests__/sleep.spec.ts
+ast test ./assembly/__tests__/*.spec.ts
+```
 
-```js
-import { beforeAll, afterAll } from "as-test";
+Multiple selectors:
 
-beforeAll(() => {
-  log("Setting up test environment...");
-});
+```bash
+ast test sleep array ./assembly/__tests__/snapshot.spec.ts
+```
 
-afterAll(() => {
-  log("Tearing down test environment...");
-});
+If nothing matches, `ast test` exits non-zero with:
 
-run();
+```text
+No test files matched: ...
 ```
 
-### 📃 Pretty Logging
+### Useful flags
 
-Using `console.log` will mess up the terminal output. Instead, use the inbuilt `log` function:
+- `--config <path>`: use another config file
+- `--update-snapshots`: write snapshot updates
+- `--no-snapshot`: disable snapshot assertions for the run
+- `--show-coverage`: print uncovered coverage points
+- `--verbose`: keep expanded suite/test lines and update running `....` statuses in place
 
-```js
-import { log } from "as-test";
+## Snapshots
+
+Snapshot assertions are enabled by default.
+
+- Read-only mode (default): missing/mismatched snapshots fail
+- Update mode: `--update-snapshots` writes missing/mismatched snapshots
 
-log("This is a pretty log function");
+Commands:
 
-run();
+```bash
+ast test --update-snapshots
+ast run --update-snapshots
+ast test --no-snapshot
 ```
 
-Or override all existing `console.log` calls with `log`:
+Snapshot files are stored in `snapshotDir` (default `./.as-test/snapshots`).
 
-```js
-import { mockFn, log } from "as-test";
+## Coverage
 
-mockFn<void>("console.log", (data: string): void => {
-    log(data);
-});
+Coverage is controlled by `coverage` in config.
+Coverage reporting includes source files ending in `.ts` or `.as` only.
+
+- Boolean form:
+  - `true` / `false`
+- Object form:
+  - `{ "enabled": true, "includeSpecs": false }`
+
+Default behavior includes non-spec files and excludes `*.spec.ts` files.
 
-run();
+Show point-level misses:
+
+```bash
+ast test --show-coverage
 ```
 
-### 🔄 Running Tests in CI
+Coverage artifacts:
+
+- `ast run` writes `coverage.log.json` to `coverageDir` (if enabled and not `"none"`)
+- `ast test` writes per-file coverage artifacts (`coverage.<file>.log.json`)
+
+Log artifacts:
+
+- `ast run` writes `test.log.json` to `logs` (if `logs` is not `"none"`)
+- `ast test` writes per-file logs (`test.<file>.log.json`)
+
+## Configuration
+
+Default file: `as-test.config.json`
+
+Example:
+
+```json
+{
+  "$schema": "./as-test.config.schema.json",
+  "input": ["./assembly/__tests__/*.spec.ts"],
+  "outDir": "./.as-test/build",
+  "logs": "./.as-test/logs",
+  "coverageDir": "./.as-test/coverage",
+  "snapshotDir": "./.as-test/snapshots",
+  "config": "none",
+  "coverage": true,
+  "buildOptions": {
+    "args": [],
+    "target": "wasi"
+  },
+  "runOptions": {
+    "runtime": {
+      "cmd": "node ./.as-test/runners/default.wasi.js <file>"
+    },
+    "reporter": ""
+  }
+}
+```
 
-To integrate `as-test` into your CI/CD workflow, see the [example configuration](https://github.com/JairusSW/as-test/blob/main/.github/workflows/as-test.yml).
+Key fields:
 
-`assembly/__tests__/example.spec.ts`
+- `input`: glob list of spec files
+- `outDir`: compiled wasm output dir
+- `logs`: log output dir or `"none"`
+- `coverageDir`: coverage output dir or `"none"`
+- `snapshotDir`: snapshot storage dir
+- `buildOptions.target`: `wasi` or `bindings`
+- `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
 
-## 📃 License
+## Custom Reporter
 
-This project is distributed under an open source license. You can view the full license using the following link: [License](./LICENSE)
+Set reporter path in config:
+
+```json
+{
+  "runOptions": {
+    "reporter": "./tests/my-reporter.js"
+  }
+}
+```
+
+Reporter module should export `createReporter` (named or default):
+
+```js
+export function createReporter(context) {
+  return {
+    onRunStart(event) {},
+    onFileStart(event) {},
+    onFileEnd(event) {},
+    onSuiteStart(event) {},
+    onSuiteEnd(event) {},
+    onAssertionFail(event) {},
+    onSnapshotMissing(event) {},
+    onRunComplete(event) {},
+  };
+}
+```
 
-## 📫 Contact
+## Assertions
+
+Skip helpers:
+
+- `xdescribe(name, fn)`
+- `xtest(name, fn)`
+- `xit(name, fn)`
+- `xexpect(value)`
+
+Available matchers:
+
+- `toBe(expected)`
+- `toBeNull()`
+- `toBeGreaterThan(value)`
+- `toBeGreaterOrEqualTo(value)`
+- `toBeLessThan(value)`
+- `toBeLessThanOrEqualTo(value)`
+- `toBeString()`
+- `toBeBoolean()`
+- `toBeArray()`
+- `toBeNumber()`
+- `toBeInteger()`
+- `toBeFloat()`
+- `toBeFinite()`
+- `toBeTruthy()`
+- `toBeFalsy()`
+- `toBeCloseTo(expected, precision = 2)`
+- `toMatch(substring)`
+- `toStartWith(prefix)`
+- `toEndWith(suffix)`
+- `toHaveLength(length)`
+- `toContain(item)`
+- `toThrow()` (with `try-as`)
+- `toMatchSnapshot(name?)`
+
+## License
+
+This project is distributed under an open source license. Work on this project is done by passion, but if you want to support it financially, you can do so by making a donation to the project's [GitHub Sponsors](https://github.com/sponsors/JairusSW) page.
+
+You can view the full license using the following link: [License](./LICENSE)
+
+## Contact
 
 Please send all issues to [GitHub Issues](https://github.com/JairusSW/as-test/issues) and to converse, please send me an email at [me@jairus.dev](mailto:me@jairus.dev)
 

package/as-test.config.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/JairusSW/as-test/blob/main/as-test.config.schema.json",
+  "title": "as-test configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor validation/autocomplete."
+    },
+    "input": {
+      "type": "array",
+      "description": "Glob patterns for test specification files.",
+      "items": {
+        "type": "string"
+      },
+      "default": ["./assembly/__tests__/*.spec.ts"]
+    },
+    "outDir": {
+      "type": "string",
+      "description": "Directory where compiled artifacts are written.",
+      "default": "./.as-test/build"
+    },
+    "logs": {
+      "description": "Directory for log artifacts, or \"none\" to disable.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "const": "none"
+        }
+      ],
+      "default": "./.as-test/logs"
+    },
+    "coverageDir": {
+      "description": "Directory for coverage artifacts, or \"none\" to disable writing coverage files.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "const": "none"
+        }
+      ],
+      "default": "./.as-test/coverage"
+    },
+    "snapshotDir": {
+      "type": "string",
+      "description": "Directory for snapshot files written by snapshot assertions.",
+      "default": "./.as-test/snapshots"
+    },
+    "config": {
+      "type": "string",
+      "description": "Reserved config field used by existing projects.",
+      "default": "none"
+    },
+    "coverage": {
+      "description": "Coverage settings. Use a boolean for quick toggle or object for options.",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true
+            },
+            "includeSpecs": {
+              "type": "boolean",
+              "description": "Include *.spec.ts files in coverage collection.",
+              "default": false
+            }
+          }
+        }
+      ],
+      "default": true
+    },
+    "buildOptions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "target": {
+          "type": "string",
+          "enum": ["wasi", "bindings"],
+          "default": "wasi"
+        }
+      },
+      "default": {
+        "args": [],
+        "target": "wasi"
+      }
+    },
+    "runOptions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "runtime": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "cmd": {
+              "type": "string",
+              "description": "Runtime command; supports placeholders like <file> and <name>.",
+              "default": "node ./.as-test/runners/default.wasi.js <file>"
+            }
+          },
+          "default": {
+            "cmd": "node ./.as-test/runners/default.wasi.js <file>"
+          }
+        },
+        "reporter": {
+          "type": "string",
+          "description": "Optional path to a custom reporter module.",
+          "default": ""
+        }
+      },
+      "default": {
+        "runtime": {
+          "cmd": "node ./.as-test/runners/default.wasi.js <file>"
+        },
+        "reporter": ""
+      }
+    }
+  }
+}

package/assembly/coverage.ts

@@ -8,17 +8,28 @@ export class CoverPoint {
 }
 
 export class Coverage {
+  public all: CoverPoint[] = [];
+  public allIndex: Map<string, i32> = new Map<string, i32>();
   public hashes: Map<string, CoverPoint> = new Map<string, CoverPoint>();
   public points: i32 = 0;
   static SN: Coverage = new Coverage();
 }
 
 export function __REGISTER(point: CoverPoint): void {
+  if (Coverage.SN.allIndex.has(point.hash)) return;
   Coverage.SN.points++;
+  Coverage.SN.allIndex.set(point.hash, Coverage.SN.all.length);
+  Coverage.SN.all.push(point);
   Coverage.SN.hashes.set(point.hash, point);
 }
 
 export function __COVER(hash: string): void {
+  if (Coverage.SN.allIndex.has(hash)) {
+    const index = Coverage.SN.allIndex.get(hash);
+    if (index < Coverage.SN.all.length) {
+      unchecked(Coverage.SN.all[index]).executed = true;
+    }
+  }
   if (Coverage.SN.hashes.has(hash)) Coverage.SN.hashes.delete(hash);
 }
 
@@ -29,3 +40,11 @@ export function __HASHES(): Map<string, CoverPoint> {
 export function __POINTS(): i32 {
   return Coverage.SN.points;
 }
+
+export function __UNCOVERED(): i32 {
+  return Coverage.SN.hashes.size;
+}
+
+export function __ALL_POINTS(): CoverPoint[] {
+  return Coverage.SN.all;
+}