╔═╗ ╔═╗    ╔═╗ ╔═╗ ╔═╗ ╔═╗
╠═╣ ╚═╗ ══  ║  ╠═  ╚═╗  ║ 
╩ ╩ ╚═╝     ╩  ╚═╝ ╚═╝  ╩ 

Table of Contents

• Installation
• Writing Tests
• Snapshots
• Coverage
• Custom Reporters
• Assertions
• License
• Contact

Installation

The installation script will set everything up for you:

npx as-test init --dir ./path-to-install

Alternatively, you can install it manually:

npm install as-test --save-dev

Writing Tests

Create assembly/__tests__/math.spec.ts:

import { describe, test, expect, run } from "as-test";

describe("math", () => {
  test("addition", () => {
    expect(1 + 2).toBe(3);
  });

  test("close to", () => {
    expect(3.14159).toBeCloseTo(3.14, 2);
  });
});

Test file selection (ast test)

No selectors:

ast test

Uses configured input patterns from as-test.config.json.

By name:

ast test sleep

Resolves to <configured-input-dir>/sleep.spec.ts.

By explicit path or glob:

ast test ./assembly/__tests__/sleep.spec.ts
ast test ./assembly/__tests__/*.spec.ts

Multiple selectors:

ast test sleep array ./assembly/__tests__/snapshot.spec.ts

If nothing matches, ast test exits non-zero with:

No test files matched: ...

Useful flags

• --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

Snapshots

Snapshot assertions are enabled by default.

• Read-only mode (default): missing/mismatched snapshots fail
• Update mode: --update-snapshots writes missing/mismatched snapshots

Commands:

ast test --update-snapshots
ast run --update-snapshots
ast test --no-snapshot

Snapshot files are stored in snapshotDir (default ./.as-test/snapshots).

Coverage

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.

Show point-level misses:

ast test --show-coverage

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:

{
  "$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": ""
  }
}

Key fields:

• 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

Custom Reporter

Set reporter path in config:

{
  "runOptions": {
    "reporter": "./tests/my-reporter.js"
  }
}

Reporter module should export createReporter (named or default):

export function createReporter(context) {
  return {
    onRunStart(event) {},
    onFileStart(event) {},
    onFileEnd(event) {},
    onSuiteStart(event) {},
    onSuiteEnd(event) {},
    onAssertionFail(event) {},
    onSnapshotMissing(event) {},
    onRunComplete(event) {},
  };
}

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 page.

You can view the full license using the following link: License

Contact

Please send all issues to GitHub Issues and to converse, please send me an email at me@jairus.dev

• Email: Send me inquiries, questions, or requests at me@jairus.dev
• GitHub: Visit the official GitHub repository Here
• Website: Visit my official website at jairus.dev
• Discord: Contact me at My Discord or on the AssemblyScript Discord Server