as-test 1.0.1 → 1.0.3

package/README.md

@@ -7,17 +7,15 @@
 
 - [Why as-test](#why-as-test)
 - [Installation](#installation)
-- [Examples](#examples)
+- [Docs](#docs)
+- [Project Layout](#project-layout)
 - [Writing Tests](#writing-tests)
-- [Setup Diagnostics](#setup-diagnostics)
 - [Mocking](#mocking)
 - [Snapshots](#snapshots)
-- [Coverage](#coverage)
-- [Custom Reporters](#custom-reporters)
-- [Assertions](#assertions)
-- [CLI Style Guide](#cli-style-guide)
+- [Fuzzing](#fuzzing)
+- [Runtimes](#runtimes)
+- [Examples](#examples)
 - [License](#license)
-- [Contact](#contact)
 
 </details>
 
@@ -34,353 +32,249 @@ Key benefits
 - Production-like testing: catch runtime-specific issues early
 - Inline mocking and snapshots
 - Custom reporters and coverage
+- Integrated fuzzing support
 
 ## Installation
 
-The installation script will set everything up for you:
-```bash
-npx as-test init --dir ./path-to-install
-```
+The easiest way to start is with the project initializer:
 
-To scaffold and install dependencies in one step:
 ```bash
-npx as-test init --dir ./path-to-install --install
+npx as-test init
 ```
 
-Alternatively, you can install it manually:
+That gives you a basic config file, a sample test, and optionally a sample fuzzer.
+
+If you already have a project and just want the package:
+
 ```bash
-npm install as-test --save-dev
+npm install --save-dev as-test
 ```
 
-## Examples
+## Docs
 
-Full runnable examples live in `examples/`, including:
+Full documentation lives at:
 
-- one standalone project per example (initialized with `ast init`)
-- complete spec files for core features
-- import mocking and import snapshot patterns
+<https://docs.jairus.dev/as-test>
 
-See `examples/README.md` for the walkthrough.
+## Project Layout
 
-Quick validation from this repo:
+By default, `as-test` looks for:
 
-```bash
-npm test
-npm run test:examples
-```
+- tests in `assembly/__tests__`
+- fuzzers in `assembly/__fuzz__`
+- config in `as-test.config.json`
+
+Generated files go into `.as-test/`.
 
 ## Writing Tests
 
-Create `assembly/__tests__/math.spec.ts`:
+Tests usually live in `assembly/__tests__/*.spec.ts`.
+
+Example:
 
 ```ts
-import { describe, test, expect, run } from "as-test";
+import { describe, expect, test } from "as-test";
 
 describe("math", () => {
-  test("addition", () => {
+  test("adds numbers", () => {
     expect(1 + 2).toBe(3);
   });
-
-  test("close to", () => {
-    expect(3.14159).toBeCloseTo(3.14, 2);
-  });
 });
 ```
 
-### File selection (`ast run`, `ast build`, `ast test`)
-
-No selectors:
+Run everything:
 
 ```bash
-ast test
+npx ast test
 ```
 
-Uses configured input patterns from `as-test.config.json`.
-
-By name:
+Run through the automatic worker pool:
 
 ```bash
-ast test sleep
+npx ast test --parallel
 ```
 
-Resolves to `<configured-input-dir>/sleep.spec.ts`.
-
-By explicit path or glob:
+Run one matching file:
 
 ```bash
-ast test ./assembly/__tests__/sleep.spec.ts
-ast test ./assembly/__tests__/*.spec.ts
+npx ast test math
 ```
 
-Multiple selectors:
+You do not need to learn every CLI flag to get started. Most projects can begin with `npx ast test`, then add more configuration only when they need it.
 
-```bash
-ast test sleep array ./assembly/__tests__/snapshot.spec.ts
-```
+## Mocking
 
-Comma-separated bare suite names:
+Mocking is supported, but the idea is to use it sparingly.
 
-```bash
-ast test box,custom,generics,string
-ast run box,custom,generics,string
-ast build box,custom,generics,string
-```
+With `as-test`, the ideal path is to run your code against the real runtime and real imports when you can. When that is not practical, you can mock individual imports instead of rebuilding your whole environment around fake behavior.
 
-If nothing matches, `ast test` exits non-zero with:
+For local functions, use `mockFn` and `unmockFn`. For host imports, use `mockImport` and `unmockImport`.
 
-```text
-No test files matched: ...
-```
+That is especially useful when:
 
-### 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.
-- `--list`: show resolved files, per-mode artifacts, and runtime command without executing
-- `--list-modes`: show configured and selected modes without executing
-- `--help` / `-h`: show command-specific help (`ast test --help`, `ast init --help`, etc.)
+- an import talks to the outside world
+- a host function is hard to reproduce in a test
+- you want to force an edge case that is difficult to trigger naturally
 
-Example:
-
-```bash
-ast build --enable try-as
-ast test --disable coverage
-```
+This keeps tests focused. You can still verify the logic in your AssemblyScript code without needing every runtime dependency to be real in every test. It also pairs well with snapshots when you want to capture the output of a mocked import and make sure it stays stable over time.
 
-Preview execution plan:
-
-```bash
-ast test --list
-ast test --list-modes
-ast run sleep --list --mode wasi
-ast build --list --mode wasi,bindings
-```
+Example:
 
-## Setup Diagnostics
+```ts
+import { describe, expect, mockFn, test, unmockFn } from "as-test";
 
-Use `ast doctor` to validate local setup before running tests.
+function getConfig(): string {
+  return "name=prod\nmode=live";
+}
 
-```bash
-ast doctor
-```
+mockFn(getConfig, (): string => "name=demo\nmode=test");
 
-You can also target specific modes and config files:
+describe("config", () => {
+  test("reads mocked data", () => {
+    expect(getConfig()).toContain("demo");
+  });
+});
 
-```bash
-ast doctor --config ./as-test.config.json --mode wasi,bindings
+unmockFn(getConfig);
 ```
 
-`doctor` checks:
+For import mocking, the same idea applies, but it is usually easier to keep the imported function in a small wrapper module and mock that import path from the spec.
 
-- config file loading and mode resolution
-- required dependencies (for example `assemblyscript`, `@assemblyscript/wasi-shim` for WASI targets)
-- runtime command parsing and executable availability
-- runtime script path existence (for script-host runtimes)
-- test spec file discovery from configured input patterns
+## Snapshots
 
-If any `ERROR` checks are found, `ast doctor` exits non-zero.
+Snapshots are useful when the output matters more than the exact step-by-step assertions.
 
-## Mocking
+They work well for:
 
-Use these helpers when you need to replace behavior during tests:
+- generated strings or structured text
+- serialized values
+- the output of mocked imports
+- larger results that would be awkward to check field by field
 
-- `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
+That lets you keep tests readable while still locking down behavior that should not change unexpectedly.
 
 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");
-});
+import { describe, expect, test } from "as-test";
 
-unmockFn(foo);
+function renderReport(): string {
+  return "name=demo\nmode=test";
+}
 
-it("function restored", () => {
-  expect(foo()).toBe("buz");
+describe("report", () => {
+  test("matches the saved output", () => {
+    expect(renderReport()).toMatchSnapshot();
+  });
 });
-
-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
+The first time you run a snapshot test, create the snapshot with:
 
-Snapshot assertions are enabled by default.
+```bash
+npx ast test --create-snapshots
+```
 
-- Read-only mode (default): missing/mismatched snapshots fail
-- Update mode: `--update-snapshots` writes missing/mismatched snapshots
+After that, a normal `npx ast test` will verify it.
 
-Commands:
+If an existing snapshot legitimately changed, overwrite it with:
 
 ```bash
-ast test --update-snapshots
-ast run --update-snapshots
-ast test --no-snapshot
+npx ast test --overwrite-snapshots
 ```
 
-Snapshot files are stored in `snapshotDir` (default `./.as-test/snapshots`).
+## Fuzzing
+
+Fuzzers usually live in `assembly/__fuzz__/*.fuzz.ts`.
+
+Example:
 
-## Coverage
+```ts
+import { expect, FuzzSeed, fuzz } from "as-test";
+
+fuzz("bounded integer addition", (left: i32, right: i32): bool => {
+  const sum = left + right;
+  expect(sum - right).toBe(left);
+  return sum >= i32.MIN_VALUE;
+}).generate((seed: FuzzSeed, run: (left: i32, right: i32) => bool): void => {
+  run(seed.i32({ min: -1000, max: 1000 }), seed.i32({ min: -1000, max: 1000 }));
+});
+```
 
-Coverage is controlled by `coverage` in config.
-Coverage reporting includes source files ending in `.ts` or `.as` only.
+If you used `npx ast init` with a fuzzer example, the config is already there. Otherwise, add a `fuzz` block to `as-test.config.json` so `npx ast fuzz` knows what to build:
 
-- Boolean form:
-  - `true` / `false`
-- Object form:
-  - `{ "enabled": true, "includeSpecs": false }`
+```json
+{
+  "fuzz": {
+    "input": ["./assembly/__fuzz__/*.fuzz.ts"],
+    "target": "bindings"
+  }
+}
+```
 
-Default behavior includes non-spec files and excludes `*.spec.ts` files.
+`ast fuzz` runs fuzz files across the selected modes, reports one result per file, and keeps the final summary separate from the normal test totals. If you want one combined command, use `ast test --fuzz`.
 
-Show point-level misses:
+Run only fuzzers:
 
 ```bash
-ast test --show-coverage
+npx ast fuzz
 ```
 
-Coverage artifacts:
+Run tests and fuzzers together:
 
-- `ast run` writes `coverage.log.json` to `coverageDir` (if enabled and not `"none"`)
-- `ast test` writes per-file coverage artifacts (`coverage.<file>.log.json`)
+```bash
+npx ast test --fuzz
+```
 
-Log artifacts:
+Fuzzing is there when you want broader input coverage, but it does not get in the way of the normal test flow. You can start with ordinary specs and add fuzzers later.
 
-- `ast run` writes `test.log.json` to `logs` (if `logs` is not `"none"`)
-- `ast test` writes per-file logs (`test.<file>.log.json`)
+## Runtimes
 
-## Configuration
+One of the main reasons to use `as-test` is that you are not locked into a single runtime.
 
-Default file: `as-test.config.json`
+If your project runs under WASI, bindings, or a custom runner, you can point your tests at that environment instead of treating Node.js as the only way to execute them.
 
-Example:
+For example, a simple WASI setup in `as-test.config.json` can look like this:
 
 ```json
 {
-  "$schema": "./as-test.config.schema.json",
   "input": ["./assembly/__tests__/*.spec.ts"],
-  "output": "./.as-test/",
-  "config": "none",
-  "coverage": true,
-  "env": {},
   "buildOptions": {
-    "cmd": "",
-    "args": [],
     "target": "wasi"
   },
-  "modes": {},
   "runOptions": {
     "runtime": {
       "cmd": "node ./.as-test/runners/default.wasi.js <file>"
-    },
-    "reporter": ""
+    }
   }
 }
 ```
 
-Key fields:
-
-- `input`: glob list of spec files
-- `output`: output alias. Use a root string (`"./.as-test/"`) or object (`{ "build": "...", "logs": "...", "coverage": "...", "snapshots": "..." }`)
-- `outDir`: compiled wasm output dir
-- `logs`: log output dir or `"none"`
-- `coverageDir`: coverage output dir or `"none"`
-- `snapshotDir`: snapshot storage dir
-- `outDir`, `logs`, `coverageDir`, and `snapshotDir` still work; when both are set, these explicit fields override `output`
-- `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`: reporter selection as a string or object
-
-Validation behavior:
-
-- Config parsing is strict for `ast build`, `ast run`, `ast test`, and `ast doctor`.
-- Invalid JSON fails early with parser details (`line`/`column` when provided by Node).
-- Unknown properties are rejected and include a nearest-key suggestion when possible.
-- Invalid property types are reported with their JSON path and a short fix hint.
-- On validation failure, the command exits non-zero and prints `run "ast doctor" to check your setup.`
-
-Example validation error:
-
-```text
-invalid config at ./as-test.config.json
-1. $.inpoot: unknown property
-     fix: use "input" if that was intended, otherwise remove this property
-2. $.runOptions.runtime.cmd: must be a string
-     fix: set to a runtime command including "<file>"
-run "ast doctor" to check your setup.
+Then run your tests normally:
+
+```bash
+npx ast test
 ```
 
-Example multi-runtime matrix:
+If you want to keep more than one runtime around, use modes:
 
 ```json
 {
+  "input": ["./assembly/__tests__/*.spec.ts"],
   "modes": {
-    "wasi-simd": {
-      "buildOptions": {
-        "target": "wasi",
-        "args": ["--enable", "simd"]
-      },
-      "runOptions": {
-        "runtime": {
-          "cmd": "wasmer run <file>"
-        }
-      }
-    },
-    "wasi-nosimd": {
+    "wasi": {
       "buildOptions": {
         "target": "wasi"
       },
       "runOptions": {
         "runtime": {
-          "cmd": "wasmer run <file>"
+          "cmd": "node ./.as-test/runners/default.wasi.js <file>"
         }
       }
     },
-    "bindings-node-simd": {
+    "bindings": {
       "buildOptions": {
-        "target": "bindings",
-        "args": ["--enable", "simd"]
+        "target": "bindings"
       },
       "runOptions": {
         "runtime": {
@@ -392,185 +286,23 @@ Example multi-runtime matrix:
 }
 ```
 
-Run all modes:
+Run a specific mode with:
 
 ```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
+npx ast test --mode wasi
 ```
 
-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):
+or
 
 ```bash
-ast run --reporter tap
+npx ast test --mode wasi,bindings
 ```
 
-TAP output is written to `./.as-test/reports/report.tap` by default.
+This is the general idea throughout the project: write tests once, then choose the runtime that matches how your code actually runs.
 
-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:
-
-```json
-{
-  "runOptions": {
-    "reporter": "./tests/my-reporter.js"
-  }
-}
-```
-
-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
-export function createReporter(context) {
-  return {
-    onRunStart(event) {},
-    onFileStart(event) {},
-    onFileEnd(event) {},
-    onSuiteStart(event) {},
-    onSuiteEnd(event) {},
-    onAssertionFail(event) {},
-    onSnapshotMissing(event) {},
-    onRunComplete(event) {},
-  };
-}
-```
+## Examples
 
-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:
-
-- `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(itemOrSubstring)` (`toContains` alias supported)
-- `toThrow()` (with `try-as`)
-- `toMatchSnapshot(name?)`
+Runnable example projects live in [examples/](./examples/README.md). They are useful if you want to see complete setups instead of isolated snippets.
 
 ## License
 
@@ -580,9 +312,9 @@ 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)
+Please send all issues to [GitHub Issues](https://github.com/JairusSW/json-as/issues) and to converse, please send me an email at [me@jairus.dev](mailto:me@jairus.dev)
 
 - **Email:** Send me inquiries, questions, or requests at [me@jairus.dev](mailto:me@jairus.dev)
-- **GitHub:** Visit the official GitHub repository [Here](https://github.com/JairusSW/as-test)
+- **GitHub:** Visit the official GitHub repository [Here](https://github.com/JairusSW/json-as)
 - **Website:** Visit my official website at [jairus.dev](https://jairus.dev/)
 - **Discord:** Contact me at [My Discord](https://discord.com/users/600700584038760448) or on the [AssemblyScript Discord Server](https://discord.gg/assemblyscript/)