Small surface. Explicit state.

Module surface

Exports

import VanillaTest, {
    VanillaTest as NamedVanillaTest,
    VANILLA_TEST_COMPLETE_EVENT
} from 'vanilla-test';

The shared API depends only on Web-standard JavaScript. It does not import Node test APIs, inspect process, launch a browser, or terminate a host.

State model

Execution model

A runner has one active-test slot. Tests inside one instance are sequential; separate instances own separate state and can progress independently.

First-decision-wins is unchanged. The active case carries its own decision marker, so pass(), fail(), and done() enforce that rule in constant time instead of searching the accumulated result arrays.

• Only one test can be active on an instance.
• Raw descriptions must be unique within an instance.
• A report seals the suite; no later test can start.
• An empty suite reports successfully with a total of zero.
• Instance state, strict mode, listeners, descriptions, and results are isolated.

Instance surface

Constructor and properties

Strict helper behavior

const test = new VanillaTest();

test.compare(1, 1); // true: exact identity through Object.is
// test.compare(1, '1'); // would throw TypeError: not identical

test.strict = false;
console.log(test.is.number('42')); // false
console.log(test.compare(1, '1')); // false

Runner contract

Lifecycle methods

One complete lifecycle

const test = new VanillaTest();

test.expects('addition preserves the total');
try {
    test.compare(1 + 2, 3);
    test.pass();
} catch (error) {
    console.error(error);
    test.fail();
} finally {
    test.done();
}

const result = test.report();
console.log(result.ok); // true

EventTarget integration

Completion event timing

VanillaTest extends the native EventTarget. Its addEventListener() delegates to the native implementation and additionally notices completion subscriptions; removeEventListener() and dispatchEvent() retain their ordinary EventTarget behavior. Use onComplete() when you want the typed completion name plus an idempotent unsubscribe function.

1. report() creates and freezes the snapshot.
2. It logs the rendered report.
3. If a completion listener has been observed, it queues a microtask that dispatches a native CustomEvent. A runner that has never registered a completion listener queues no completion work.
4. report() returns the snapshot before the listener runs.
5. The event's detail is the exact returned snapshot object.

const test = new VanillaTest();
let phase = 'before report';

const unsubscribe = test.onComplete((event) => {
    console.log(event.type);          // vanilla-test:complete
    console.log(event.detail.ok);     // true
    console.log(phase);               // after report
}, { once: true });

test.expects('event delivery is asynchronous');
test.pass();
test.done();

const result = test.report();
phase = 'after report';
console.log(result.ok);               // true, before event listener

await Promise.resolve();            // let the queued event run
unsubscribe();                        // safe after a once-only listener ran

Registering the first completion listener after report() schedules delivery from the frozen snapshot. Dispatch happens at most once, and there is no replay after it occurs. Repeated report() calls do not dispatch again.

Stable consumer boundary

Result contract

Use the structured fields for automation. The report string is human-facing ANSI output and should not be parsed.

{
    passed: ['1) .expects addition preserves the total'],
    failed: [],
    total: 1,
    failureCount: 0,
    ok: true,
    report: 'ANSI-rendered console report'
}

• The result object, passed, and failed are frozen.
• The first report result is cached by identity: test.report() === test.report().
• report() never calls process.exit() and never assigns process.exitCode.
• A host adapter decides how an unsuccessful result affects a shell, page, worker, or CI job.

strong-type delegation

strong-type 2.0.1 helper surface

test.is exposes the complete isomorphic helper with 183 advertised shared validators plus core and extension methods. Matching calls return true. Mismatches throw TypeError while test.strict is true, or return false while it is false. The families below are a practical map, not an exhaustive substitute for the searchable strong-type reference.

How helpers decide

Common method catalogue

Predicates, unions, and comparisons

const test = new VanillaTest();

console.log(test.is.array([]));                 // true
console.log(test.is.date(new Date()));           // true
console.log(test.is.union(42, 'string|number')); // true
console.log(test.compare(1, '1'));              // throws in strict mode

test.strict = false;
console.log(test.is.promise({}));               // false

union(value, typesString) splits a pipe-delimited list and calls helpers by their exact method names. Use names from the catalogue above, such as 'string|number|null'.

Failure modes

Error matrix

Runner contract errors are always enforced, even when test.strict is false.

Complete integration

Runnable shared suite

Keep the test logic host-neutral and return the structured result. Each adapter decides how to expose success or failure.

test/shared-test.js

import VanillaTest from 'vanilla-test';

export default async function run() {
    const test = new VanillaTest();

    test.expects('addition preserves the total');
    try {
        test.compare(1 + 2, 3);
        test.pass();
    } catch (error) {
        console.error(error);
        test.fail();
    } finally {
        test.done();
    }

    test.expects('async values keep their shape');
    try {
        const value = await Promise.resolve({ ready: true });
        test.is.object(value);
        test.is.boolean(value.ready);
        test.pass();
    } catch (error) {
        console.error(error);
        test.fail();
    } finally {
        test.done();
    }

    return test.report();
}

Node adapter

Translate result.ok into a process exit code without changing the shared suite.

// test/node.js
import run from './shared-test.js';

const result = await run();
process.exitCode = result.ok ? 0 : 1;

node ./test/node.js

Browser adapter

Map package specifiers to served ES modules, import the same suite, and render a small page-level status for non-console users.

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <script type="importmap">
    {
        "imports": {
            "vanilla-test": "/node_modules/vanilla-test/index.js",
            "ansi-colors-es6": "/node_modules/ansi-colors-es6/index.js",
            "strong-type": "/node_modules/strong-type/index.js"
        }
    }
    </script>
</head>
<body>
    <p data-status>Running…</p>
    <p><strong>Check the console or DevTools.</strong></p>

    <script type="module">
        import run from './shared-test.js';

        const result = await run();
        document.querySelector('[data-status]').textContent =
            result.ok
                ? `Passed ${result.total} tests`
                : `Failed ${result.failureCount} of ${result.total} tests`;
    </script>
</body>
</html>

Apply the contract

Next steps