.ns-container { max-width: 900px; margin: 0 auto; padding: 20px; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; line-height: 1.6; color: #1f2937; } .ns-title { font-size: 2rem; margin-bottom: 0.5rem; color: #0f172a; } .ns-desc { font-size: 1.1rem; color: #64748b; margin-bottom: 1.5rem; } .ns-nav { display: flex; flex-wrap: wrap; gap: 8px; padding: 12px 0; border-bottom: 1px solid #e2e8f0; margin-bottom: 2rem; position: sticky; top: 0; background: white; z-index: 10; } .ns-nav-link { padding: 6px 14px; border-radius: 6px; background: #f1f5f9; color: #3b82f6; text-decoration: none; font-size: 14px; font-weight: 500; } .ns-nav-link:hover { background: #3b82f6; color: white; } .ns-section { margin-bottom: 3rem; padding-bottom: 2rem; border-bottom: 1px solid #f1f5f9; } .ns-section-title { font-size: 1.5rem; color: #1e293b; margin-bottom: 1rem; padding-top: 1rem; } .ns-section-content h3 { font-size: 1.2rem; margin-top: 1.5rem; color: #334155; } .ns-section-content p { margin: 0.5rem 0; } .ns-section-content pre { background: #1e293b; color: #e2e8f0; padding: 12px 16px; border-radius: 6px; overflow-x: auto; font-size: 13px; line-height: 1.5; } .ns-section-content code { background: #f1f5f9; padding: 2px 6px; border-radius: 3px; font-size: 0.9em; } .ns-section-content pre code { background: none; padding: 0; } .ns-section-content table { width: 100%; border-collapse: collapse; margin: 1rem 0; } .ns-section-content th, .ns-section-content td { padding: 8px 12px; border: 1px solid #e2e8f0; text-align: left; } .ns-section-content th { background: #f8fafc; font-weight: 600; } .ns-section-content img { max-width: 100%; height: auto; } .ns-back-to-top { font-size: 13px; margin-top: 1.5rem; } .ns-back-to-top a { color: #3b82f6; text-decoration: none; } .ns-footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid #e2e8f0; color: #94a3b8; font-size: 13px; text-align: center; } .ns-js-notice { background: #fef3c7; border: 1px solid #f59e0b; border-radius: 6px; padding: 12px 16px; margin-bottom: 1.5rem; font-size: 14px; color: #92400e; }

NogginLessDom

This page works best with JavaScript enabled. You are viewing a static version of the content.

NogginLessDom

A zero-dependency testing framework built on node:test and node:assert.

NogginLessDom is a comprehensive testing framework for Node.js that ships a full-featured test runner, assertion library, DOM simulation, mocking utilities, code coverage, snapshot testing, and dependency analysis -- all with zero runtime dependencies. Every algorithm is implemented from scratch using only Node.js built-in modules. No third-party code ships to consumers, eliminating the supply chain attack surface entirely.

v0.0.25 -- 80 source files, 28K+ lines of TypeScript, 3100+ tests.

Key Features

Test Runner -- describe, it, test with skip, only, todo, concurrent, each, shuffle, retry, fails, skipIf, runIf, and full lifecycle hooks
30+ Assertions -- expect() with equality, truthiness, type, numeric, string, collection, exception, mock, and snapshot matchers plus .not, .resolves, .rejects modifiers
DOM Simulation -- Document, Element, 29 typed HTML elements, 20 event types, Shadow DOM, Custom Elements, Observer APIs, SVG, Canvas, IndexedDB, Web Workers, WebSocket, and more
Mocking -- fn(), spyOn(), module mocking, fake timers with full Date mocking, global/env stubbing, and async utilities
Code Coverage -- V8 and Istanbul providers, 11 reporters, configurable thresholds, source map support, per-test tracking
Dependency Analysis -- circular import detection, import depth analysis, unused import detection, dependency graph visualization
Zero Dependencies -- empty dependencies in package.json, no transitive node_modules to audit

Quick Start

Install as a dev dependency:

bun add -d @asymmetric-effort/nogginlessdom

Create a test file (example.test.ts):

import { describe, it, expect } from '@asymmetric-effort/nogginlessdom';

describe('Math', () => {
  it('adds two numbers', () => {
    expect(1 + 2).toBe(3);
  });

  it('compares objects deeply', () => {
    expect({ a: 1, b: [2, 3] }).toEqual({ a: 1, b: [2, 3] });
  });

  it('checks exceptions', () => {
    expect(() => {
      throw new Error('oops');
    }).toThrow('oops');
  });
});

Run the tests:

bun test

DOM Testing

NogginLessDom includes a full DOM simulation. No separate DOM library needed.

import {
  describe,
  it,
  expect,
  Document,
  Event,
} from '@asymmetric-effort/nogginlessdom';

describe('DOM', () => {
  it('creates and queries elements', () => {
    const doc = new Document();
    const div = doc.createElement('div');
    div.id = 'app';
    div.className = 'container';

    const paragraph = doc.createElement('p');
    paragraph.textContent = 'Hello, world!';
    div.appendChild(paragraph);
    doc.appendChild(div);

    expect(doc.getElementById('app')).toBeDefined();
    expect(doc.querySelector('p')?.textContent).toBe('Hello, world!');
    expect(doc.querySelectorAll('.container')).toHaveLength(1);
  });

  it('handles events with bubbling', () => {
    const doc = new Document();
    const parent = doc.createElement('div');
    const button = doc.createElement('button');
    parent.appendChild(button);

    const clicks: string[] = [];
    parent.addEventListener('click', () => clicks.push('parent'));
    button.addEventListener('click', () => clicks.push('button'));

    button.dispatchEvent(new Event('click', { bubbles: true }));
    expect(clicks).toEqual(['button', 'parent']);
  });
});

Mocking

Create mock functions, spy on methods, and control time:

import {
  describe,
  it,
  expect,
  fn,
  spyOn,
  useFakeTimers,
  useRealTimers,
} from '@asymmetric-effort/nogginlessdom';

describe('Mocking', () => {
  it('tracks mock function calls', () => {
    const mockFn = fn((x: number) => x * 2);
    mockFn(3);
    mockFn(5);

    expect(mockFn).toHaveBeenCalledTimes(2);
    expect(mockFn).toHaveBeenCalledWith(3);
    expect(mockFn.mock.results[0]).toEqual({ type: 'return', value: 6 });
  });

  it('spies on object methods', () => {
    const obj = { greet: (name: string) => `Hello, ${name}` };
    const spy = spyOn(obj, 'greet');

    obj.greet('Alice');
    expect(spy).toHaveBeenCalledWith('Alice');
    spy.mockRestore();
  });

  it('controls fake timers', () => {
    const clock = useFakeTimers();
    const callback = fn();

    setTimeout(callback, 1000);
    expect(callback).not.toHaveBeenCalled();

    clock.advanceTimersByTime(1000);
    expect(callback).toHaveBeenCalledOnce();

    useRealTimers();
  });
});

Code Coverage

Enable coverage in bunfig.toml:

[test]
coverage = true
coverageThreshold = { line = 90, function = 90, statement = 90 }

Run tests with coverage:

bun test

Coverage data is collected automatically when enabled. The framework supports V8 and Istanbul providers with 11 output formats including text, HTML, LCOV, Cobertura, and more. See the Configuration Guide for full details.

Why NogginLessDom?

Zero Supply Chain Risk

The dependencies field in package.json is {}. When you install NogginLessDom, you get exactly one package with no transitive dependency tree. Package takeovers, typosquatting, and malicious updates in transitive dependencies cannot affect your test toolchain.

Built on Node.js Built-ins

The test runner wraps node:test. Assertions wrap node:assert. These are battle-tested modules maintained by the Node.js team, guaranteed to be available in every Node.js >= 20 environment. NogginLessDom adds a familiar API layer on top without reinventing core functionality.

Everything in One Package

Test runner, assertions, DOM simulation, mocking, coverage, snapshots, and dependency analysis -- all from a single import. No need to install and configure separate packages for each capability.

Security by Design

DOM parsing never uses eval(), new Function(), or dynamic code execution. HTML input is validated through deterministic parsing. Path operations include symlink protection and traversal validation.

Documentation

Full documentation is available in the docs/ directory:

Getting Started -- Installation, first test, and core features walkthrough
Installation -- All package managers, TypeScript setup, and verification
Configuration -- Test patterns, coverage, reporters, dependency analysis, and environment variables
Architecture -- Module structure, dependency graph, build pipeline, and security design
API Reference -- Detailed documentation for every module

API Overview

Module	Key Exports	Docs
Test Runner	`describe`, `it`, `test`, lifecycle hooks, `.each`, `.skip`, `.only`, `.retry`	test-runner.md
Assertions	`expect()` with 30+ matchers, `.not`, `.resolves`, `.rejects`	assertions.md
DOM	`Document`, `Element`, 29 HTML elements, 20 event types, `Window`, `Storage`	dom.md
Mocking	`fn`, `spyOn`, `mock`, `vi`, `useFakeTimers`, module mocking	mocking.md
Coverage	V8 + Istanbul providers, 11 reporters, thresholds, per-test tracking	architecture.md
Snapshots	`toMatchSnapshot`, `toMatchInlineSnapshot`, custom serializers	assertions.md

Development

make setup          # Install dependencies and git hooks
make lint           # Run all linters (markdownlint, eslint, prettier, etc.)
make test           # Run unit, integration, and e2e tests
make build          # Clean build to build/

Requires Node.js >= 20.0.0.

Contributing

See CONTRIBUTING.md for development workflow, coding standards, and pull request guidelines.

Security

NogginLessDom has zero runtime dependencies, which eliminates the supply chain attack surface entirely. See SECURITY.md for our security policy and vulnerability reporting process.

License

MIT

Getting Started

This guide walks you through installing NogginLessDom, writing your first test, and exploring the framework's core capabilities. By the end you will have a working test suite using the test runner, assertions, DOM simulation, mocking, snapshots, and coverage.

Installation

Install NogginLessDom as a dev dependency. It has zero runtime dependencies, so this is the only package you need.

With Bun (recommended):

bun add -d @asymmetric-effort/nogginlessdom

With npm:

npm install --save-dev @asymmetric-effort/nogginlessdom

For additional package managers and TypeScript setup, see the Installation Guide.

Your First Test

Create a file named math.test.ts:

import { describe, it, expect } from '@asymmetric-effort/nogginlessdom';

describe('Math', () => {
  it('adds two numbers', () => {
    expect(1 + 2).toBe(3);
  });

  it('handles negative numbers', () => {
    expect(-1 + -2).toBe(-3);
  });
});

This test file uses three functions from NogginLessDom:

describe groups related tests into a suite.
it defines a single test case.
expect creates an assertion that checks a value against a matcher.

Running Tests

Run your tests with Bun:

bun test

You should see output indicating that both tests passed. Under the hood, NogginLessDom delegates to node:test, so you get the same reliable test execution and reporting that Node.js provides natively.

Run a specific file:

bun test math.test.ts

Run tests matching a name pattern:

bun test --grep "adds two"

Assertions

NogginLessDom provides an expect() function with 30+ chainable matchers:

import { describe, it, expect } from '@asymmetric-effort/nogginlessdom';

describe('Assertions', () => {
  it('checks equality', () => {
    expect('hello').toBe('hello');
    expect({ a: 1 }).toEqual({ a: 1 });
    expect({ a: 1, b: 2 }).toMatchObject({ a: 1 });
  });

  it('checks truthiness', () => {
    expect(true).toBeTruthy();
    expect(0).toBeFalsy();
    expect(null).toBeNull();
    expect(undefined).toBeUndefined();
  });

  it('checks types and numbers', () => {
    expect('hello').toBeTypeOf('string');
    expect(new Date()).toBeInstanceOf(Date);
    expect(3.14).toBeCloseTo(Math.PI, 1);
    expect(10).toBeGreaterThan(5);
  });

  it('checks collections', () => {
    expect([1, 2, 3]).toContain(2);
    expect([1, 2, 3]).toHaveLength(3);
    expect({ name: 'Alice' }).toHaveProperty('name');
  });

  it('uses negation', () => {
    expect(1).not.toBe(2);
    expect('foo').not.toContain('bar');
  });

  it('checks exceptions', () => {
    expect(() => {
      throw new Error('oops');
    }).toThrow('oops');
  });

  it('uses asymmetric matchers', () => {
    expect({ name: 'Alice', age: 30 }).toEqual(
      expect.objectContaining({ name: 'Alice' }),
    );
    expect([1, 2, 3]).toEqual(expect.arrayContaining([1, 3]));
  });

  it('uses custom predicates', () => {
    expect(42).toSatisfy((n: number) => n > 0 && n < 100);
  });
});

DOM Testing

NogginLessDom includes a complete DOM simulation. No separate DOM library is needed. Create documents, add elements, query the tree, dispatch events, and assert the results.

import {
  describe,
  it,
  expect,
  beforeEach,
  Document,
  Event,
  CustomEvent,
  createWindow,
} from '@asymmetric-effort/nogginlessdom';

describe('DOM', () => {
  let doc: Document;

  beforeEach(() => {
    doc = new Document();
  });

  it('creates and queries elements', () => {
    const div = doc.createElement('div');
    div.id = 'app';
    div.className = 'container main';

    const heading = doc.createElement('h1');
    heading.textContent = 'Welcome';
    div.appendChild(heading);

    const paragraph = doc.createElement('p');
    paragraph.textContent = 'Hello, world!';
    div.appendChild(paragraph);

    doc.appendChild(div);

    expect(doc.getElementById('app')).toBeDefined();
    expect(doc.querySelector('h1')?.textContent).toBe('Welcome');
    expect(doc.querySelectorAll('p')).toHaveLength(1);
    expect(div.classList.contains('container')).toBe(true);
  });

  it('handles events with bubbling', () => {
    const parent = doc.createElement('div');
    const button = doc.createElement('button');
    parent.appendChild(button);

    const clicks: string[] = [];
    parent.addEventListener('click', () => clicks.push('parent'));
    button.addEventListener('click', () => clicks.push('button'));

    button.dispatchEvent(new Event('click', { bubbles: true }));
    expect(clicks).toEqual(['button', 'parent']);
  });

  it('dispatches custom events with detail', () => {
    const el = doc.createElement('div');
    let received: unknown = null;

    el.addEventListener('notify', (e: Event) => {
      received = (e as CustomEvent).detail;
    });

    el.dispatchEvent(
      new CustomEvent('notify', { detail: { message: 'hello' } }),
    );
    expect(received).toEqual({ message: 'hello' });
  });

  it('uses innerHTML for complex structures', () => {
    const container = doc.createElement('div');
    container.innerHTML = `
      <nav>
        <a href="/">Home</a>
        <a href="/about">About</a>
      </nav>
    `;
    doc.appendChild(container);

    const links = doc.querySelectorAll('a');
    expect(links).toHaveLength(2);
  });

  it('provides a full window environment', () => {
    const window = createWindow();
    expect(window.document).toBeDefined();
    expect(window.location).toBeDefined();
    expect(window.history).toBeDefined();
    expect(window.navigator).toBeDefined();
    expect(window.localStorage).toBeDefined();
  });
});

Mocking

Create mock functions, spy on existing methods (including property accessors), and control time with fake timers.

Mock Functions

import { describe, it, expect, fn } from '@asymmetric-effort/nogginlessdom';

describe('Mock functions', () => {
  it('tracks calls and return values', () => {
    const mockFn = fn((x: number) => x * 2);

    mockFn(3);
    mockFn(5);

    expect(mockFn).toHaveBeenCalledTimes(2);
    expect(mockFn).toHaveBeenCalledWith(3);
    expect(mockFn.mock.results[0]).toEqual({ type: 'return', value: 6 });
  });

  it('stubs return values', () => {
    const fetchUser = fn();
    fetchUser.mockReturnValue({ id: 1, name: 'Alice' });

    expect(fetchUser()).toEqual({ id: 1, name: 'Alice' });
  });

  it('mocks async functions', () => {
    const fetchData = fn();
    fetchData.mockResolvedValue({ status: 'ok' });

    expect(fetchData()).resolves.toEqual({ status: 'ok' });
  });
});

Spying on Methods

import { describe, it, expect, spyOn } from '@asymmetric-effort/nogginlessdom';

describe('Spying', () => {
  it('spies on object methods', () => {
    const calculator = {
      add: (a: number, b: number) => a + b,
    };

    const spy = spyOn(calculator, 'add');
    calculator.add(2, 3);

    expect(spy).toHaveBeenCalledWith(2, 3);
    spy.mockRestore();
  });
});

Fake Timers

import {
  describe,
  it,
  expect,
  fn,
  useFakeTimers,
  useRealTimers,
} from '@asymmetric-effort/nogginlessdom';

describe('Fake timers', () => {
  it('advances timers by time', () => {
    const clock = useFakeTimers();
    const callback = fn();

    setTimeout(callback, 5000);
    expect(callback).not.toHaveBeenCalled();

    clock.advanceTimersByTime(5000);
    expect(callback).toHaveBeenCalledOnce();

    useRealTimers();
  });

  it('mocks the Date constructor', () => {
    const clock = useFakeTimers({ now: new Date('2026-01-01T00:00:00Z') });

    expect(Date.now()).toBe(new Date('2026-01-01T00:00:00Z').getTime());

    clock.setSystemTime(new Date('2026-06-15T12:00:00Z'));
    expect(Date.now()).toBe(new Date('2026-06-15T12:00:00Z').getTime());

    useRealTimers();
  });
});

Snapshot Testing

Capture and compare values across test runs:

import { describe, it, expect } from '@asymmetric-effort/nogginlessdom';

describe('Snapshots', () => {
  it('matches a snapshot', () => {
    const data = { name: 'Alice', items: [1, 2, 3] };
    expect(data).toMatchSnapshot();
  });

  it('matches an inline snapshot', () => {
    expect({ greeting: 'hello' }).toMatchInlineSnapshot();
  });
});

On the first run, snapshots are created and saved. On subsequent runs, values are compared against the stored snapshots. Update snapshots when intentional changes occur by passing the --update-snapshots flag.

Coverage

Enable code coverage in bunfig.toml:

[test]
coverage = true
coverageThreshold = { line = 90, function = 90, statement = 90 }

Then run tests as usual:

bun test

Coverage data is collected automatically. If any metric falls below the configured threshold, the test run fails with a non-zero exit code. The framework supports V8 and Istanbul providers with 11 output formats. See the Configuration Guide for full coverage options.

Watch Mode

Re-run tests automatically when files change:

bun test --watch

This watches your source and test files and re-runs the relevant test suite whenever a change is detected. Combine with --grep to watch a specific subset of tests during development.

Next Steps

API Reference -- Detailed documentation of every function, class, and matcher
Configuration Guide -- Test patterns, coverage, reporters, dependency analysis, and environment variables
Architecture -- How the framework is built, module structure, and design principles
Installation Guide -- Additional package managers, TypeScript configuration, and what gets installed

API Reference

This section documents every public function, class, and interface exported by NogginLessDom. All exports are available from the top-level package import:

import {
  // Test Runner
  describe, it, test, beforeEach, afterEach, beforeAll, afterAll,

  // Assertions
  expect,

  // DOM Simulation
  Document, Element, Node, TextNode, Event,

  // Mocking
  fn, spyOn, useFakeTimers, useRealTimers,
} from '@asymmetric-effort/nogginlessdom';

Modules

Test Runner

The test runner wraps node:test to provide a comprehensive API for defining test suites, test cases, and lifecycle hooks.

Exports: describe, it, test, beforeEach, afterEach, beforeAll, afterAll

Full Test Runner API Reference

Assertions

The assertions module wraps node:assert to provide an expect(value) API with chainable matchers. Supports equality, type checking, collection inspection, exception testing, and async assertions.

Exports: expect

Full Assertions API Reference

DOM Simulation

The DOM module provides a complete DOM environment for testing, built from scratch with zero dependencies. It implements the core DOM interfaces needed for testing web applications: document creation, element manipulation, tree traversal, CSS selector queries, and event dispatching.

Exports: Document, Element, Node, TextNode, Event

Full DOM API Reference

Mocking

The mocking module provides utilities for creating mock functions, spying on object methods, and controlling timers. Mock functions track their calls and return values, allowing you to make assertions about how code under test interacts with its dependencies.

Exports: fn, spyOn, useFakeTimers, useRealTimers

Full Mocking API Reference

Coverage

The coverage module provides code coverage collection, reporting, threshold enforcement, and baseline tracking. It supports V8, Istanbul, and custom coverage providers with 12 built-in reporters.

Exports: startCoverage, takeCoverage, stopCoverage, reportCoverage, checkCoverageThresholds, saveBaseline, loadBaseline, diffBaseline

Full Coverage API Reference

Design Notes

All modules are designed to be used independently or together. There are no cross-dependencies between modules -- you can import only the test runner, only the assertions, or only the DOM simulation as your use case requires.

Every function maps directly to a Node.js built-in API or is implemented from scratch within the package. No third-party code is involved at any layer.

The API surface follows widely adopted testing conventions. If you are familiar with describe, it, expect, fn, and spyOn, you already know how to use NogginLessDom. The DOM API follows the browser DOM standard as closely as practical.

Test Runner API Reference

The test runner module wraps Node.js's built-in node:test module to provide a comprehensive interface for organizing and running tests, including test filtering, watch mode, pluggable reporters, test isolation, mock hoisting, and dependency analysis.

import {
  describe,
  it,
  test,
  beforeEach,
  afterEach,
  beforeAll,
  afterAll,
  onTestFailed,
  onTestFinished,
  setTestNamePattern,
  setTestFilePattern,
  configureIsolation,
  setSerialMode,
  configureReporters,
} from '@asymmetric-effort/nogginlessdom';

Test Suites

`describe(name, fn)`

Define a test suite. Suites can be nested to create hierarchical test structures. When serial mode is enabled (via setSerialMode(true)), suites default to concurrency: 1.

function describe(name: string, fn: SuiteFn): void;

Parameter	Type	Description
`name`	`string`	Name of the test suite
`fn`	`() => void \	Promise<void>`	Suite body containing tests

describe('UserService', () => {
  describe('create', () => {
    it('should create a user with valid data', () => {
      // ...
    });

    it('should reject invalid email', () => {
      // ...
    });
  });
});

`describe.skip(name, fn)`

Skip an entire test suite. The suite and all its tests are registered but not executed.

function describe.skip(name: string, fn: SuiteFn): void;

describe.skip('Experimental feature', () => {
  it('should do something', () => {
    // not executed
  });
});

`describe.only(name, fn)`

Run only this suite (and other suites/tests marked only). All other suites are skipped.

function describe.only(name: string, fn: SuiteFn): void;

describe.only('Focus on this suite', () => {
  it('runs this test', () => {});
});

`describe.todo(name, fn?)`

Mark a suite as a TODO placeholder. The suite is registered but the body is never executed.

function describe.todo(name: string, fn?: SuiteFn): void;

describe.todo('Future feature');

`describe.concurrent(name, fn)`

Run all tests within this suite concurrently by setting concurrency: true on the underlying node:test describe call.

function describe.concurrent(name: string, fn: SuiteFn): void;

describe.concurrent('Parallel tests', () => {
  it('test A', async () => { /* ... */ });
  it('test B', async () => { /* ... */ });
});

`describe.serial(name, fn)`

Force all tests within this suite to run sequentially by setting concurrency: 1. Useful inside a concurrent parent suite where specific tests must not overlap.

function describe.serial(name: string, fn: SuiteFn): void;

describe.concurrent('mostly parallel', () => {
  it('fast A', async () => { /* ... */ });

  describe.serial('database tests', () => {
    it('insert row', async () => { /* ... */ });
    it('read row', async () => { /* ... */ });
  });
});

`describe.shuffle(name, fn)`

Run the tests within this suite in a randomized order using a seeded Fisher-Yates shuffle. The seed defaults to Date.now() and can be overridden via the SHUFFLE_SEED environment variable for reproducibility.

function describe.shuffle(name: string, fn: SuiteFn): void;

describe.shuffle('Randomized order', () => {
  it('test A', () => { /* ... */ });
  it('test B', () => { /* ... */ });
  it('test C', () => { /* ... */ });
});

Set SHUFFLE_SEED for reproducible ordering:

SHUFFLE_SEED=12345 bun test

`describe.skipIf(condition)(name, fn)`

Conditionally skip a suite. If condition is truthy, the suite is skipped.

function describe.skipIf(condition: unknown): (name: string, fn: SuiteFn) => void;

describe.skipIf(process.platform === 'win32')('Unix-only tests', () => {
  it('uses /tmp', () => { /* ... */ });
});

`describe.runIf(condition)(name, fn)`

Conditionally run a suite. If condition is truthy, the suite runs; otherwise it is skipped.

function describe.runIf(condition: unknown): (name: string, fn: SuiteFn) => void;

describe.runIf(process.env.CI)('CI-only tests', () => {
  it('checks deployment', () => { /* ... */ });
});

`describe.each(table)(name, fn)`

Generate a test suite for each entry in a data table. Supports printf-style formatting (%s, %d, %i, %f, %j, %o, %%) and $variable syntax for object entries.

function describe.each(table: unknown[]): (
  name: string,
  fn: (...args: unknown[]) => void | Promise<void>,
) => void;

describe.each([
  { input: 'hello', expected: 5 },
  { input: 'world', expected: 5 },
])('length of "$input"', ({ input, expected }) => {
  it(`should be ${expected}`, () => {
    expect(input.length).toBe(expected);
  });
});

// With array entries and printf formatting
describe.each([
  ['GET', 200],
  ['POST', 201],
])('HTTP %s returns %d', (method, status) => {
  it('responds correctly', async () => {
    const res = await request(method);
    expect(res.status).toBe(status);
  });
});

Tests

`it(name, fn, options?)` / `test(name, fn, options?)`

Define an individual test case. test is an alias for it.

function it(name: string, fn: TestFn, options?: TestOptions): void;
function test(name: string, fn: TestFn, options?: TestOptions): void;

TestOptions:

Option	Type	Description
`skip`	`boolean \	string`	Skip this test. A string value is used as reason.
`only`	`boolean`	Run only this test (and others marked `only`).
`todo`	`boolean \	string`	Mark as TODO. Registered but not executed.
`timeout`	`number`	Maximum time in milliseconds before test fails.
`retries`	`number`	Number of additional retry attempts on failure.

// Basic test
it('should return the sum', () => {
  expect(add(1, 2)).toBe(3);
});

// Async test
it('should fetch data', async () => {
  const data = await fetchData();
  expect(data).toBeDefined();
});

// With options
it('should handle edge case', () => {
  // ...
}, { skip: 'Not implemented yet' });

it('should complete quickly', async () => {
  await longRunningOperation();
}, { timeout: 5000 });

When a test name pattern is active (see Test Filtering below), tests whose full name does not match the pattern are automatically skipped with the reason "filtered by test name pattern".

`it.skip(name, fn?)`

Skip a test. The test is registered but not executed.

function it.skip(name: string, fn?: TestFn): void;

it.skip('not ready yet', () => {
  // not executed
});

`it.only(name, fn)`

Run only this test (and others marked only). When a name pattern is active, the pattern and .only are intersected: the test must match both.

function it.only(name: string, fn: TestFn): void;

it.only('debug this test', () => {
  expect(true).toBe(true);
});

`it.todo(name, fn?)`

Mark a test as a TODO placeholder. The test body is never executed.

function it.todo(name: string, fn?: TestFn): void;

it.todo('implement error handling');

`it.concurrent(name, fn, options?)`

Run this test concurrently with other concurrent tests. The test function is automatically wrapped with isolation cleanup (see Test Isolation).

function it.concurrent(name: string, fn: TestFn, options?: TestOptions): void;

it.concurrent('async operation A', async () => {
  const result = await operationA();
  expect(result).toBeDefined();
});

`it.each(table)(name, fn)`

Generate a test for each entry in a data table. Supports printf-style formatting (%s, %d, %i, %f, %j, %o, %%) and $variable syntax for object entries.

function it.each(table: unknown[]): (
  name: string,
  fn: (...args: unknown[]) => void | Promise<void>,
) => void;

it.each([
  [1, 2, 3],
  [2, 3, 5],
  [10, 20, 30],
])('add(%d, %d) = %d', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

it.each([
  { a: 1, b: 2, sum: 3 },
  { a: 5, b: 5, sum: 10 },
])('$a + $b = $sum', ({ a, b, sum }) => {
  expect(a + b).toBe(sum);
});

`it.skipIf(condition)(name, fn)`

Conditionally skip a test based on a runtime condition.

function it.skipIf(condition: unknown): (name: string, fn: TestFn) => void;

it.skipIf(!process.env.API_KEY)('requires API key', () => {
  // only runs when API_KEY is set
});

`it.runIf(condition)(name, fn)`

Conditionally run a test based on a runtime condition.

function it.runIf(condition: unknown): (name: string, fn: TestFn) => void;

it.runIf(process.env.CI)('CI-only test', () => {
  // only runs in CI
});

`it.fails(name, fn)`

Assert that a test is expected to fail. The test passes if the test function throws, and fails if the function completes without throwing.

function it.fails(name: string, fn: TestFn): void;

it.fails('known broken behavior', () => {
  expect(brokenFunction()).toBe('correct');
});

`it.retry(n)(name, fn)`

Retry a test up to n additional times on failure. The test only fails after all retries are exhausted.

function it.retry(n: number): (name: string, fn: TestFn) => void;

it.retry(3)('flaky network test', async () => {
  const response = await fetch('https://api.example.com/data');
  expect(response.ok).toBe(true);
});

`it.shuffle`

Alias for it. Shuffling a single test is a no-op. Use describe.shuffle to randomize test ordering within a suite.

Lifecycle Hooks

`beforeEach(fn)`

function beforeEach(fn: TestFn): void;

describe('Database', () => {
  let db: Database;

  beforeEach(() => {
    db = new Database(':memory:');
    db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
  });

  it('should insert a row', () => {
    db.exec("INSERT INTO users (name) VALUES ('Alice')");
    expect(db.query('SELECT * FROM users')).toHaveLength(1);
  });
});

`afterEach(fn)`

function afterEach(fn: TestFn): void;

describe('FileWriter', () => {
  afterEach(() => {
    fs.rmSync('/tmp/test-output', { recursive: true, force: true });
  });

  it('should write a file', () => {
    writeFile('/tmp/test-output/data.txt', 'hello');
    expect(fs.existsSync('/tmp/test-output/data.txt')).toBe(true);
  });
});

`beforeAll(fn)`

function beforeAll(fn: TestFn): void;

describe('API Integration', () => {
  let server: Server;

  beforeAll(async () => {
    server = await startTestServer();
  });

  afterAll(async () => {
    await server.close();
  });

  it('should respond to GET /', async () => {
    const res = await fetch(`http://localhost:${server.port}/`);
    expect(res.status).toBe(200);
  });
});

`afterAll(fn)`

function afterAll(fn: TestFn): void;

`onTestFailed(callback)`

Register a callback invoked when a test fails. The callback receives a context object with the test name and the error that caused the failure.

function onTestFailed(callback: (context: TestFailedContext) => void): void;

interface TestFailedContext {
  name: string;
  error: unknown;
}

onTestFailed(({ name, error }) => {
  console.log(`Test "${name}" failed:`, error);
});

`onTestFinished(callback)`

Register a callback invoked when a test finishes (pass or fail). The callback receives a context object with the test name and whether it passed.

function onTestFinished(callback: (context: TestFinishedContext) => void): void;

interface TestFinishedContext {
  name: string;
  passed: boolean;
}

onTestFinished(({ name, passed }) => {
  console.log(`Test "${name}" ${passed ? 'passed' : 'failed'}`);
});

`clearLifecycleHooks()`

Clear all registered onTestFailed and onTestFinished callbacks. Useful for test isolation between suites.

function clearLifecycleHooks(): void;

`installAutoMockCleanup()`

Install an afterEach hook that automatically restores all mocks after each test. Call once at the top of a suite where automatic mock cleanup is desired.

function installAutoMockCleanup(): void;

describe('with auto cleanup', () => {
  installAutoMockCleanup();

  it('mocks are restored automatically', () => {
    const spy = spyOn(console, 'log');
    console.log('test');
    expect(spy).toHaveBeenCalled();
    // spy is restored after this test completes
  });
});

Test Filtering

Filter which tests run by name pattern or file pattern. Patterns can be set programmatically or via environment variables.

`setTestNamePattern(pattern, options?)`

Set a test name filter. Tests whose full name (describe names joined with > plus the test name) does not match the pattern are automatically skipped.

function setTestNamePattern(
  pattern: string | RegExp,
  options?: { invert?: boolean },
): void;

Parameter	Type	Description
`pattern`	`string \	RegExp`	Pattern to match against full test names
`options.invert`	`boolean`	If `true`, skip tests that match the pattern

// Run only tests containing "auth"
setTestNamePattern('auth');

// Run only tests matching a regex
setTestNamePattern(/UserService > create/);

// Run all tests EXCEPT those matching the pattern
setTestNamePattern('slow', { invert: true });

Full test names are built from the nested describe stack joined with > :

UserService > create > should create a user with valid data

Environment variable: Set TEST_NAME_PATTERN to apply a name pattern automatically on module load.

TEST_NAME_PATTERN="auth" bun test

`clearTestNamePattern()`

Remove the active test name filter.

function clearTestNamePattern(): void;

`getTestNamePattern()`

Return the current name filter state.

function getTestNamePattern(): { pattern: RegExp | null; invert: boolean };

`setTestFilePattern(glob)`

Set a file glob pattern. Test files whose paths do not match are skipped entirely.

function setTestFilePattern(glob: string): void;

setTestFilePattern('src/**/*.test.ts');

Environment variable: Set TEST_FILE_PATTERN to apply a file pattern automatically on module load.

TEST_FILE_PATTERN="src/auth/**" bun test

`clearTestFilePattern()`

Remove the active file pattern filter.

function clearTestFilePattern(): void;

`getTestFilePattern()`

Return the current file glob pattern, or null if none is set.

function getTestFilePattern(): string | null;

Watch Mode

Watch mode monitors source and test files for changes and re-runs affected tests automatically.

`watchTests(testRunner, options?)`

Start watching for file changes and re-run affected test files.

function watchTests(
  testRunner: (files: string[]) => Promise<void>,
  options?: WatchOptions,
): WatchController;

WatchOptions:

Option	Type	Default
`watchInclude`	`string[]`	`['src/', 'tests/']`
`watchExclude`	`string[]`	`['node_modules', '.git', 'build']`
`debounceMs`	`number`	`300`
`cwd`	`string`	`process.cwd()`

const controller = watchTests(
  async (files) => {
    console.log('Running tests:', files);
    // execute tests for the given files
  },
  {
    watchInclude: ['src/**', 'tests/**'],
    watchExclude: ['node_modules', '.git', 'build', 'coverage'],
    debounceMs: 500,
  },
);

// Later: stop watching
controller.stop();

When a source file changes, the watch system rebuilds the import graph and identifies which test files depend on the changed file. Only those test files are re-run. If a test file itself changes, it is re-run directly. If a changed source file has no known test dependents, all test files are re-run.

WatchController

The object returned by watchTests.

interface WatchController {
  stop(): void;
  runAll(): void;
  runFailed(): void;
  getWatchedFiles(): string[];
}

Method	Description
`stop()`	Stop all file watchers and cancel pending runs
`runAll()`	Re-run all discovered test files
`runFailed()`	Re-run only previously failed test files
`getWatchedFiles()`	Return the list of all currently watched file paths

// Re-run all tests on demand
controller.runAll();

// Re-run only failed tests
controller.runFailed();

// Inspect watched files
console.log(controller.getWatchedFiles());

Utility Functions

`matchGlob(filePath, pattern)`

Match a file path against a glob pattern. Supports * (single segment) and ** (any depth).

function matchGlob(filePath: string, pattern: string): boolean;

`filterPaths(paths, include, exclude)`

Filter an array of paths by include and exclude glob patterns.

function filterPaths(
  paths: string[],
  include: string[],
  exclude: string[],
): string[];

`buildImportGraph(files)`

Build a reverse dependency map from a set of file paths. Each key is a resolved import target; each value is the set of files that import it.

function buildImportGraph(files: string[]): Map<string, Set<string>>;

Reporters

The reporter system provides pluggable output formatting for test results.

TestReporter Interface

All reporters implement this interface. Every method is optional.

interface TestReporter {
  onSuiteStart?(event: TestEvent): void;
  onSuiteEnd?(event: TestEvent): void;
  onTestStart?(event: TestEvent): void;
  onTestPass?(event: TestEvent): void;
  onTestFail?(event: TestEvent): void;
  onTestSkip?(event: TestEvent): void;
  onTestTodo?(event: TestEvent): void;
  onRunStart?(info: { files: string[]; totalTests: number }): void;
  onRunEnd?(summary: RunSummary): void;
}

interface TestEvent {
  name: string;
  suite?: string;
  file?: string;
  duration?: number;
  error?: Error;
  reason?: string;
}

interface RunSummary {
  passed: number;
  failed: number;
  skipped: number;
  todo: number;
  duration: number;
}

Built-in Reporters

Five built-in reporters are available by name:

Name	Class	Description
`default`	`DefaultReporter`	Compact PASS/FAIL output with summary
`verbose`	`VerboseReporter`	Full test names with checkmarks, durations, and suite headers
`dot`	`DotReporter`	Single character per test: `.` pass, `F` fail, `s` skip, `t` todo
`json`	`JsonReporter`	NDJSON output (one JSON object per event)
`silent`	`SilentReporter`	No output at all

All reporters except SilentReporter accept ReporterOptions:

interface ReporterOptions {
  outputFile?: string;   // Write output to a file instead of stdout
  colors?: boolean;      // Force color on/off (defaults to TTY detection)
}

import { VerboseReporter } from '@asymmetric-effort/nogginlessdom';

const reporter = new VerboseReporter({ outputFile: 'test-results.txt' });

`configureReporters(config)`

Configure the global reporter manager. Replaces any previously configured reporters.

function configureReporters(config: {
  reporter?: string | TestReporter;
  reporters?: Array<string | TestReporter>;
  outputFile?: string;
}): void;

Use reporter for a single reporter, or reporters for multiple. When outputFile is specified, it is passed to each built-in reporter created by name.

// Single reporter by name
configureReporters({ reporter: 'verbose' });

// Multiple reporters (multi-reporter)
configureReporters({
  reporters: ['default', new JsonReporter({ outputFile: 'results.ndjson' })],
});

// With output file
configureReporters({ reporter: 'json', outputFile: 'results.json' });

ReporterManager

The ReporterManager class manages a collection of reporters and dispatches events to all of them.

class ReporterManager {
  addReporter(reporter: TestReporter | string): void;
  removeReporter(reporter: TestReporter): void;
  notify(event: string, data: unknown): void;
  getReporters(): TestReporter[];
  static create(name: string, options?: ReporterOptions): TestReporter;
}

import { ReporterManager } from '@asymmetric-effort/nogginlessdom';

const manager = new ReporterManager();
manager.addReporter('verbose');
manager.addReporter(new JsonReporter({ outputFile: 'log.json' }));

// Dispatch an event to all reporters
manager.notify('onTestPass', { name: 'my test', duration: 42 });

Errors thrown by individual reporters are swallowed so a broken reporter never crashes the test run.

`getReporterManager()`

Get the global singleton ReporterManager. Creates one with a DefaultReporter if none exists yet.

function getReporterManager(): ReporterManager;

`resetReporterManager()`

Reset the global reporter manager to undefined, so the next call to getReporterManager() creates a fresh instance.

function resetReporterManager(): void;

Test Isolation

Configure how concurrent tests are isolated from each other.

`configureIsolation(config)`

Set the isolation mode for concurrent tests.

function configureIsolation(config: IsolationConfig): void;

interface IsolationConfig {
  isolate?: boolean;                      // default: true for concurrent, false for sequential
  isolation?: 'full' | 'mocks' | 'none'; // default: 'full'
}

Isolation modes:

Mode	Behavior
`full`	Restore all mocks, use real timers, unstub all globals
`mocks`	Restore all mocks only
`none`	No automatic cleanup

By default, concurrent tests (it.concurrent) run with full isolation. Sequential tests run without isolation. Use configureIsolation to override these defaults.

// Only restore mocks, keep fake timers
configureIsolation({ isolation: 'mocks' });

// Disable all automatic cleanup
configureIsolation({ isolation: 'none' });

// Force isolation even for sequential tests
configureIsolation({ isolate: true, isolation: 'full' });

`getIsolationConfig()`

Return the current isolation configuration.

function getIsolationConfig(): IsolationConfig;

Serial Execution

`setSerialMode(serial)`

Enable or disable global serial mode. When enabled, all describe() calls automatically use concurrency: 1.

function setSerialMode(serial: boolean): void;

// Force all suites to run sequentially
setSerialMode(true);

describe('Suite A', () => {
  it('test 1', () => { /* ... */ });
  it('test 2', () => { /* ... */ });
});

`getSerialMode()`

Return the current serial mode setting.

function getSerialMode(): boolean;

`describe.serial(name, fn)`

Force a single suite to run sequentially regardless of the global mode. See the Test Suites section above.

Mock Hoisting

Mock hoisting reorders mock.module(), mock.modulePartial(), vi.mock(), and vi.hoisted() calls so they appear before all import declarations in test files. This is necessary for ESM because import bindings are evaluated before any module-level statements execute.

`hoistMocks(source, filename?)`

Transform test source code to hoist mock calls above import declarations.

function hoistMocks(
  source: string,
  filename?: string,
): { code: string; hoisted: boolean };

Parameter	Type	Description
`source`	`string`	The original test file source code
`filename`	`string`	File path (reserved for source-map support)

Returns { code, hoisted } where code is the transformed source and hoisted is true if any calls were moved.

import { hoistMocks } from '@asymmetric-effort/nogginlessdom';

const result = hoistMocks(`
import { myModule } from './my-module';
mock.module('./my-module', () => ({ myModule: () => 42 }));
`);

// result.code has mock.module() before the import
// result.hoisted === true

The implementation is regex-based (no AST parser) to preserve the project's zero-dependency constraint. It correctly handles:

Multi-line mock calls with balanced parentheses
String literals and template literals inside mock calls
Only top-level calls (brace depth 0) are hoisted
Optional const x = vi.hoisted(...) assignments

`registerHoistPlugin(options?)`

function registerHoistPlugin(options?: { filter?: RegExp }): void;

Parameter	Type	Default
`options.filter`	`RegExp`	`/\.(test\	spec)\.(ts\	tsx\	js\	jsx)$/`

import { registerHoistPlugin } from '@asymmetric-effort/nogginlessdom';

registerHoistPlugin();

Or configure in bunfig.toml:

preload = ["@asymmetric-effort/nogginlessdom/hoist"]

Dependency Analysis

Circular Dependencies

Detect circular import chains in your codebase using DFS-based back-edge detection.

`detectCircularImports(entryFiles, options?)`

Find circular import chains starting from the given entry files.

function detectCircularImports(
  entryFiles: string[],
  options?: {
    cwd?: string;
    exclude?: string[];
    maxCycles?: number;
  },
): CircularDependency[];

Parameter	Type	Default
`entryFiles`	`string[]`	(required)
`options.cwd`	`string`	`process.cwd()`
`options.exclude`	`string[]`	`[]`
`options.maxCycles`	`number`	`50`

interface CircularDependency {
  cycle: string[];       // File paths forming the cycle (last === first)
  files: Set<string>;    // Set of all files in the cycle
}

import { detectCircularImports } from '@asymmetric-effort/nogginlessdom';

const cycles = detectCircularImports(['src/index.ts'], {
  exclude: ['node_modules'],
  maxCycles: 10,
});

for (const { cycle } of cycles) {
  console.log('Cycle:', cycle.join(' -> '));
}

Cycles are deduplicated and normalized to start with the lexicographically smallest file path.

`formatCycleReport(cycles)`

Format detected cycles as a human-readable report with arrow-separated paths.

function formatCycleReport(cycles: CircularDependency[]): string;

const report = formatCycleReport(cycles);
console.log(report);
// Found 2 circular dependencies:
//
// src/a.ts -> src/b.ts -> src/a.ts
// src/c.ts -> src/d.ts -> src/e.ts -> src/c.ts

`configureCycleDetection(config)`

Enable cycle detection during test runs.

function configureCycleDetection(config: CycleDetectionConfig): void;

interface CycleDetectionConfig {
  enabled?: boolean;     // Enable detection
  strict?: boolean;      // true = fail test run; false = warn only
  exclude?: string[];    // Glob patterns to skip
  maxCycles?: number;    // Stop after N cycles (default: 50)
}

configureCycleDetection({
  enabled: true,
  strict: true,
  exclude: ['node_modules', 'build'],
  maxCycles: 20,
});

Environment variable: Set DETECT_CYCLES=1 or DETECT_CYCLES=true to enable cycle detection when enabled is not explicitly set.

DETECT_CYCLES=1 bun test

`buildForwardGraph(entryFiles, options?)`

Build a forward dependency graph (file to the set of files it imports). Only relative imports are included; bare specifiers and node: built-ins are skipped.

function buildForwardGraph(
  entryFiles: string[],
  options?: { cwd?: string; exclude?: string[] },
): Map<string, Set<string>>;

Import Depth

Analyze the longest import chain depth for each file in the dependency tree.

`analyzeImportDepth(entryFiles, options?)`

Calculate import depth metrics for a set of entry files.

function analyzeImportDepth(
  entryFiles: string[],
  options?: {
    cwd?: string;
    exclude?: string[];
    threshold?: number;
  },
): DepthAnalysisResult;

interface DepthAnalysis {
  file: string;
  depth: number;
  longestChain: string[];
  directImports: number;
  transitiveImports: number;
}

interface DepthAnalysisResult {
  entries: DepthAnalysis[];
  maxDepth: number;
  averageDepth: number;
  filesExceedingThreshold: DepthAnalysis[];
}

import { analyzeImportDepth } from '@asymmetric-effort/nogginlessdom';

const result = analyzeImportDepth(['src/index.ts'], {
  threshold: 8,
});

console.log('Max depth:', result.maxDepth);
console.log('Average depth:', result.averageDepth);

for (const entry of result.filesExceedingThreshold) {
  console.log(`${entry.file}: depth ${entry.depth}`);
  console.log('  Chain:', entry.longestChain.join(' -> '));
}

`configureDepthCheck(config)`

Enable import depth checking during test runs.

function configureDepthCheck(config: DepthCheckConfig): void;

interface DepthCheckConfig {
  enabled?: boolean;      // Enable depth checking
  threshold?: number;     // Max allowed depth (default: 10)
  strict?: boolean;       // true = fail test run; false = warn only
}

configureDepthCheck({
  enabled: true,
  threshold: 8,
  strict: true,
});

Environment variable: Set IMPORT_DEPTH_THRESHOLD to a number to both enable depth checking and set the threshold.

IMPORT_DEPTH_THRESHOLD=8 bun test

Unused Imports

Detect imported symbols that are never referenced in the file body.

`detectUnusedImports(files, options?)`

Scan files for imports whose symbols are never used.

function detectUnusedImports(
  files: string[],
  options?: {
    cwd?: string;
    exclude?: string[];
    ignoreTypeImports?: boolean;
    ignoreSideEffectImports?: boolean;
  },
): UnusedImport[];

Parameter	Type	Default
`files`	`string[]`	(required)
`options.cwd`	`string`	`process.cwd()`
`options.exclude`	`string[]`	config default
`options.ignoreTypeImports`	`boolean`	`true`
`options.ignoreSideEffectImports`	`boolean`	`true`

interface UnusedImport {
  file: string;
  importSource: string;
  importedSymbols: string[];
  line: number;
  isNamespaceImport: boolean;
  isTypeOnly: boolean;
}

import { detectUnusedImports } from '@asymmetric-effort/nogginlessdom';

const unused = detectUnusedImports(['src/index.ts', 'src/utils.ts']);

for (const entry of unused) {
  console.log(`${entry.file}:${entry.line} - unused: ${entry.importedSymbols.join(', ')}`);
}

The detector handles named imports, default imports, namespace imports (* as ns), aliased imports (a as b), and correctly ignores re-exported symbols. Single-line comments are stripped before checking usage.

Environment variable: Set DETECT_UNUSED_IMPORTS=0 or DETECT_UNUSED_IMPORTS=false to disable detection.

`formatUnusedImportReport(unused)`

Format unused imports as a human-readable report.

function formatUnusedImportReport(unused: UnusedImport[]): string;

const report = formatUnusedImportReport(unused);
console.log(report);

`configureUnusedImportDetection(config)`

Configure unused import detection settings.

function configureUnusedImportDetection(config: UnusedImportConfig): void;

interface UnusedImportConfig {
  enabled?: boolean;                // Enable detection (default: true)
  strict?: boolean;                 // true = fail; false = warn
  ignoreTypeImports?: boolean;      // Skip `import type` (default: true)
  ignoreSideEffectImports?: boolean; // Skip `import './setup'` (default: true)
  exclude?: string[];               // Patterns to skip
}

configureUnusedImportDetection({
  enabled: true,
  strict: false,
  ignoreTypeImports: true,
  exclude: ['generated/'],
});

Graph Visualization

Build and export full dependency graphs in multiple formats.

`buildDependencyGraph(entryFiles, options?)`

Build a complete dependency graph from entry points, including nodes, edges, depth analysis, cycle detection, and summary statistics.

function buildDependencyGraph(
  entryFiles: string[],
  options?: {
    cwd?: string;
    exclude?: string[];
    includeMetadata?: boolean;
    relativePaths?: boolean;
  },
): DependencyGraph;

Parameter	Type	Default
`entryFiles`	`string[]`	(required)
`options.cwd`	`string`	`process.cwd()`
`options.exclude`	`string[]`	`[]`
`options.includeMetadata`	`boolean`	`false`
`options.relativePaths`	`boolean`	`true`

When includeMetadata is true, each node includes lines of code and export count.

interface DependencyGraph {
  version: 1;
  generated: string;
  root: string;
  entryPoints: string[];
  nodes: DependencyNode[];
  edges: DependencyEdge[];
  summary: {
    totalFiles: number;
    totalEdges: number;
    maxDepth: number;
    averageImports: number;
    cycleCount: number;
    leafCount: number;
    hubFiles: string[];    // Top 5 most-imported files
  };
}

interface DependencyNode {
  id: string;
  imports: string[];
  importedBy: string[];
  depth: number;
  directImportCount: number;
  transitiveImportCount: number;
  isEntryPoint: boolean;
  isLeaf: boolean;
  inCycle: boolean;
  metadata?: { loc?: number; exportCount?: number };
}

interface DependencyEdge {
  from: string;
  to: string;
  type: 'static' | 'dynamic';
  symbols?: string[];
}

import { buildDependencyGraph } from '@asymmetric-effort/nogginlessdom';

const graph = buildDependencyGraph(['src/index.ts'], {
  includeMetadata: true,
  exclude: ['node_modules'],
});

console.log('Total files:', graph.summary.totalFiles);
console.log('Max depth:', graph.summary.maxDepth);
console.log('Cycles:', graph.summary.cycleCount);
console.log('Hub files:', graph.summary.hubFiles);

Environment variable: Set EXPORT_DEPENDENCY_GRAPH=0 or EXPORT_DEPENDENCY_GRAPH=false to return an empty graph.

`exportGraphJSON(graph, pretty?)`

Serialize a DependencyGraph to a JSON string.

function exportGraphJSON(graph: DependencyGraph, pretty?: boolean): string;

const json = exportGraphJSON(graph, true);
fs.writeFileSync('deps.json', json);

`exportGraphDOT(graph)`

Convert a DependencyGraph to Graphviz DOT format.

function exportGraphDOT(graph: DependencyGraph): string;

const dot = exportGraphDOT(graph);
// digraph dependencies {
//   rankdir=LR;
//   "src/a.ts" -> "src/b.ts";
//   ...
// }

`exportGraphMermaid(graph)`

Convert a DependencyGraph to Mermaid flowchart format.

function exportGraphMermaid(graph: DependencyGraph): string;

const mermaid = exportGraphMermaid(graph);
// graph LR
//   src_a.ts["src/a.ts"] --> src_b.ts["src/b.ts"]
//   ...

`saveGraph(entryFiles, outputPath, options?)`

Build a dependency graph and write it to disk. The output format is auto-detected from the file extension (.json, .dot, .mmd/.mermaid) or can be specified explicitly.

function saveGraph(
  entryFiles: string[],
  outputPath: string,
  options?: {
    format?: 'json' | 'dot' | 'mermaid';
    pretty?: boolean;
    cwd?: string;
    exclude?: string[];
  },
): void;

import { saveGraph } from '@asymmetric-effort/nogginlessdom';

// Auto-detect format from extension
saveGraph(['src/index.ts'], 'deps.json', { pretty: true });
saveGraph(['src/index.ts'], 'deps.dot');
saveGraph(['src/index.ts'], 'deps.mmd');

// Explicit format
saveGraph(['src/index.ts'], 'output.txt', { format: 'mermaid' });

The output directory is created recursively if it does not exist.

Type Definitions

type TestFn = (...args: unknown[]) => void | Promise<void>;
type SuiteFn = (...args: unknown[]) => void | Promise<void>;

interface TestOptions {
  skip?: boolean | string;
  only?: boolean;
  todo?: boolean | string;
  timeout?: number;
  retries?: number;
}

Mapping to node:test

NogginLessDom	node:test	Notes
`describe`	`describe`	Direct delegation
`describe.skip`	`describe`	With `{ skip: true }` option
`describe.only`	`describe`	With `{ only: true }` option
`describe.todo`	`describe`	With `{ todo: true }` option
`describe.concurrent`	`describe`	With `{ concurrency: true }` option
`describe.serial`	`describe`	With `{ concurrency: 1 }` option
`it`	`it`	Options object mapped
`test`	`it`	Alias for `it`
`it.skip`	`it`	With `{ skip: true }` option
`it.only`	`it`	With `{ only: true }` option
`it.todo`	`it`	With `{ todo: true }` option
`it.concurrent`	`it`	With `{ concurrency: true }` option
`it.fails`	`it`	Wrapped to invert pass/fail
`it.retry`	`it`	Wrapped with retry loop
`beforeEach`	`beforeEach`	Direct delegation
`afterEach`	`afterEach`	Direct delegation
`beforeAll`	`before`	Conventional naming
`afterAll`	`after`	Conventional naming

Assertions API Reference

The assertions module wraps Node.js's built-in node:assert/strict module to provide a full-featured expect() API with 40+ chainable matchers, asymmetric matchers, assertion tracking, snapshot testing, custom matchers, and error diffs.

import { expect } from '@asymmetric-effort/nogginlessdom';

Overview

All assertions start with expect(actual) and chain a matcher method. Every matcher tracks the assertion count for expect.assertions() and expect.hasAssertions() verification.

expect(actual).toBe(expected);
expect(actual).not.toBe(unexpected);
await expect(promise).resolves.toBe(value);
await expect(promise).rejects.toThrow('error');

Equality

`.toBe(expected)`

Assert strict reference equality (===). Use for primitives and identity checks.

toBe(expected: T): void

expect(1 + 1).toBe(2);
expect('hello').toBe('hello');
expect(true).toBe(true);

const obj = { a: 1 };
expect(obj).toBe(obj); // same reference

Negated:

expect(1).not.toBe(2);

Maps to assert.strictEqual / assert.notStrictEqual.

`.toEqual(expected)`

Assert deep equality. Recursively compares all properties of objects and arrays. Supports asymmetric matchers within the expected value. On failure, produces a colored diff of expected vs received.

toEqual(expected: T): void

expect({ a: 1, b: [2, 3] }).toEqual({ a: 1, b: [2, 3] });
expect([1, 2, 3]).toEqual([1, 2, 3]);

// With asymmetric matchers
expect({ name: 'Alice', age: 30 }).toEqual({
  name: expect.any(String),
  age: expect.any(Number),
});

Negated:

expect({ a: 1 }).not.toEqual({ a: 2 });

Maps to assert.deepStrictEqual / assert.notDeepStrictEqual.

`.toStrictEqual(expected)`

Assert strict deep equality. Like toEqual, but checks prototype chains and does not allow undefined-valued properties to match missing properties. Produces a colored diff on failure.

toStrictEqual(expected: T): void

class Point {
  constructor(public x: number, public y: number) {}
}

expect(new Point(1, 2)).toStrictEqual(new Point(1, 2));

Negated:

expect(new Point(1, 2)).not.toStrictEqual({ x: 1, y: 2 });

Maps to assert.deepStrictEqual / assert.notDeepStrictEqual.

Truthiness

`.toBeTruthy()`

Assert the value is truthy (not false, 0, "", null, undefined, or NaN).

toBeTruthy(): void

expect(1).toBeTruthy();
expect('non-empty').toBeTruthy();
expect([]).toBeTruthy(); // arrays are truthy

Negated:

expect(0).not.toBeTruthy();

`.toBeFalsy()`

Assert the value is falsy.

toBeFalsy(): void

expect(0).toBeFalsy();
expect('').toBeFalsy();
expect(null).toBeFalsy();

Negated:

expect(1).not.toBeFalsy();

`.toBeNull()`

Assert the value is exactly null.

toBeNull(): void

expect(null).toBeNull();

Negated:

expect(undefined).not.toBeNull();

Maps to assert.strictEqual(actual, null).

`.toBeUndefined()`

Assert the value is exactly undefined.

toBeUndefined(): void

expect(undefined).toBeUndefined();
const obj: Record<string, unknown> = {};
expect(obj.missing).toBeUndefined();

Negated:

expect(42).not.toBeUndefined();

Maps to assert.strictEqual(actual, undefined).

`.toBeDefined()`

Assert the value is not undefined. Note: null is considered defined.

toBeDefined(): void

expect(null).toBeDefined();
expect(42).toBeDefined();

Negated:

expect(undefined).not.toBeDefined();

Maps to assert.notStrictEqual(actual, undefined).

`.toBeNaN()`

Assert the value is NaN. Uses Number.isNaN().

toBeNaN(): void

expect(NaN).toBeNaN();
expect(parseInt('not a number')).toBeNaN();

Negated:

expect(42).not.toBeNaN();

Type

`.toBeInstanceOf(constructor)`

Assert the value is an instance of the given constructor.

toBeInstanceOf(expected: abstract new (...args: unknown[]) => unknown): void

expect(new Date()).toBeInstanceOf(Date);
expect(new Error('fail')).toBeInstanceOf(Error);
expect([1, 2, 3]).toBeInstanceOf(Array);

Negated:

expect('hello').not.toBeInstanceOf(Number);

`.toBeTypeOf(type)`

Assert that typeof actual matches the given type string.

toBeTypeOf(type: string): void

Valid types: 'string', 'number', 'boolean', 'function', 'object', 'undefined', 'symbol', 'bigint'.

expect('hello').toBeTypeOf('string');
expect(42).toBeTypeOf('number');
expect(true).toBeTypeOf('boolean');
expect(() => {}).toBeTypeOf('function');
expect(null).toBeTypeOf('object');
expect(Symbol()).toBeTypeOf('symbol');
expect(BigInt(42)).toBeTypeOf('bigint');

Negated:

expect('hello').not.toBeTypeOf('number');

Throws if the type string is not one of the valid types.

Numbers

`.toBeGreaterThan(number)`

Assert the value is greater than the given number.

toBeGreaterThan(expected: number): void

expect(10).toBeGreaterThan(5);

Negated:

expect(5).not.toBeGreaterThan(10);

`.toBeGreaterThanOrEqual(number)`

Assert the value is greater than or equal to the given number.

toBeGreaterThanOrEqual(expected: number): void

expect(10).toBeGreaterThanOrEqual(10);
expect(11).toBeGreaterThanOrEqual(10);

Negated:

expect(9).not.toBeGreaterThanOrEqual(10);

`.toBeLessThan(number)`

Assert the value is less than the given number.

toBeLessThan(expected: number): void

expect(5).toBeLessThan(10);

Negated:

expect(10).not.toBeLessThan(5);

`.toBeLessThanOrEqual(number)`

Assert the value is less than or equal to the given number.

toBeLessThanOrEqual(expected: number): void

expect(10).toBeLessThanOrEqual(10);
expect(9).toBeLessThanOrEqual(10);

Negated:

expect(11).not.toBeLessThanOrEqual(10);

`.toBeCloseTo(number, precision?)`

Assert a floating-point number is close to the expected value. The default precision is 2, meaning numbers must differ by less than 0.5 * 10^-2 (0.005).

toBeCloseTo(expected: number, precision?: number): void

expect(0.1 + 0.2).toBeCloseTo(0.3);
expect(1.005).toBeCloseTo(1.0, 2);
expect(Math.PI).toBeCloseTo(3.14159, 4);

Negated:

expect(0.1 + 0.2).not.toBeCloseTo(0.4);

`.toBeWithin(start, end)`

Assert a number is within the half-open range [start, end).

toBeWithin(start: number, end: number): void

expect(5).toBeWithin(1, 10);
expect(1).toBeWithin(1, 10);   // inclusive start

Negated:

expect(10).not.toBeWithin(1, 10); // exclusive end

Strings

`.toMatch(pattern)`

Assert a string matches a regular expression or contains a substring.

toMatch(expected: string | RegExp): void

expect('hello world').toMatch(/hello/);
expect('hello world').toMatch('world');
expect('2024-01-15').toMatch(/\d{4}-\d{2}-\d{2}/);

Negated:

expect('hello').not.toMatch('goodbye');
expect('hello').not.toMatch(/\d+/);

Collections

`.toContain(item)`

Assert an array includes the given item (strict equality) or a string contains the given substring.

toContain(expected: unknown): void

expect([1, 2, 3]).toContain(2);
expect('hello world').toContain('world');

Negated:

expect([1, 2, 3]).not.toContain(4);

`.toContainEqual(expected)`

Assert an array contains an element that is deeply equal to the expected value. Supports asymmetric matchers.

toContainEqual(expected: unknown): void

expect([{ a: 1 }, { b: 2 }]).toContainEqual({ a: 1 });
expect([{ name: 'Alice' }]).toContainEqual(
  expect.objectContaining({ name: 'Alice' }),
);

Negated:

expect([{ a: 1 }]).not.toContainEqual({ a: 2 });

`.toHaveLength(length)`

Assert an array, string, or any object with a .length property has the given length.

toHaveLength(expected: number): void

expect([1, 2, 3]).toHaveLength(3);
expect('hello').toHaveLength(5);
expect([]).toHaveLength(0);

Negated:

expect([1, 2]).not.toHaveLength(3);

`.toHaveProperty(key, value?)`

Assert an object has the given property. Optionally check the property's value using deep equality.

toHaveProperty(key: string, value?: unknown): void

const user = { name: 'Alice', address: { city: 'Portland' } };

expect(user).toHaveProperty('name');
expect(user).toHaveProperty('name', 'Alice');
expect(user).toHaveProperty('address');

Negated:

expect(user).not.toHaveProperty('age');

`.toBeEmpty()`

Assert a value is empty. Works with strings, arrays, Maps, Sets, and plain objects.

toBeEmpty(): void

expect('').toBeEmpty();
expect([]).toBeEmpty();
expect(new Map()).toBeEmpty();
expect(new Set()).toBeEmpty();
expect({}).toBeEmpty();

Negated:

expect([1]).not.toBeEmpty();

`.toContainAllEntries(entries)`

Assert an object or Map contains all the specified [key, value] entries. Values are compared using deep equality with asymmetric matcher support.

toContainAllEntries(entries: [string, unknown][]): void

expect({ a: 1, b: 2, c: 3 }).toContainAllEntries([
  ['a', 1],
  ['b', 2],
]);

const map = new Map([['x', 10], ['y', 20]]);
expect(map).toContainAllEntries([['x', 10], ['y', 20]]);

Negated:

expect({ a: 1 }).not.toContainAllEntries([['a', 1], ['b', 2]]);

`.toContainAnyEntries(entries)`

Assert an object or Map contains at least one of the specified [key, value] entries.

toContainAnyEntries(entries: [string, unknown][]): void

expect({ a: 1, b: 2 }).toContainAnyEntries([
  ['a', 1],
  ['c', 3],
]);

Negated:

expect({ a: 1 }).not.toContainAnyEntries([['b', 2], ['c', 3]]);

Objects

`.toMatchObject(expected)`

Assert that an object contains all the key-value pairs in expected (partial matching). Extra keys in actual are allowed. Supports nested objects and asymmetric matchers. Produces a diff on failure.

toMatchObject(expected: Record<string, unknown> | unknown[]): void

expect({ a: 1, b: 2, c: 3 }).toMatchObject({ a: 1, b: 2 });
expect({ user: { name: 'Alice', age: 30 } }).toMatchObject({
  user: { name: 'Alice' },
});

Negated:

expect({ a: 1, b: 2 }).not.toMatchObject({ a: 1, b: 3 });

`.toSatisfy(predicate)`

Assert the value satisfies a custom predicate function.

toSatisfy(predicate: (value: unknown) => boolean): void

expect(42).toSatisfy((n) => n > 0 && n < 100);
expect('hello').toSatisfy((s) => s.startsWith('h'));

Negated:

expect(-1).not.toSatisfy((n) => n > 0);

`.toSatisfyAll(predicate)`

Assert that every element in an array satisfies the predicate.

toSatisfyAll(predicate: (value: unknown) => boolean): void

expect([2, 4, 6]).toSatisfyAll((n) => n % 2 === 0);

Negated:

expect([1, 2, 3]).not.toSatisfyAll((n) => n % 2 === 0);

`.toBeOneOf(values)`

Assert the value is strictly equal to one of the values in the array.

toBeOneOf(values: unknown[]): void

expect('active').toBeOneOf(['active', 'inactive', 'pending']);
expect(1).toBeOneOf([1, 2, 3]);

Negated:

expect('deleted').not.toBeOneOf(['active', 'inactive']);

Functions and Errors

`.toThrow(expected?)`

Assert that a function throws an error. Optionally match the error message (string or RegExp) or error object.

toThrow(expected?: string | RegExp | Error): void

// Any throw
expect(() => { throw new Error('oops'); }).toThrow();

// By message substring
expect(() => { throw new Error('not found'); }).toThrow('not found');

// By regex
expect(() => {
  throw new Error('Connection refused at port 8080');
}).toThrow(/port \d+/);

// By error object
expect(() => {
  throw new TypeError('bad type');
}).toThrow(new TypeError('bad type'));

Negated:

expect(() => {}).not.toThrow();
expect(() => { throw new Error('oops'); }).not.toThrow('different message');

Maps to assert.throws / assert.doesNotThrow.

`.toThrowWithMessage(ErrorType, message)`

Assert that a function throws an error that is an instance of ErrorType and whose message matches the given string (substring) or RegExp.

toThrowWithMessage(
  ErrorType: new (...args: unknown[]) => Error,
  message: string | RegExp,
): void

expect(() => {
  throw new TypeError('invalid argument');
}).toThrowWithMessage(TypeError, 'invalid argument');

expect(() => {
  throw new RangeError('out of bounds');
}).toThrowWithMessage(RangeError, /out of/);

Negated:

expect(() => {
  throw new TypeError('invalid');
}).not.toThrowWithMessage(RangeError, 'invalid');

Mock Matchers

These matchers work with mock functions created by fn() or spyOn(). They read from the .mock property on the function.

`.toHaveBeenCalled()`

Assert the mock was called at least once.

toHaveBeenCalled(): void

const mockFn = fn();
mockFn();
expect(mockFn).toHaveBeenCalled();

Negated:

const mockFn = fn();
expect(mockFn).not.toHaveBeenCalled();

`.toHaveBeenCalledTimes(n)`

Assert the mock was called exactly n times.

toHaveBeenCalledTimes(n: number): void

const mockFn = fn();
mockFn();
mockFn();
expect(mockFn).toHaveBeenCalledTimes(2);

Negated:

expect(mockFn).not.toHaveBeenCalledTimes(3);

`.toHaveBeenCalledWith(...args)`

Assert the mock was called at least once with the specified arguments. Uses deep equality with asymmetric matcher support.

toHaveBeenCalledWith(...args: unknown[]): void

const mockFn = fn();
mockFn('hello', 42);
expect(mockFn).toHaveBeenCalledWith('hello', 42);
expect(mockFn).toHaveBeenCalledWith(expect.any(String), expect.any(Number));

Negated:

expect(mockFn).not.toHaveBeenCalledWith('goodbye', 0);

`.toHaveBeenLastCalledWith(...args)`

Assert the most recent call to the mock used the specified arguments.

toHaveBeenLastCalledWith(...args: unknown[]): void

const mockFn = fn();
mockFn('first');
mockFn('second');
expect(mockFn).toHaveBeenLastCalledWith('second');

Negated:

expect(mockFn).not.toHaveBeenLastCalledWith('first');

`.toHaveBeenNthCalledWith(n, ...args)`

Assert the nth call (1-indexed) to the mock used the specified arguments.

toHaveBeenNthCalledWith(n: number, ...args: unknown[]): void

const mockFn = fn();
mockFn('a');
mockFn('b');
mockFn('c');
expect(mockFn).toHaveBeenNthCalledWith(2, 'b');

Negated:

expect(mockFn).not.toHaveBeenNthCalledWith(1, 'b');

`.toHaveBeenCalledOnce()`

Assert the mock was called exactly once. Convenience for toHaveBeenCalledTimes(1).

toHaveBeenCalledOnce(): void

const mockFn = fn();
mockFn();
expect(mockFn).toHaveBeenCalledOnce();

Negated:

const mockFn = fn();
mockFn();
mockFn();
expect(mockFn).not.toHaveBeenCalledOnce();

`.toHaveReturned()`

Assert the mock successfully returned (did not throw) at least once.

toHaveReturned(): void

const mockFn = fn(() => 42);
mockFn();
expect(mockFn).toHaveReturned();

Negated:

expect(throwingMock).not.toHaveReturned();

`.toHaveReturnedTimes(n)`

Assert the mock successfully returned exactly n times.

toHaveReturnedTimes(n: number): void

const mockFn = fn(() => 'ok');
mockFn();
mockFn();
expect(mockFn).toHaveReturnedTimes(2);

Negated:

expect(mockFn).not.toHaveReturnedTimes(3);

`.toHaveReturnedWith(value)`

Assert the mock returned the specified value at least once. Uses deep equality with asymmetric matcher support.

toHaveReturnedWith(value: unknown): void

const mockFn = fn(() => 42);
mockFn();
expect(mockFn).toHaveReturnedWith(42);

Negated:

expect(mockFn).not.toHaveReturnedWith(99);

`.toHaveLastReturnedWith(value)`

Assert the most recent return value from the mock matches the specified value.

toHaveLastReturnedWith(value: unknown): void

const mockFn = fn();
mockFn.mockReturnValueOnce(1).mockReturnValueOnce(2);
mockFn();
mockFn();
expect(mockFn).toHaveLastReturnedWith(2);

Negated:

expect(mockFn).not.toHaveLastReturnedWith(1);

`.toHaveNthReturnedWith(n, value)`

Assert the nth call (1-indexed) returned the specified value.

toHaveNthReturnedWith(n: number, value: unknown): void

const mockFn = fn();
mockFn.mockReturnValueOnce('a').mockReturnValueOnce('b');
mockFn();
mockFn();
expect(mockFn).toHaveNthReturnedWith(1, 'a');
expect(mockFn).toHaveNthReturnedWith(2, 'b');

Negated:

expect(mockFn).not.toHaveNthReturnedWith(1, 'b');

Negation

`.not`

Invert any matcher. Can be chained before any matcher method.

expect(1).not.toBe(2);
expect('hello').not.toContain('goodbye');
expect([1, 2]).not.toHaveLength(3);
expect(null).not.toBeUndefined();
expect(() => {}).not.toThrow();
expect({ a: 1 }).not.toEqual({ b: 2 });

Toggling .not flips the negation state, so .not.not is a double negation that behaves like no negation at all.

Async

`.resolves`

Unwrap a resolved promise before applying the matcher. The test function must be async and you must await the assertion.

it('resolves with a value', async () => {
  await expect(Promise.resolve(42)).resolves.toBe(42);
  await expect(fetchUser(1)).resolves.toHaveProperty('name');
});

If the promise rejects, the assertion fails with an error message indicating the unexpected rejection.

Available matchers on .resolves: toBe, toEqual, toStrictEqual, toBeTruthy, toBeFalsy, toBeNull, toBeUndefined, toBeDefined, toBeNaN, toBeInstanceOf, toContain, toHaveLength, toHaveProperty, toMatch, toThrow, toBeGreaterThan, toBeGreaterThanOrEqual, toBeLessThan, toBeLessThanOrEqual, toBeCloseTo.

.resolves.not is also supported:

await expect(Promise.resolve(42)).resolves.not.toBe(0);

`.rejects`

Assert that a promise rejects, then apply matchers to the rejection reason.

it('rejects with an error', async () => {
  await expect(Promise.reject(new Error('fail'))).rejects.toThrow('fail');
  await expect(failingFetch()).rejects.toBeInstanceOf(Error);
});

If the promise resolves, the assertion fails with an error message indicating the unexpected resolution.

.rejects.not is also supported:

await expect(Promise.reject(new Error('x'))).rejects.not.toThrow('y');

Asymmetric Matchers

Asymmetric matchers can be used inside toEqual, toHaveBeenCalledWith, toContainEqual, and other matchers that perform deep comparison. They implement an asymmetricMatch(actual) method.

`expect.anything()`

Matches anything except null and undefined.

expect({ a: 1 }).toEqual({ a: expect.anything() });
expect(mockFn).toHaveBeenCalledWith(expect.anything());

`expect.any(constructor)`

Matches values that are instances of the given constructor. For primitive wrappers (String, Number, Boolean, BigInt, Symbol, Function), matches the corresponding typeof check instead.

expect({ id: 1, name: 'Alice' }).toEqual({
  id: expect.any(Number),
  name: expect.any(String),
});
expect(true).toEqual(expect.any(Boolean));
expect(() => {}).toEqual(expect.any(Function));
expect(new Date()).toEqual(expect.any(Date));

`expect.stringContaining(string)`

Matches strings that contain the specified substring.

expect({ message: 'hello world' }).toEqual({
  message: expect.stringContaining('world'),
});

`expect.stringMatching(pattern)`

Matches strings that match the given string or regular expression.

expect({ email: 'alice@example.com' }).toEqual({
  email: expect.stringMatching(/@example\.com$/),
});

`expect.objectContaining(object)`

Matches objects that contain at least the specified key-value pairs. Supports nested asymmetric matchers.

expect(mockFn).toHaveBeenCalledWith(
  expect.objectContaining({ type: 'click' }),
);

`expect.arrayContaining(array)`

Matches arrays that contain all elements in the specified array (order does not matter). Each element is compared using deep equality.

expect([1, 2, 3, 4]).toEqual(expect.arrayContaining([3, 1]));

`expect.not.objectContaining(object)`

Matches objects that do NOT contain all the specified key-value pairs.

expect({ a: 1, b: 2 }).toEqual(
  expect.not.objectContaining({ c: 3 }),
);

`expect.not.arrayContaining(array)`

Matches arrays that do NOT contain all the specified elements.

expect([1, 2, 3]).toEqual(expect.not.arrayContaining([4, 5]));

`expect.not.stringContaining(string)`

Matches strings that do NOT contain the specified substring.

expect({ msg: 'hello' }).toEqual({
  msg: expect.not.stringContaining('goodbye'),
});

`expect.not.stringMatching(pattern)`

Matches strings that do NOT match the given pattern.

expect({ code: 'ABC' }).toEqual({
  code: expect.not.stringMatching(/\d+/),
});

Custom Matchers

`expect.extend(matchers)`

Register custom matchers. Each matcher function receives the actual value as its first argument and any additional arguments from the call. It must return { pass: boolean, message: () => string }.

expect.extend(matchers: Record<string, CustomMatcherFn>): void

type CustomMatcherFn = (
  received: unknown,
  ...args: unknown[],
) => { pass: boolean; message: () => string };

expect.extend({
  toBeEven(received: number) {
    const pass = received % 2 === 0;
    return {
      pass,
      message: () =>
        `Expected ${received} ${pass ? 'not ' : ''}to be even`,
    };
  },
  toBeWithinRange(received: number, floor: number, ceiling: number) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        `Expected ${received} ${pass ? 'not ' : ''}to be within [${floor}, ${ceiling}]`,
    };
  },
});

expect(4).toBeEven();
expect(3).not.toBeEven();
expect(50).toBeWithinRange(1, 100);

Custom matchers respect .not negation automatically.

Assertion Tracking

`expect.assertions(count)`

Declare that exactly count assertions must be called during the current test. Useful for verifying assertions inside callbacks or conditional branches actually execute.

expect.assertions(count: number): void

it('calls both callbacks', () => {
  expect.assertions(2);
  forEach([1, 2], (item) => {
    expect(item).toBeGreaterThan(0);
  });
});

If the actual count differs, expect.verifyAssertions() throws.

`expect.hasAssertions()`

Declare that at least one assertion must run during the current test.

expect.hasAssertions(): void

it('makes at least one assertion', async () => {
  expect.hasAssertions();
  const data = await fetchData();
  if (data.length > 0) {
    expect(data[0]).toBeDefined();
  }
});

`expect.getState()`

Return the current assertion tracking state.

expect.getState(): {
  assertionCount: number;
  expectedAssertionCount: number | null;
  isExpectingAssertions: boolean;
}

`expect.resetState()`

Reset the assertion counter and expected counts. Call at the start of each test for clean tracking.

expect.resetState(): void

`expect.verifyAssertions()`

Verify that assertion count expectations are met. Throws if expect.assertions(n) was called and the count does not match, or if expect.hasAssertions() was called and no assertions ran. Call at the end of each test.

expect.verifyAssertions(): void

Snapshot Testing

`.toMatchSnapshot(snapshotName?, hint?, propertyMatchers?)`

Compare the value against a stored snapshot. On first run, the snapshot is created. On subsequent runs, the value is compared. Negation is not supported.

toMatchSnapshot(
  snapshotName?: string,
  hint?: string,
  propertyMatchers?: Record<string, unknown>,
): void

expect({ name: 'Alice', items: [1, 2, 3] }).toMatchSnapshot();
expect(data).toMatchSnapshot('user data');

`.toMatchInlineSnapshot(inlineSnapshot?)`

Compare the value against an inline snapshot embedded in the test source file. On first run, the snapshot string is written into the test file.

toMatchInlineSnapshot(inlineSnapshot?: string): void

expect({ greeting: 'hello' }).toMatchInlineSnapshot();

`.toMatchFileSnapshot(filePath)`

Compare the value against a snapshot stored in a separate file.

toMatchFileSnapshot(filePath: string): void

expect(generatedOutput).toMatchFileSnapshot('./fixtures/expected-output.txt');

`.toThrowErrorMatchingSnapshot()`

Assert the function throws, then compare the error message against a stored snapshot.

toThrowErrorMatchingSnapshot(): void

expect(() => {
  throw new Error('specific error message');
}).toThrowErrorMatchingSnapshot();

`.toThrowErrorMatchingInlineSnapshot(snapshot?)`

Assert the function throws, then compare the error message against an inline snapshot.

toThrowErrorMatchingInlineSnapshot(snapshot?: string): void

expect(() => {
  throw new Error('something went wrong');
}).toThrowErrorMatchingInlineSnapshot();

Snapshot Auto-Update

Snapshots can be automatically updated when the actual value changes. Use setUpdateMode('all') to update all snapshots during a test run, or setUpdateMode('new') to only create new snapshots without updating existing ones.

import { setUpdateMode, getUpdateMode } from '@asymmetric-effort/nogginlessdom';

setUpdateMode('all');   // Update all snapshots
setUpdateMode('new');   // Only create new, don't update existing
setUpdateMode('none');  // Default: never auto-update

Snapshot Serializers

`expect.addSnapshotSerializer(serializer)`

expect.addSnapshotSerializer(serializer: SnapshotSerializer): void

interface SnapshotSerializer {
  test(value: unknown): boolean;
  serialize(
    value: unknown,
    config: SerializeConfig,
    indentation: string,
    depth: number,
    refs: Set<unknown>,
    printer: PrinterFn,
  ): string;
}

interface SerializeConfig {
  indent?: number;
  maxDepth?: number;
  min?: boolean;
  printBasicPrototype?: boolean;
}

expect.addSnapshotSerializer({
  test(val: unknown): boolean {
    return val instanceof Date;
  },
  serialize(val: unknown): string {
    return `Date(${(val as Date).toISOString()})`;
  },
});

// Now snapshots of Date objects use custom formatting
expect(new Date('2024-01-15')).toMatchSnapshot();

The printer parameter allows recursively serializing nested values through the standard serialization pipeline:

expect.addSnapshotSerializer({
  test(val) {
    return val instanceof MyClass;
  },
  serialize(val, config, indentation, depth, refs, printer) {
    const obj = val as MyClass;
    return `MyClass(${printer(obj.data, config, indentation, depth + 1, refs)})`;
  },
});

Error Diffs

The diff engine produces colored, human-readable diffs for assertion errors.

`objectDiff(expected, received, options?)`

Produce a diff between two objects, arrays, or primitives. Shows - Expected (green) / + Received (red) format with nested key-level granularity.

function objectDiff(
  expected: unknown,
  received: unknown,
  options?: DiffOptions,
): string;

import { objectDiff } from '@asymmetric-effort/nogginlessdom';

const diff = objectDiff(
  { a: 1, b: 2 },
  { a: 1, b: 3, c: 4 },
);
console.log(diff);
//   b:
//     - Expected: 2
//     + Received: 3
//   + c: 4

`stringDiff(expected, received, options?)`

Produce a diff between two strings. Multi-line strings use line-by-line comparison. Single-line strings show expected vs received with a caret at the first difference.

function stringDiff(
  expected: string,
  received: string,
  options?: DiffOptions,
): string;

import { stringDiff } from '@asymmetric-effort/nogginlessdom';

const diff = stringDiff('hello world', 'hello earth');
console.log(diff);

`formatExpectedReceived(expected, received, options?)`

Automatically choose the best diff format based on the types of the values. Uses stringDiff for two strings, objectDiff for objects, and a simple expected/received display for primitives.

function formatExpectedReceived(
  expected: unknown,
  received: unknown,
  options?: DiffOptions,
): string;

`configureDiff(options)`

Set global diff configuration that applies to all assertion error messages.

function configureDiff(options: DiffOptions): void;

interface DiffOptions {
  maxLength?: number;  // Max string length before truncation (default: 1000)
  colorize?: boolean;  // Force color on/off (default: TTY detection)
}

import { configureDiff } from '@asymmetric-effort/nogginlessdom';

configureDiff({ maxLength: 500, colorize: false });

`getDiffConfig()`

Return the current global diff configuration.

function getDiffConfig(): DiffOptions;

ANSI Helpers

Utility functions for colored output, respecting TTY detection:

function green(s: string): string;  // Green text
function red(s: string): string;    // Red text
function dim(s: string): string;    // Dimmed text
function bold(s: string): string;   // Bold text
function stripAnsi(s: string): string;  // Remove all ANSI codes

DOM Simulation API Reference

NogginLessDom provides a complete, zero-dependency DOM simulation for testing web applications without a browser. Every class and function described here is available from the top-level package import.

import {
  Document, Element, Node, TextNode, Comment, DocumentFragment,
  Event, createWindow,
} from '@asymmetric-effort/nogginlessdom';

Core Classes

Node

Base class for all DOM nodes. Provides tree manipulation, traversal, and comparison methods.

Node Type Constants

Constant	Value
`Node.ELEMENT_NODE`	1
`Node.TEXT_NODE`	3
`Node.COMMENT_NODE`	8
`Node.DOCUMENT_NODE`	9
`Node.DOCUMENT_FRAGMENT_NODE`	11

Document Position Constants

Constant	Value
`Node.DOCUMENT_POSITION_DISCONNECTED`	1
`Node.DOCUMENT_POSITION_PRECEDING`	2
`Node.DOCUMENT_POSITION_FOLLOWING`	4
`Node.DOCUMENT_POSITION_CONTAINS`	8
`Node.DOCUMENT_POSITION_CONTAINED_BY`	16

Properties

Property	Type	Description
`nodeType`	`number`	The node type constant
`nodeName`	`string`	The node name (`#text`, `#comment`, tag name, etc.)
`childNodes`	`Node[]`	Direct child nodes
`parentNode`	`Node \	null`	Parent node
`parentElement`	`Element \	null`	Parent element (null if parent is not an Element)
`ownerDocument`	`Document \	null`	The owning document
`isConnected`	`boolean`	True if the node is in a document tree
`nodeValue`	`string \	null`	Node value (null for non-text nodes)
`textContent`	`string`	Text content of the node and all descendants
`firstChild`	`Node \	null`	First child node
`lastChild`	`Node \	null`	Last child node
`nextSibling`	`Node \	null`	Next sibling node
`previousSibling`	`Node \	null`	Previous sibling node

Methods

appendChild(child: Node): Node -- Appends a child node. Removes the child from its current parent if it has one. Fires connectedCallback on custom elements.

const div = document.createElement('div');
const span = document.createElement('span');
div.appendChild(span);

removeChild(child: Node): Node -- Removes a child node. Throws if the node is not a child. Fires disconnectedCallback on custom elements.

insertBefore(newChild: Node, referenceChild: Node | null): Node -- Inserts a node before a reference child. If referenceChild is null, appends to the end.

replaceChild(newChild: Node, oldChild: Node): Node -- Replaces an existing child with a new node.

contains(other: Node): boolean -- Returns true if other is a descendant of this node (or is this node itself).

hasChildNodes(): boolean -- Returns true if the node has children.

cloneNode(deep?: boolean): Node -- Creates a copy. If deep is true, clones all descendants.

normalize(): void -- Merges adjacent text nodes and removes empty text nodes.

isEqualNode(other: Node | null): boolean -- Deep-compares two nodes for structural equality.

isSameNode(other: Node | null): boolean -- Returns true if both references point to the same node.

compareDocumentPosition(other: Node): number -- Returns a bitmask describing the position of other relative to this node.

Element

Extends Node. Represents an HTML or SVG element with attributes, styling, events, and DOM manipulation capabilities.

Constructor

new Element(tagName: string, namespaceURI?: string | null)

Tag names are uppercased for HTML, preserved for SVG.

Properties

Property	Type	Description
`tagName`	`string`	Uppercase tag name (e.g. `'DIV'`)
`id`	`string`	The element's ID
`className`	`string`	Space-separated class names
`namespaceURI`	`string \	null`	Namespace URI
`innerHTML`	`string`	HTML content of the element
`outerHTML`	`string` (read-only)	HTML including the element itself
`classList`	`DOMTokenList`	Token list for class manipulation
`style`	`CSSStyleDeclaration`	Inline style object
`dataset`	`DOMStringMap`	Data attribute access via `data-*`
`children`	`HTMLCollection`	Child elements (not text/comment nodes)
`childElementCount`	`number`	Number of child elements
`firstElementChild`	`Element \	null`	First child element
`lastElementChild`	`Element \	null`	Last child element
`nextElementSibling`	`Element \	null`	Next sibling element
`previousElementSibling`	`Element \	null`	Previous sibling element
`shadowRoot`	`ShadowRoot \	null`	Open shadow root, or null
`slot`	`string`	Slot name for shadow DOM distribution
`assignedSlot`	`Element \	null`	The slot element this is assigned to
`tabIndex`	`number`	Tab order (0 for interactive elements, -1 otherwise)
`contentEditable`	`string`	`'true'`, `'false'`, or `'inherit'`
`isContentEditable`	`boolean`	Resolved editability

Attribute Methods

element.setAttribute('href', '/page');
element.getAttribute('href');        // '/page'
element.hasAttribute('href');        // true
element.removeAttribute('href');
element.toggleAttribute('disabled'); // toggles presence
element.getAttributeNames();         // ['class', 'id', ...]
element.hasAttributes();             // true if any attributes exist

// Namespaced variants
element.setAttributeNS(ns, name, value);
element.getAttributeNS(ns, name);
element.removeAttributeNS(ns, name);
element.hasAttributeNS(ns, name);

Query Methods

element.querySelector('.active');             // first match or null
element.querySelectorAll('li.item');          // NodeList of all matches
element.getElementsByTagName('span');         // live HTMLCollection
element.getElementsByClassName('highlight');  // live HTMLCollection
element.closest('.wrapper');                  // nearest ancestor matching selector
element.matches('.active');                   // true if this element matches

DOM Manipulation

element.before(nodeA, nodeB);      // insert before this element
element.after(nodeA);              // insert after this element
element.prepend(child);            // insert as first child
element.append(childA, childB);    // append children
element.remove();                  // remove from parent
element.replaceWith(newElement);   // replace with another node
element.click();                   // dispatch a click event
element.focus();                   // dispatch focus event
element.blur();                    // dispatch blur event

Layout and Geometry (Test Helpers)

All layout properties default to 0. Use setBoundingClientRect and setLayoutMetrics to configure values for testing.

element.setBoundingClientRect({ x: 10, y: 20, width: 100, height: 50 });
const rect = element.getBoundingClientRect();
// { x: 10, y: 20, width: 100, height: 50, top: 20, right: 110, bottom: 70, left: 10 }

element.setLayoutMetrics({
  offsetWidth: 200, offsetHeight: 100,
  clientWidth: 180, clientHeight: 80,
  scrollWidth: 500, scrollHeight: 300,
});

element.scrollIntoView();   // no-op stub
element.scroll(x, y);
element.scrollTo(x, y);
element.scrollBy(dx, dy);
element.getClientRects();   // [getBoundingClientRect()]

Event Handler Properties

All standard on* event handler properties are supported:

onclick, ondblclick, onmousedown, onmouseup, onmousemove, onmouseover, onmouseout, onmouseenter, onmouseleave, onkeydown, onkeyup, onkeypress, onfocus, onblur, onchange, oninput, onsubmit, onreset, onscroll, onwheel, ondrag, ondragstart, ondragend, ondragover, ondragenter, ondragleave, ondrop, onload, onerror, onresize

element.onclick = (event) => { console.log('clicked'); };

TextNode

Extends Node with nodeType 3. Represents text content.

const text = new TextNode('Hello');
text.data;            // 'Hello'
text.data = 'World';  // updates text; fires characterData mutation
text.textContent;     // 'World'
text.nodeValue;       // 'World'
text.cloneNode();     // new TextNode('World')

Comment

Extends Node with nodeType 8. Represents an HTML comment.

const comment = new Comment('TODO: fix this');
comment.data;         // 'TODO: fix this'
comment.textContent;  // 'TODO: fix this'

DocumentFragment

Extends Node with nodeType 11. A lightweight container for nodes that can be inserted into the DOM as a group.

const fragment = new DocumentFragment();
fragment.appendChild(new Element('p'));
fragment.querySelector('p');        // works
fragment.querySelectorAll('*');     // works
parent.appendChild(fragment);       // transfers all children

Document

Extends Node with nodeType 9. The root of a DOM tree.

Properties

Property	Type	Description
`readyState`	`string`	Always `'complete'`
`activeElement`	`Element \	null`	Currently focused element
`contentType`	`string`	`'text/html'`
`characterSet`	`string`	`'UTF-8'`
`URL`	`string`	Document URL
`domain`	`string`	Document domain
`referrer`	`string`	Referrer URL
`defaultView`	`unknown`	The parent Window
`visibilityState`	`string`	`'visible'` or `'hidden'`
`hidden`	`boolean`	True when `visibilityState` is `'hidden'`
`cookie`	`string`	Cookie string (full cookie jar)
`body`	`Element \	null`	The `<body>` element
`head`	`Element \	null`	The `<head>` element
`title`	`string`	Content of the `<title>` element
`documentElement`	`Element \	null`	The `<html>` element
`customElements`	`CustomElementRegistry`	Custom element registry

Collection Properties

Property	Description
`forms`	All `<form>` elements
`images`	All `<img>` elements
`links`	All `<a>` and `<area>` elements with `href`
`scripts`	All `<script>` elements
`embeds`	All `<embed>` elements
`anchors`	All `<a>` elements with `name`

Factory Methods

document.createElement('div');
document.createElementNS('http://www.w3.org/2000/svg', 'circle');
document.createTextNode('hello');
document.createComment('note');
document.createDocumentFragment();
document.createRange();
document.createEvent('Event');
document.createTreeWalker(root, whatToShow, filter);
document.createNodeIterator(root, whatToShow, filter);

Query Methods

document.getElementById('app');
document.querySelector('#app .content');
document.querySelectorAll('button');
document.getElementsByTagName('div');
document.getElementsByClassName('active');

Utility Methods

document.adoptNode(externalNode);     // removes from original tree
document.importNode(node, deep);      // clone with optional deep copy
document.addEventListener('click', handler);
document.removeEventListener('click', handler);
document.dispatchEvent(event);

Test Helpers

document.setVisibility('hidden');   // changes visibilityState and fires event

HTML Elements

Form Elements

HTMLInputElement (input)

Property	Type	Default	Description
`type`	`string`	`'text'`	Input type
`value`	`string`	`''`	Current value
`name`	`string`	`''`	Form control name
`disabled`	`boolean`	`false`	Disabled state
`checked`	`boolean`	`false`	Checked state (checkbox/radio)
`placeholder`	`string`	`''`	Placeholder text
`readOnly`	`boolean`	`false`	Read-only state
`required`	`boolean`	`false`	Required state
`min` / `max` / `step`	`string`	`''`	Numeric constraints
`pattern`	`string`	`''`	Regex validation pattern
`minLength` / `maxLength`	`number`	`-1`	Length constraints
`defaultValue`	`string`	`''`	Default value
`defaultChecked`	`boolean`	`false`	Default checked
`willValidate`	`boolean`	computed	True when not disabled
`validity`	`ValidityState`	computed	Full validity state object
`validationMessage`	`string`	`''`	Custom validation message

Validation methods: checkValidity(), reportValidity(), setCustomValidity(message)

Focus methods: focus(), blur(), select(), click()

const input = document.createElement('input');
input.type = 'email';
input.required = true;
input.value = 'invalid';
input.validity.typeMismatch;    // true
input.validity.valid;           // false

ValidityState

The validity property on form elements returns a ValidityState with these boolean properties: badInput, customError, patternMismatch, rangeOverflow, rangeUnderflow, stepMismatch, tooLong, tooShort, typeMismatch, valueMissing, valid.

HTMLButtonElement (button)

Properties: type ('submit', 'reset', 'button'), name, value, disabled.

HTMLSelectElement (select)

Properties: name, disabled, multiple, required, selectedIndex, value, options (array of HTMLOptionElement).

Validation: validity, checkValidity(), setCustomValidity().

const select = document.createElement('select');
const option = document.createElement('option');
option.value = 'a';
option.textContent = 'Option A';
select.appendChild(option);
select.value;  // 'a'

HTMLOptionElement (option)

Properties: value, selected, disabled, defaultSelected, index, label, text.

HTMLTextAreaElement (textarea)

Properties: value, name, disabled, readOnly, required, placeholder, rows (default 2), cols (default 20), minLength, maxLength, defaultValue.

Validation: validity, checkValidity(), setCustomValidity().

HTMLFormElement (form)

Properties: action, method, enctype, target, name, elements (array of form controls).

Methods: submit(), reset().

const form = document.createElement('form');
const input = document.createElement('input');
input.name = 'email';
form.appendChild(input);
form.elements; // [input]

HTMLLabelElement (label)

Properties: htmlFor, form, control.

HTMLFieldSetElement (fieldset)

Properties: disabled, name.

HTMLOutputElement (output)

Properties: value (mapped to textContent), defaultValue, htmlFor.

Media Elements

HTMLImageElement (img)

Properties: src, alt, width, height, naturalWidth, naturalHeight, complete.

HTMLVideoElement (video)

Properties: src, controls, autoplay, loop, muted, width, height, currentTime, duration, paused, ended.

Methods: play() (returns Promise, sets paused = false), pause().

HTMLAudioElement (audio)

Same media properties and methods as HTMLVideoElement (without width/ height).

HTMLPictureElement (picture)

Container element. No additional properties.

HTMLSourceElement (source)

Properties: src, type, srcset, media.

Table Elements

HTMLTableElement (table)

Properties: rows (all TR descendants), tBodies, tHead, tFoot.

Methods: insertRow(index?), deleteRow(index), createTBody(), createTHead(), createTFoot().

const table = document.createElement('table');
const row = table.insertRow();
const cell = row.insertCell();
cell.textContent = 'Hello';
table.rows.length;  // 1

HTMLTableRowElement (tr)

Properties: cells (array of HTMLTableCellElement), rowIndex.

Methods: insertCell(index?), deleteCell(index).

HTMLTableCellElement (td / th)

Properties: colSpan, rowSpan, cellIndex.

Interactive Elements

HTMLDialogElement (dialog)

Properties: open, returnValue.

Methods: show(), showModal(), close(returnValue?).

const dialog = document.createElement('dialog');
dialog.showModal();
dialog.open;        // true
dialog.close('ok');
dialog.returnValue; // 'ok'
dialog.open;        // false

HTMLDetailsElement (details)

Properties: open.

HTMLProgressElement (progress)

Properties: value, max.

HTMLMeterElement (meter)

Properties: value, min, max, low, high, optimum.

Other Elements

HTMLAnchorElement (a)

Properties: href, target, rel, download, hash, host, hostname, pathname, port, protocol, search, text.

HTMLCanvasElement (canvas)

Properties: width (default 300), height (default 150).

Methods: getContext('2d'), toDataURL(type?), toBlob(callback).

HTMLTemplateElement (template)

Properties: content (a DocumentFragment).

HTMLIFrameElement (iframe)

Properties: src, width, height, name, contentDocument, contentWindow.

HTMLScriptElement (script)

Properties: src, type, async, defer, text.

HTMLSlotElement (slot)

Properties: name.

Methods: assignedNodes(options?), assignedElements(options?).

HTMLLinkElement (link)

Properties: rel, href, type.

Automatically triggers stylesheet loading when rel="stylesheet" and a stylesheet loader is configured on the Window.

HTMLTimeElement (time)

Properties: dateTime.

SVG Elements

SVG elements are created with createElementNS using the SVG namespace.

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
circle.setAttribute('cx', '50');
circle.setAttribute('r', '25');
svg.appendChild(circle);

SVGElement (base class)

All SVG elements extend SVGElement, which sets namespaceURI to http://www.w3.org/2000/svg and preserves lowercase tag names.

Property: viewBox -- parses the viewBox attribute into { baseVal: { x, y, width, height } }.

Supported SVG Element Classes

Class	Tag	Additional API
`SVGSVGElement`	svg	`createSVGRect()`, `createSVGPoint()`, `createSVGMatrix()`
`SVGPathElement`	path	--
`SVGCircleElement`	circle	`cx`, `cy`, `r` (as `{ baseVal: { value } }`)
`SVGRectElement`	rect	--
`SVGLineElement`	line	--
`SVGTextElement`	text	--
`SVGGElement`	g	--
`SVGDefsElement`	defs	--
`SVGUseElement`	use	`href` (as `{ baseVal }`)

CSS and Styling

CSSStyleDeclaration

Provides access to inline styles via a Proxy, supporting both camelCase property access and standard methods.

const el = document.createElement('div');
el.style.backgroundColor = 'red';                      // camelCase setter
el.style.getPropertyValue('background-color');          // 'red'
el.style.setProperty('color', 'blue');
el.style.setProperty('font-size', '14px', 'important');
el.style.getPropertyPriority('font-size');              // 'important'
el.style.removeProperty('color');                       // returns 'blue'
el.style.cssText;           // 'background-color: red; font-size: 14px'
el.style.cssText = 'margin: 10px; padding: 5px';
el.style.length;            // 2
el.style.item(0);           // 'margin'

getComputedStyle

Window.getComputedStyle(element, pseudoElement?) returns a CSSStyleDeclaration with styles resolved from:

Default display values based on tag name
External stylesheets loaded via configureStylesheetLoader
<style> elements in the document
Inline styles
Inherited properties from the ancestor chain

const win = createWindow();
const doc = win.document;
const style = doc.createElement('style');
style.textContent = '.box { color: red; font-size: 16px; }';
doc.head.appendChild(style);

const div = doc.createElement('div');
div.className = 'box';
doc.body.appendChild(div);

const computed = win.getComputedStyle(div);
computed.getPropertyValue('color');     // 'red'
computed.getPropertyValue('display');   // 'block' (default for div)

Specificity and Cascade

Rules are sorted by specificity [id-count, class-count, element-count] and then by source order. Higher specificity wins; for equal specificity, the later rule wins.

CSS Inheritance

The following properties are inherited from parent elements when not explicitly set: color, font-family, font-size, font-style, font-weight, line-height, text-align, text-indent, text-transform, visibility, cursor, direction, letter-spacing, word-spacing, white-space, list-style-type, list-style-position, list-style-image, border-collapse, border-spacing, caption-side, empty-cells, quotes, speak, orphans, widows.

const parent = doc.createElement('div');
parent.style.color = 'blue';
doc.body.appendChild(parent);

const child = doc.createElement('span');
parent.appendChild(child);

win.getComputedStyle(child).getPropertyValue('color'); // 'blue' (inherited)

CSS Variables (Custom Properties)

Custom properties (--*) are inherited through the DOM tree and resolved with var().

const style = doc.createElement('style');
style.textContent = `
  :root { --primary: blue; }
  .btn { color: var(--primary); }
  .btn.alt { color: var(--accent, green); }
`;
doc.head.appendChild(style);

Variables resolve through ancestor chains: a var(--name, fallback) expression uses the fallback when the variable is undefined. Nested var() references are resolved iteratively up to 10 levels.

calc() Expressions

calc() expressions are evaluated when all operands share the same unit. Mixed-unit expressions are left as-is.

style.textContent = '.box { width: calc(100px + 50px); }';
// getComputedStyle resolves to '150px'

Supports +, -, *, / with units: px, em, rem, %, vh, vw, and more.

Pseudo-elements

::before and ::after pseudo-elements are supported in getComputedStyle.

style.textContent = '.icon::before { content: "X"; color: gold; }';
const pseudoStyle = win.getComputedStyle(icon, '::before');
pseudoStyle.getPropertyValue('content'); // '"X"'
pseudoStyle.getPropertyValue('color');   // 'gold'

@media Rules

Rules inside @media blocks are only applied when the media query matches the window's current state.

style.textContent = `
  @media (min-width: 768px) { .sidebar { display: block; } }
  @media (max-width: 767px) { .sidebar { display: none; } }
`;

External Stylesheets

Use configureStylesheetLoader to load external CSS files referenced by <link rel="stylesheet"> elements.

win.configureStylesheetLoader((href) => {
  return '.external { color: purple; }';
});
const link = doc.createElement('link');
link.rel = 'stylesheet';
link.href = '/styles.css';
doc.head.appendChild(link);

!important Handling

Properties declared !important in stylesheets override non-important inline styles. Inline !important declarations override stylesheet !important.

style.textContent = '.box { color: red !important; }';
div.style.setProperty('color', 'blue');
// getComputedStyle returns 'red' (stylesheet !important wins)

div.style.setProperty('color', 'green', 'important');
// getComputedStyle returns 'green' (inline !important wins)

Shorthand Expansion

The following shorthand properties are automatically expanded to longhands:

margin / padding to -top, -right, -bottom, -left
border to border-width, border-style, border-color
background to background-color
font to font-weight, font-size, line-height, font-family

Events

Base Event Class

const event = new Event('click', {
  bubbles: true,
  cancelable: true,
  composed: false,
});

Event Properties

Property	Type	Description
`type`	`string`	Event type name
`bubbles`	`boolean`	Whether event bubbles
`cancelable`	`boolean`	Whether default can be prevented
`composed`	`boolean`	Whether event crosses shadow DOM boundaries
`isTrusted`	`boolean`	Always `false` (synthetic events)
`timeStamp`	`number`	Timestamp when created
`defaultPrevented`	`boolean`	Whether `preventDefault()` was called
`target`	`Node \	null`	The event target
`currentTarget`	`Node \	null`	Current handler's target
`eventPhase`	`number`	0=NONE, 1=CAPTURING, 2=AT\_TARGET, 3=BUBBLING

Event Methods

preventDefault() -- Prevents the default action (if cancelable)
stopPropagation() -- Stops propagation to further listeners
stopImmediatePropagation() -- Stops propagation and skips remaining listeners on the current target
composedPath() -- Returns the event path, crossing shadow boundaries if composed

Event Dispatch

Elements support the full W3C event dispatch model: capturing phase, target phase, and bubbling phase.

element.addEventListener('click', handler);
element.addEventListener('click', handler, { capture: true, once: true });
element.removeEventListener('click', handler);
element.dispatchEvent(new Event('click', { bubbles: true }));

Event Subclasses

CustomEvent

new CustomEvent('my-event', { bubbles: true, detail: { key: 'value' } });
// Properties: detail

MouseEvent

new MouseEvent('click', {
  bubbles: true, cancelable: true,
  clientX: 100, clientY: 200,
  button: 0, buttons: 1,
  altKey: false, ctrlKey: false, shiftKey: false, metaKey: false,
});

KeyboardEvent

new KeyboardEvent('keydown', {
  key: 'Enter', code: 'Enter',
  altKey: false, ctrlKey: true, shiftKey: false, metaKey: false,
  repeat: false,
});

FocusEvent

Properties: relatedTarget.

InputEvent

Properties: data, inputType.

WheelEvent

Extends MouseEvent. Properties: deltaX, deltaY, deltaZ, deltaMode.

Constants: DOM_DELTA_PIXEL (0), DOM_DELTA_LINE (1), DOM_DELTA_PAGE (2).

PointerEvent

Extends MouseEvent. Properties: pointerId, pointerType, isPrimary, width, height, pressure, tiltX, tiltY, twist.

TouchEvent

Properties: touches, targetTouches, changedTouches (arrays of Touch objects with identifier, target, clientX, clientY, pageX, pageY, screenX, screenY).

DragEvent

Extends MouseEvent. Properties: dataTransfer (a DataTransfer instance).

ClipboardEvent

Properties: clipboardData (a DataTransfer instance).

TransitionEvent

Properties: propertyName, elapsedTime, pseudoElement.

AnimationEvent

Properties: animationName, elapsedTime, pseudoElement.

ErrorEvent

Properties: message, filename, lineno, colno, error.

MessageEvent

Properties: data, origin, source, ports.

StorageEvent

Properties: key, oldValue, newValue, url, storageArea.

PopStateEvent

Properties: state.

ProgressEvent

Properties: lengthComputable, loaded, total.

HashChangeEvent

Properties: oldURL, newURL.

PromiseRejectionEvent

Properties: promise, reason.

BeforeUnloadEvent

Properties: returnValue (settable string).

Selectors

NogginLessDom implements a CSS selector engine supporting:

Tag name: div, span, *
ID: #my-id
Class: .my-class
Attribute selectors: [attr], [attr=value], [attr~=value], [attr|=value], [attr^=value], [attr$=value], [attr*=value]
Pseudo-classes: :first-child, :last-child, :nth-child(n), :not(selector)
Combinators: descendant (space), child (>)
Comma-separated lists: div, span
Compound selectors: div.class#id[attr]

document.querySelector('div.container > p:first-child');
document.querySelectorAll('input[type="text"], textarea');
element.matches('.active:not(.disabled)');
element.closest('form');

Observers

MutationObserver

Observes changes to the DOM tree: child additions/removals, attribute changes, and text content changes.

const observer = new MutationObserver((mutations) => {
  for (const record of mutations) {
    console.log(record.type, record.target);
  }
});

observer.observe(element, {
  childList: true,
  attributes: true,
  characterData: true,
  subtree: true,
  attributeOldValue: true,
  characterDataOldValue: true,
  attributeFilter: ['class', 'id'],
});

// Mutations are delivered asynchronously via microtask
element.setAttribute('class', 'new');
await Promise.resolve(); // mutations delivered

observer.takeRecords();  // get pending records synchronously
observer.disconnect();   // stop observing

MutationRecord Properties

Property	Type	Description
`type`	`'attributes' \	'characterData' \	'childList'`	Mutation type
`target`	`Node`	The mutated node
`addedNodes`	`Node[]`	Nodes added (childList)
`removedNodes`	`Node[]`	Nodes removed (childList)
`previousSibling`	`Node \	null`	Previous sibling of added/removed node
`nextSibling`	`Node \	null`	Next sibling of added/removed node
`attributeName`	`string \	null`	Changed attribute name
`oldValue`	`string \	null`	Previous value (when old-value tracking enabled)

IntersectionObserver

Tracks element visibility. Since there is no layout engine, use the triggerIntersection helper to simulate intersections.

import { triggerIntersection } from '@asymmetric-effort/nogginlessdom';

const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    console.log(entry.target, entry.isIntersecting, entry.intersectionRatio);
  });
}, {
  root: null,
  rootMargin: '0px',
  threshold: [0, 0.5, 1],
});

observer.observe(element);

triggerIntersection(observer, [
  { target: element, isIntersecting: true, intersectionRatio: 0.75 },
]);

observer.takeRecords();
observer.unobserve(element);
observer.disconnect();

ResizeObserver

Tracks element size changes. Use triggerResize to simulate.

import { triggerResize } from '@asymmetric-effort/nogginlessdom';

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    console.log(entry.contentRect.width, entry.contentRect.height);
    console.log(entry.borderBoxSize, entry.contentBoxSize);
  }
});

observer.observe(element, { box: 'content-box' });

// Single-target form
triggerResize(observer, element, {
  x: 0, y: 0, width: 200, height: 100,
  top: 0, right: 200, bottom: 100, left: 0,
});

// Array form with partial entries
triggerResize(observer, [
  { target: element, contentRect: { width: 300, height: 150 } },
]);

observer.unobserve(element);
observer.disconnect();

Fetch API

The Window.fetch method defaults to making real HTTP/HTTPS requests via node:http/node:https. For testing, configure a mock handler.

const win = createWindow();

// Configure a mock fetch handler
win.configureFetch((url, options) => {
  return new Response(JSON.stringify({ id: 1 }), {
    status: 200,
    headers: { 'content-type': 'application/json' },
  });
});

const response = await win.fetch('/api/users');
const data = await response.json();

Request

const req = new Request('/api', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: '{"key":"value"}',
});

req.url;       // '/api'
req.method;    // 'POST'
req.headers;   // Map { 'Content-Type' => 'application/json' }
req.clone();   // new Request with same properties

// Body methods (can only be called once)
await req.json();
await req.text();
await req.blob();
await req.arrayBuffer();
await req.formData();

Response

const res = new Response('body text', {
  status: 201,
  statusText: 'Created',
  headers: { 'X-Custom': 'value' },
});

res.status;      // 201
res.ok;          // true (200-299)
res.statusText;  // 'Created'
res.headers;     // Map
res.bodyUsed;    // false
res.clone();     // new Response

// Body methods (can only be called once)
await res.json();
await res.text();
await res.blob();
await res.arrayBuffer();
await res.formData();

Headers

A standard Headers class wrapping Map<string, string>.

FormData

A standard FormData implementation with append, get, getAll, has, set, delete, entries, keys, values, and forEach.

Blob

Re-exported from globalThis.Blob.

XMLHttpRequest

Simulates the full XMLHttpRequest lifecycle. Configure a handler via Window.configureXHR.

State Constants

Constant	Value
`XMLHttpRequest.UNSENT`	0
`XMLHttpRequest.OPENED`	1
`XMLHttpRequest.HEADERS_RECEIVED`	2
`XMLHttpRequest.LOADING`	3
`XMLHttpRequest.DONE`	4

Usage

const win = createWindow();

win.configureXHR(async (request) => {
  return {
    status: 200,
    statusText: 'OK',
    headers: { 'content-type': 'application/json' },
    body: '{"result": true}',
  };
});

const xhr = new win.XMLHttpRequest();
xhr.open('GET', '/api/data');
xhr.responseType = 'json';
xhr.onload = function () {
  console.log(this.response); // { result: true }
};
xhr.send();

Properties

readyState, status, statusText, responseText, response, responseType ('', 'text', 'json', 'arraybuffer'), responseURL, timeout, withCredentials.

Event Handlers

onreadystatechange, onload, onerror, onabort, ontimeout, onloadstart, onloadend, onprogress.

Methods

open(method, url), send(body?), abort(), setRequestHeader(name, value), getResponseHeader(name), getAllResponseHeaders(), addEventListener(type, listener), removeEventListener(type, listener).

WebSocket

Simulates WebSocket connections for testing. Configure a handler via Window.configureWebSocket.

State Constants

Constant	Value
`WebSocket.CONNECTING`	0
`WebSocket.OPEN`	1
`WebSocket.CLOSING`	2
`WebSocket.CLOSED`	3

Usage

const win = createWindow();

win.configureWebSocket({
  onOpen: () => console.log('opened'),
  send: (data) => console.log('sent:', data),
  onClose: (code, reason) => console.log('closed', code, reason),
});

const ws = new win.WebSocket('ws://localhost:8080');
ws.onmessage = (event) => console.log(event.data);

// Simulate server events
ws.simulateOpen();
ws.simulateMessage('hello from server');
ws.simulateClose(1000, 'normal');
ws.simulateError(new Error('connection lost'));

Properties

readyState, url, protocol, bufferedAmount, extensions, binaryType.

Event Handlers

onopen, onmessage, onclose, onerror.

Test Helpers

simulateOpen() -- Sets state to OPEN and fires open event
simulateMessage(data) -- Fires message event with data
simulateClose(code?, reason?) -- Sets state to CLOSED and fires close event
simulateError(error?) -- Fires error event

WebSocket Events

WSMessageEvent -- extends Event with data: string
CloseEvent -- extends Event with code, reason, wasClean

IndexedDB

In-memory implementation of the IndexedDB API, available as window.indexedDB.

IDBFactory

const win = createWindow();
const request = win.indexedDB.open('mydb', 1);

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  const store = db.createObjectStore('users', { keyPath: 'id' });
  store.createIndex('name', 'name', { unique: false });
};

request.onsuccess = (event) => {
  const db = event.target.result;
  // use database...
};

Methods: open(name, version?), deleteDatabase(name), databases().

IDBDatabase

Properties: name, version, objectStoreNames.

Methods: createObjectStore(name, options?), deleteObjectStore(name), transaction(storeNames, mode?), close().

IDBTransaction

Properties: db, mode ('readonly', 'readwrite', 'versionchange'), error, objectStoreNames.

Methods: objectStore(name), abort().

Events: oncomplete, onabort, onerror.

IDBObjectStore

Properties: name, keyPath, autoIncrement, indexNames.

Methods: add(value, key?), put(value, key?), get(key), getAll(query?, count?), delete(key), clear(), count(query?), createIndex(name, keyPath, options?), deleteIndex(name), index(name), openCursor(query?, direction?).

const tx = db.transaction('users', 'readwrite');
const store = tx.objectStore('users');
store.add({ id: 1, name: 'Alice', age: 30 });
store.put({ id: 1, name: 'Alice', age: 31 });

const getReq = store.get(1);
getReq.onsuccess = () => console.log(getReq.result);

IDBIndex

Properties: name, keyPath, unique, multiEntry.

Methods: get(key), getAll(query?, count?), count(query?), openCursor(query?, direction?).

IDBCursor

Properties: source, direction, key, primaryKey, value.

Methods: continue(), advance(count), delete(), update(value).

Directions: 'next', 'nextunique', 'prev', 'prevunique'.

IDBKeyRange

Static factory methods for defining key ranges:

IDBKeyRange.only(42);
IDBKeyRange.lowerBound(10);
IDBKeyRange.lowerBound(10, true);     // open (exclusive)
IDBKeyRange.upperBound(100);
IDBKeyRange.bound(10, 100, false, true);

range.includes(50); // true

IDBRequest and IDBOpenDBRequest

Properties: result, error, source, transaction, readyState.

Events: onsuccess, onerror. IDBOpenDBRequest adds onupgradeneeded and onblocked.

Canvas

CanvasRenderingContext2D

A stub that records all draw calls for test inspection.

const canvas = document.createElement('canvas');
canvas.width = 400;
canvas.height = 300;
const ctx = canvas.getContext('2d');

ctx.fillStyle = '#ff0000';
ctx.fillRect(10, 10, 100, 50);
ctx.beginPath();
ctx.arc(200, 150, 50, 0, Math.PI * 2);
ctx.fill();

// Inspect recorded draw calls
const calls = ctx.__getDrawCalls();
// [
//   { method: 'fillRect', args: [10, 10, 100, 50] },
//   { method: 'beginPath', args: [] },
//   { method: 'arc', args: [200, 150, 50, 0, 6.28..., undefined] },
//   { method: 'fill', args: [] },
// ]

ctx.__clearDrawCalls(); // reset for next assertions

State Properties

fillStyle, strokeStyle, lineWidth, lineCap, lineJoin, font, textAlign, textBaseline, globalAlpha, globalCompositeOperation.

Path Methods

beginPath(), closePath(), moveTo(x, y), lineTo(x, y), arc(x, y, r, start, end, ccw?), arcTo(x1, y1, x2, y2, r), bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y), quadraticCurveTo(cpx, cpy, x, y), rect(x, y, w, h), ellipse(x, y, rx, ry, rotation, start, end, ccw?).

Drawing Methods

fill(), stroke(), fillRect(x, y, w, h), strokeRect(x, y, w, h), clearRect(x, y, w, h), fillText(text, x, y, maxWidth?), strokeText(text, x, y, maxWidth?), drawImage(...), clip().

Measurement

measureText(text) -- Returns { width: text.length * 10 }.

Image Data

createImageData(w, h), getImageData(sx, sy, sw, sh), putImageData(data, dx, dy).

CanvasGradient

const grad = ctx.createLinearGradient(0, 0, 100, 0);
grad.addColorStop(0, 'red');
grad.addColorStop(1, 'blue');
ctx.fillStyle = grad;

grad.__getStops(); // [{ offset: 0, color: 'red' }, { offset: 1, color: 'blue' }]

Also: createRadialGradient(x0, y0, r0, x1, y1, r1).

CanvasPattern

createPattern(image, repetition) -- Returns a CanvasPattern stub.

ImageData

const imageData = new ImageData(100, 100);
imageData.width;   // 100
imageData.height;  // 100
imageData.data;    // Uint8ClampedArray of length 40000

Transform Methods

translate(x, y), rotate(angle), scale(x, y), transform(a, b, c, d, e, f), setTransform(a, b, c, d, e, f), resetTransform().

State Stack

save() and restore() push/pop the full drawing state (fill, stroke, line, font, alpha, composite operation).

Web Animations

element.animate()

const animation = element.animate(
  [
    { opacity: '0', transform: 'translateY(-10px)' },
    { opacity: '1', transform: 'translateY(0)' },
  ],
  { duration: 300, easing: 'ease-in', fill: 'forwards' },
);

animation.playState;    // 'running'
animation.currentTime;  // 0
animation.pause();
animation.playState;    // 'paused'
animation.finish();     // jumps to end, fires onfinish
animation.cancel();     // resets, fires oncancel
animation.reverse();    // reverses playbackRate

Animation

Property	Type	Description
`id`	`string`	Animation ID
`playState`	`string`	`'idle'`, `'running'`, `'paused'`, `'finished'`
`currentTime`	`number \	null`	Current playback time
`startTime`	`number \	null`	Start time
`playbackRate`	`number`	Playback speed multiplier
`effect`	`KeyframeEffect \	null`	The animation effect
`timeline`	`AnimationTimeline \	null`	The timeline
`onfinish`	callback	Fired when animation finishes
`oncancel`	callback	Fired when animation is cancelled
`finished`	`Promise<Animation>`	Resolves when finished
`ready`	`Promise<Animation>`	Resolves when ready to play

Methods: play(), pause(), cancel(), finish(), reverse().

KeyframeEffect

const effect = new KeyframeEffect(element, keyframes, {
  duration: 500,
  delay: 100,
  easing: 'ease-out',
  iterations: 3,
  direction: 'alternate',
  fill: 'both',
});

effect.getKeyframes();
effect.setKeyframes(newKeyframes);
effect.getTiming();
effect.updateTiming({ duration: 1000 });

Workers

Worker

const worker = new Worker('/worker.js', { type: 'module', name: 'my-worker' });

worker.onmessage = (event) => console.log(event.data);
worker.onerror = (event) => console.error(event.message);
worker.postMessage({ cmd: 'start' });
worker.terminate();

// Test helpers
worker.simulateMessage({ result: 42 });
worker.simulateError(new Error('worker failed'));

SharedWorker

const shared = new SharedWorker('/shared.js', { name: 'cache' });
shared.port.start();
shared.port.onmessage = (event) => console.log(event.data);
shared.port.postMessage('ping');

// Test helper
shared.port.simulateMessage('pong');
shared.port.close();

MessagePort

Properties: onmessage, onmessageerror.

Methods: postMessage(data), start(), close(), addEventListener(...), removeEventListener(...).

Test helper: simulateMessage(data).

ServiceWorker and ServiceWorkerContainer

const registration = await navigator.serviceWorker.register('/sw.js', {
  scope: '/',
});

registration.active;   // ServiceWorker instance
registration.scope;    // '/'
await registration.unregister();
await registration.update();

await navigator.serviceWorker.getRegistration('/');
await navigator.serviceWorker.getRegistrations();
await navigator.serviceWorker.ready; // resolves with first registration

Window

createWindow(options?) is the primary entry point for creating a full DOM environment.

import { createWindow } from '@asymmetric-effort/nogginlessdom';

const win = createWindow({
  innerWidth: 1024,
  innerHeight: 768,
  screenWidth: 1920,
  screenHeight: 1080,
  devicePixelRatio: 2,
  colorScheme: 'dark',
  reducedMotion: false,
});

Window Properties

Property	Type	Description
`document`	`Document`	The document (with html/head/body structure)
`location`	`Location`	Location stub
`history`	`History`	History with push/pop/replace state
`navigator`	`Navigator`	Navigator stub
`localStorage`	`Storage`	In-memory storage (5 MB quota)
`sessionStorage`	`Storage`	In-memory storage (5 MB quota)
`innerWidth` / `innerHeight`	`number`	Viewport dimensions
`performance`	`Performance`	Performance API
`screen`	`object`	Screen stub with `width`, `height`, etc.
`devicePixelRatio`	`number`	DPR
`scrollX` / `scrollY`	`number`	Scroll position
`pageXOffset` / `pageYOffset`	`number`	Scroll position aliases
`indexedDB`	`IDBFactory`	IndexedDB factory
`CSS`	`object`	`CSS.supports(prop, val)`
`console`	`Console`	Re-exported globalThis.console

Web API Properties on Window

FormData, Headers, Request, Response, TextEncoder, TextDecoder, Blob, atob, btoa, structuredClone, DOMParser, XMLSerializer, queueMicrotask, AbortController, AbortSignal, crypto, Worker, SharedWorker.

Storage

In-memory implementation with quota enforcement and StorageEvent dispatch.

win.localStorage.setItem('key', 'value');
win.localStorage.getItem('key');   // 'value'
win.localStorage.removeItem('key');
win.localStorage.clear();
win.localStorage.length;           // 0
win.localStorage.key(0);           // null

// StorageEvent fires on the Window when values change
win.addEventListener('storage', (e) => {
  console.log(e.key, e.oldValue, e.newValue);
});

Quota: 5 MB (UTF-16). Throws a QuotaExceededError when exceeded.

Navigator

Properties: userAgent, language, languages, onLine, cookieEnabled, platform, vendor, hardwareConcurrency, maxTouchPoints, clipboard, permissions, serviceWorker.

Methods: sendBeacon(url, data?), vibrate(pattern).

Clipboard

await win.navigator.clipboard.writeText('hello');
await win.navigator.clipboard.readText(); // 'hello'

Permissions

const result = await win.navigator.permissions.query({ name: 'clipboard-read' });
result.state; // 'granted' (always)

History

win.history.pushState({ page: 1 }, '', '/page/1');
win.history.replaceState({ page: 2 }, '', '/page/2');
win.history.back();     // fires popstate
win.history.forward();  // fires popstate
win.history.go(-2);     // fires popstate
win.history.length;
win.history.state;

Location

Properties: href, hash, pathname, search, origin, protocol, host, hostname, port.

Methods: assign(url), replace(url), reload().

matchMedia

const mql = win.matchMedia('(min-width: 768px)');
mql.matches;   // true if innerWidth >= 768
mql.media;     // '(min-width: 768px)'

mql.addEventListener('change', (e) => {
  console.log(e.matches, e.media);
});

// Changing dimensions fires change events on affected MediaQueryLists
win.setDimensions(500, 400);

Supported media features: min-width, max-width, min-height, max-height, prefers-color-scheme, prefers-reduced-motion, media types (all, screen, print).

Performance API

win.performance.now();                         // ms since creation
win.performance.timeOrigin;                    // creation timestamp
win.performance.mark('start');
win.performance.mark('end');
win.performance.measure('duration', 'start', 'end');
win.performance.getEntries();
win.performance.getEntriesByName('start');
win.performance.getEntriesByType('mark');
win.performance.clearMarks('start');
win.performance.clearMeasures();

PerformanceObserver

const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  console.log(entries);
});
observer.observe({ entryTypes: ['mark', 'measure'] });
observer.disconnect();
observer.takeRecords();

requestAnimationFrame

const id = win.requestAnimationFrame((timestamp) => {
  console.log('frame at', timestamp);
});
win.cancelAnimationFrame(id);

// Test helper: synchronously flush all queued callbacks
win.flushAnimationFrames();

requestIdleCallback

const id = win.requestIdleCallback((deadline) => {
  console.log(deadline.timeRemaining(), deadline.didTimeout);
});
win.cancelIdleCallback(id);

// Test helper: synchronously flush all queued callbacks
win.flushIdleCallbacks();

postMessage

win.addEventListener('message', (event) => {
  console.log(event.data, event.origin);
});
win.postMessage({ type: 'init' }, '*');
// Delivered asynchronously via queueMicrotask

Page Visibility

win.document.visibilityState; // 'visible'
win.document.hidden;          // false

win.document.setVisibility('hidden');
// Fires 'visibilitychange' event on document

Timer Methods

setTimeout, setInterval, clearTimeout, clearInterval delegate to globalThis. Use fake timers from the mocking module to control them.

Configuration Methods

win.configureFetch(handler);
win.configureXHR(handler);
win.configureWebSocket(handler);
win.configureStylesheetLoader(loader);

ARIA and Accessibility

Property Accessors

All standard ARIA property accessors are implemented as getters/setters that map to the corresponding aria-* attributes:

element.ariaLabel = 'Close dialog';
element.getAttribute('aria-label');  // 'Close dialog'

element.ariaHidden = 'true';
element.ariaDisabled = 'true';
element.ariaExpanded = 'false';
element.ariaSelected = 'true';
element.ariaChecked = 'mixed';
element.ariaRequired = 'true';
element.ariaPressed = 'true';
element.ariaLive = 'polite';
element.ariaDescribedBy = 'desc-id';
element.ariaLabelledBy = 'label-id';
element.ariaControls = 'panel-id';
element.ariaValueNow = '50';
element.ariaValueMin = '0';
element.ariaValueMax = '100';
element.ariaValueText = 'fifty percent';

Role

element.role = 'button';
element.getAttribute('role'); // 'button'

Implicit Roles

getImplicitRole(element) returns the implicit ARIA role based on the tag name and attributes. An explicit role attribute always takes precedence.

import { getImplicitRole } from '@asymmetric-effort/nogginlessdom';

getImplicitRole(button);      // 'button'
getImplicitRole(nav);         // 'navigation'
getImplicitRole(header);      // 'banner'
getImplicitRole(footer);      // 'contentinfo'
getImplicitRole(main);        // 'main'

// Context-dependent:
getImplicitRole(anchor);                       // null (no href)
anchor.setAttribute('href', '/');
getImplicitRole(anchor);                       // 'link'

input.setAttribute('type', 'checkbox');
getImplicitRole(input);                        // 'checkbox'

Pointer Capture

element.setPointerCapture(1);
element.hasPointerCapture(1);    // true
element.releasePointerCapture(1);
element.hasPointerCapture(1);    // false

Drag and Drop

DataTransfer

const dt = new DataTransfer();
dt.setData('text/plain', 'Hello');
dt.setData('text/html', '<b>Hello</b>');
dt.getData('text/plain');   // 'Hello'
dt.types;                   // ['text/plain', 'text/html']
dt.clearData('text/html');
dt.clearData();             // clears all

dt.dropEffect = 'copy';
dt.effectAllowed = 'copyMove';
dt.setDragImage(element, 0, 0);  // no-op

DataTransferItem

dt.items.length;    // number of items
dt.items.add('data', 'text/plain');
const item = dt.items.get(0);
item.kind;          // 'string'
item.type;          // 'text/plain'
item.getAsString((data) => console.log(data));
item.getAsFile();   // null (files not supported)
dt.items.remove(0);
dt.items.clear();

DragEvent

const dragEvent = new DragEvent('drop', {
  bubbles: true,
  cancelable: true,
  dataTransfer: dt,
});
element.dispatchEvent(dragEvent);

HTML Parser

parseHTML

Parses HTML strings into DOM nodes. Used internally by innerHTML setter.

import { parseHTML } from '@asymmetric-effort/nogginlessdom';

const nodes = parseHTML('<div class="box"><p>Hello</p></div>');

Supported features:

Standard HTML elements and attributes (quoted and unquoted values)
Void elements (br, img, input, etc.)
Self-closing tags
Raw text elements (script, style, textarea) -- content is not parsed as HTML
HTML entities: &, <, >, ", ',  , ©, ®, ™, —, –, «, », •, …, €, £, ¥, ¢
Numeric entities: {, 💩
DOCTYPE declarations (skipped)
HTML comments (skipped)
Maximum nesting depth of 5000 to prevent stack overflow

Shadow DOM and Custom Elements

Shadow DOM

const host = document.createElement('div');
const shadow = host.attachShadow({ mode: 'open' });

shadow.innerHTML = '<slot></slot>';
shadow.getElementById('id');
shadow.querySelector('.cls');
shadow.querySelectorAll('*');

host.shadowRoot;  // shadow (open mode)
// Closed mode: host.shadowRoot returns null

ShadowRoot extends Node and supports innerHTML, getElementById, querySelector, and querySelectorAll.

Events with composed: true cross shadow boundaries during dispatch. Non-composed events stop at the shadow root.

Custom Elements

class MyButton extends Element {
  static observedAttributes = ['variant'];

  connectedCallback() { /* called on appendChild */ }
  disconnectedCallback() { /* called on removeChild */ }
  attributeChangedCallback(name, oldVal, newVal) { /* called on setAttribute */ }

  constructor() {
    super('my-button');
  }
}

document.customElements.define('my-button', MyButton);
document.customElements.get('my-button');        // MyButton
document.customElements.getName(MyButton);       // 'my-button'
await document.customElements.whenDefined('my-button'); // resolves immediately

const btn = document.createElement('my-button'); // uses registered constructor

Slots

const slot = document.createElement('slot');
slot.name = 'header';
slot.assignedNodes();    // nodes distributed to this slot
slot.assignedElements(); // elements only

Collections and Utilities

NodeList

Returned by querySelectorAll. Supports length, [index], and forEach.

HTMLCollection

Returned by getElementsByTagName, getElementsByClassName, and children. Live collection: re-evaluates on each access.

DOMTokenList

Returned by element.classList. Methods: add(token), remove(token), toggle(token, force?), contains(token), replace(old, new), item(index), toString().

element.classList.add('active', 'visible');
element.classList.remove('hidden');
element.classList.toggle('selected');
element.classList.contains('active');  // true

TreeWalker and NodeIterator

const walker = document.createTreeWalker(
  root,
  NodeFilter.SHOW_ELEMENT,
  (node) => NodeFilter.FILTER_ACCEPT,
);

while (walker.nextNode()) {
  console.log(walker.currentNode);
}

walker.previousNode();
walker.firstChild();
walker.lastChild();
walker.nextSibling();
walker.previousSibling();
walker.parentNode();

NodeFilter Constants

Constant	Value
`NodeFilter.SHOW_ALL`	`0xFFFFFFFF`
`NodeFilter.SHOW_ELEMENT`	`0x1`
`NodeFilter.SHOW_TEXT`	`0x4`
`NodeFilter.SHOW_COMMENT`	`0x80`
`NodeFilter.FILTER_ACCEPT`	`1`
`NodeFilter.FILTER_REJECT`	`2`
`NodeFilter.FILTER_SKIP`	`3`

Mocking API Reference

The mocking module provides comprehensive utilities for creating mock functions, spying on object methods and accessors, controlling timers, mocking modules, stubbing globals and environment variables, and async test helpers.

import {
  fn, spyOn, mock, vi,
  useFakeTimers, useRealTimers,
} from '@asymmetric-effort/nogginlessdom';

Mock Functions

fn()

Creates a mock function that tracks calls, arguments, return values, and instances.

const mockFn = fn();
mockFn('a', 'b');
mockFn('c');

mockFn.mock.calls;    // [['a', 'b'], ['c']]
mockFn.mock.results;  // [{ type: 'return', value: undefined }, ...]

With an implementation:

const add = fn((a: number, b: number) => a + b);
add(1, 2);  // 3

Mock Return Values

const mockFn = fn();

// Return the same value every time
mockFn.mockReturnValue(42);
mockFn();  // 42
mockFn();  // 42

// Return a value only for the next call
mockFn.mockReturnValueOnce('first');
mockFn.mockReturnValueOnce('second');
mockFn();  // 'first'
mockFn();  // 'second'
mockFn();  // 42 (falls back to mockReturnValue)

Mock Implementations

const mockFn = fn();

// Set a persistent implementation
mockFn.mockImplementation((x: number) => x * 2);
mockFn(5);  // 10

// Set a one-time implementation
mockFn.mockImplementationOnce((x: number) => x * 3);
mockFn(5);  // 15 (one-time)
mockFn(5);  // 10 (falls back to mockImplementation)

Async Mocks

const mockFn = fn();

mockFn.mockResolvedValue({ data: 'ok' });
await mockFn();  // { data: 'ok' }

mockFn.mockResolvedValueOnce({ data: 'once' });
await mockFn();  // { data: 'once' }
await mockFn();  // { data: 'ok' }

mockFn.mockRejectedValue(new Error('fail'));
await mockFn();  // throws Error('fail')

mockFn.mockRejectedValueOnce(new Error('once'));
await mockFn();  // throws Error('once')

Mock Naming

const mockFn = fn();
mockFn.mockName('myFunction');
mockFn.getMockName();  // 'myFunction'

getMockImplementation

const impl = (x: number) => x + 1;
const mockFn = fn(impl);
mockFn.getMockImplementation();  // impl

withImplementation

Temporarily replaces the implementation for the duration of a callback.

const mockFn = fn(() => 'original');

mockFn.withImplementation(
  () => 'temporary',
  () => {
    mockFn();  // 'temporary'
  },
);
mockFn();  // 'original'

// Also works with async callbacks
await mockFn.withImplementation(
  () => 'async-temp',
  async () => {
    mockFn();  // 'async-temp'
  },
);

Mock Properties

.mock.calls

Array of argument arrays for each call.

mockFn('a', 1);
mockFn('b', 2);
mockFn.mock.calls;  // [['a', 1], ['b', 2]]

.mock.results

Array of { type, value } objects for each call.

const mockFn = fn(() => 42);
mockFn();
mockFn.mock.results;  // [{ type: 'return', value: 42 }]

const throwing = fn(() => { throw new Error('oops'); });
try { throwing(); } catch {}
throwing.mock.results;  // [{ type: 'throw', value: Error('oops') }]

.mock.lastCall

The arguments of the most recent call, or undefined if never called.

mockFn('x', 'y');
mockFn.mock.lastCall;  // ['x', 'y']

.mock.instances

Array of this values when the mock was called with new.

const MockClass = fn();
const instance = new MockClass();
MockClass.mock.instances;  // [instance]

.mock.contexts

Array of this values for every call (both regular and constructor calls).

Mock Control

mockClear()

Resets call tracking (calls, results, instances, contexts) but preserves the implementation and return values.

mockFn('a');
mockFn.mockClear();
mockFn.mock.calls;  // []

mockReset()

Calls mockClear() and also removes the implementation and return values.

mockFn.mockReturnValue(42);
mockFn.mockReset();
mockFn();  // undefined

mockRestore()

Calls mockReset(). For spies created with spyOn, also restores the original function or accessor on the object.

const spy = spyOn(obj, 'method');
spy.mockRestore();
// obj.method is now the original function

Spies

spyOn

Creates a spy on an object method. The spy wraps the original function and tracks calls while still invoking the original by default.

const obj = {
  greet(name: string) { return `Hello, ${name}`; },
};

const spy = spyOn(obj, 'greet');
obj.greet('World');          // 'Hello, World'
spy.mock.calls;              // [['World']]

// Override the implementation
spy.mockReturnValue('Hi');
obj.greet('World');          // 'Hi'

// Restore the original
spy.mockRestore();
obj.greet('World');          // 'Hello, World'

Spying on Getters

const obj = {
  get value() { return 42; },
};

const spy = spyOn(obj, 'value', 'get');
spy.mockReturnValue(100);
obj.value;  // 100

spy.mockRestore();
obj.value;  // 42

Spying on Setters

const obj = {
  _data: '',
  set data(v: string) { this._data = v; },
};

const spy = spyOn(obj, 'data', 'set');
obj.data = 'hello';
spy.mock.calls;  // [['hello']]

spy.mockRestore();

Module Mocking

mock.module

Registers a mock for a module path. The factory function receives an importOriginal helper to access the real module.

await mock.module('fs', () => ({
  readFileSync: fn(() => 'mocked content'),
  writeFileSync: fn(),
}));

// With importOriginal to keep some real exports
await mock.module('fs', async ({ importOriginal }) => {
  const actual = await importOriginal();
  return {
    ...actual,
    readFileSync: fn(() => 'mocked'),
  };
});

Mocks must be set up before the module under test is imported.

mock.modulePartial

Partially mocks a module: imports the real module, overlays overrides, and optionally auto-mocks remaining functions.

await mock.modulePartial('fs', {
  readFileSync: fn(() => 'mocked'),
}, { autoMockRest: true });

importActual

Dynamically imports the real module, bypassing any registered mocks.

const realFs = await mock.importActual('fs');

importMock

Imports a module with mock awareness. If a mock is registered, returns it. Otherwise, auto-mocks all function exports.

const mockedFs = await mock.importMock('fs');
// All functions are replaced with fn() mocks

mock.require

Synchronous mock-aware require. Returns the mock if registered, otherwise falls back to the real module.

const fs = mock.require('fs');

mock.unmock and mock.doUnmock

Removes the mock registration for a module.

mock.unmock('fs');

mock.resetModules

Clears all registered module mocks.

mock.resetModules();

mock.getMockedModule

Returns the mock for a given module, or undefined.

const m = mock.getMockedModule('fs');

mock.hoisted

Executes a factory function immediately and returns its result. Useful for variable declarations that need to be available before mock.module() calls.

const mocks = mock.hoisted(() => ({
  readFile: fn(),
}));
await mock.module('fs', () => mocks);

Fake Timers

useFakeTimers

Replaces setTimeout, setInterval, clearTimeout, clearInterval, Date, Date.now, setImmediate, clearImmediate, requestAnimationFrame, cancelAnimationFrame, and performance.now with controllable fakes.

const clock = useFakeTimers();

setTimeout(() => console.log('fired'), 1000);
clock.advanceTimersByTime(1000);  // 'fired'

With options:

const clock = useFakeTimers({
  now: new Date('2025-01-01'),
  toFake: ['setTimeout', 'Date'],  // only fake specific APIs
});

Date.now();  // 1735689600000 (2025-01-01)

FakeTimerController Methods

Method	Description
`advanceTimersByTime(ms)`	Advance clock by ms, firing timers along the way
`advanceTimersByTimeAsync(ms)`	Same as above, returns Promise
`advanceTimersToNextTimer()`	Advance to the next scheduled timer
`advanceTimersToNextTimerAsync()`	Same as above, returns Promise
`getTimerCount()`	Number of pending timers
`runAllTimers()`	Run all pending timers (max 1000 iterations)
`runAllTimersAsync()`	Same as above, returns Promise
`runOnlyPendingTimers()`	Run only currently pending timers (not new ones)
`runOnlyPendingTimersAsync()`	Same as above, returns Promise
`setSystemTime(time)`	Set the current fake time (number or Date)
`getMockedSystemTime()`	Get current fake time as Date
`getRealSystemTime()`	Get real system time
`now`	Current fake time in milliseconds

useRealTimers

Restores all original timer functions, Date, requestAnimationFrame, and performance.now.

useRealTimers();

requestAnimationFrame Integration

When fake timers are active, requestAnimationFrame callbacks are scheduled with a virtual 16ms delay and receive the current fake timestamp.

const clock = useFakeTimers();
let frame = 0;
requestAnimationFrame((ts) => { frame = ts; });
clock.advanceTimersByTime(16);
// frame === 16

Date and performance Mocking

When fake timers are active:

Date.now() returns the fake time
new Date() (no arguments) uses the fake time
new Date(value) still works with explicit values
performance.now() returns the fake time

const clock = useFakeTimers({ now: 1000 });
Date.now();           // 1000
new Date().getTime(); // 1000
performance.now();    // 1000

clock.advanceTimersByTime(500);
Date.now();           // 1500

Global Stubs

mock.stubGlobal

Replaces a global property with a value, storing the original for later restoration.

mock.stubGlobal('fetch', fn(() => Promise.resolve(new Response('ok'))));
globalThis.fetch('/api');

mock.unstubAllGlobals

Restores all stubbed globals to their original values.

mock.unstubAllGlobals();

stubEnv

Stubs an environment variable, storing the original for restoration.

vi.stubEnv('NODE_ENV', 'test');
process.env.NODE_ENV;  // 'test'

unstubAllEnvs

Restores all stubbed environment variables.

vi.unstubAllEnvs();

Auto-Cleanup

configureMockBehavior

Configures automatic mock cleanup behavior. Called by the test runner after each test.

import { configureMockBehavior } from '@asymmetric-effort/nogginlessdom';

configureMockBehavior({
  clearMocks: true,       // call mockClear() on all mocks after each test
  resetMocks: false,      // call mockReset() on all mocks after each test
  restoreMocks: false,    // call mockRestore() on all mocks after each test
  unstubGlobals: false,   // call unstubAllGlobals() after each test
  fakeTimers: {
    autoRestore: false,   // call useRealTimers() after each test
  },
});

Priority: restoreMocks > resetMocks > clearMocks. Only one is applied.

Bulk Operations

mock.clearAllMocks();    // mockClear() on every tracked mock
mock.resetAllMocks();    // mockReset() on every tracked mock
mock.restoreAllMocks();  // mockRestore() on every tracked mock + unstubAllGlobals
mock.isMockFunction(fn); // true if value was created by fn() or spyOn()

Async Utilities

waitFor

Retries a callback until it does not throw. Returns the callback's return value.

const result = await vi.waitFor(() => {
  const el = document.querySelector('.loaded');
  if (!el) throw new Error('not loaded');
  return el;
}, {
  timeout: 5000,   // max wait time in ms (default: 1000)
  interval: 100,   // retry interval in ms (default: 50)
});

Works with async callbacks:

await vi.waitFor(async () => {
  const res = await fetch('/status');
  if (!res.ok) throw new Error('not ready');
});

waitUntil

Retries a callback until it returns a truthy value. Returns the truthy value.

const element = await vi.waitUntil(() => {
  return document.querySelector('.ready');
}, {
  timeout: 3000,
  interval: 50,
});

vi Namespace

The vi object provides a single namespace that mirrors established testing conventions for compatibility. It re-exports all mocking utilities.

import { vi } from '@asymmetric-effort/nogginlessdom';

vi.fn();
vi.spyOn(obj, 'method');
vi.useFakeTimers();
vi.useRealTimers();
vi.getMockedSystemTime();
vi.getRealSystemTime();
vi.stubEnv('KEY', 'value');
vi.unstubAllEnvs();
vi.waitFor(callback, options);
vi.waitUntil(callback, options);
vi.mocked(value);            // identity function for type narrowing
vi.configureMockBehavior(config);
vi.getMockConfig();
vi.mock('module', factory);  // alias for mock.module
vi.module('module', factory);
vi.modulePartial('module', overrides, options);
vi.doMock('module', factory);
vi.importActual('module');
vi.importMock('module');
vi.require('module');
vi.unmock('module');
vi.doUnmock('module');
vi.resetModules();
vi.getMockedModule('module');
vi.stubGlobal('name', value);
vi.unstubAllGlobals();
vi.isMockFunction(value);
vi.clearAllMocks();
vi.resetAllMocks();
vi.restoreAllMocks();
vi.hoisted(factory);

vi.mocked

Identity function used for TypeScript type narrowing of mocked values.

const mockedFetch = vi.mocked(fetch);
// TypeScript now treats mockedFetch as a mock function type

NogginLessDom Documentation

NogginLessDom (@asymmetric-effort/nogginlessdom) is a zero-dependency testing framework built entirely on Node.js built-in modules. It wraps node:test and node:assert to deliver a comprehensive test runner, assertion library, DOM simulation, mocking utilities, code coverage, snapshot testing, and dependency analysis while eliminating the entire third-party supply chain attack surface.

Getting Started

Getting Started -- Installation, first test, and a walkthrough of all core features with runnable examples.

Architecture

Architecture -- Zero-dependency philosophy, module structure, dependency graph, build pipeline, and security design.

API Reference

Detailed documentation for every exported function, class, and matcher.

API Reference Index -- Overview of all exported modules.
Test Runner -- describe, it, test, lifecycle hooks, modifiers (skip, only, todo, each, retry, shuffle), reporters, watch mode, and dependency analysis tools.
Assertions -- expect() with 30+ matchers, .not, .resolves, .rejects, asymmetric matchers, custom matchers, assertion tracking, and snapshot testing.
DOM Simulation -- Document, Element, Node, 29 typed HTML elements, 20 event types, Shadow DOM, Custom Elements, Observer APIs, SVG, Canvas, IndexedDB, Web Workers, WebSocket, and Window environment.
Mocking -- fn(), spyOn(), mock instances, module mocking, fake timers with Date mocking, global/env stubbing, async utilities, and the vi namespace.

User Guide

Guides for end users adopting NogginLessDom in their projects.

User Guide Index -- Orientation and quick start.
Installation -- Installing via Bun, npm, yarn, or pnpm. Verifying the install, TypeScript setup, and what gets installed.
Configuration -- Test file patterns, TypeScript configuration, coverage settings, reporter configuration, watch mode, test filtering, mock auto-cleanup, test isolation, serial execution, dependency analysis, and environment variables reference.

Developer Guide

Guides for contributors to the NogginLessDom project itself.

Developer Guide Index -- Contributor orientation and links to all developer docs.
Environment Setup -- Prerequisites, cloning, IDE configuration, and project structure.
Testing -- Test organization, coverage requirements, naming conventions, and running tests.
Building -- Build process, output artifacts, clean builds, and troubleshooting.
Releasing -- Semantic versioning, release targets, npm publishing, and pre-release checklist.

Quick Links

Architecture

This document describes the internal architecture of NogginLessDom, including the zero-dependency philosophy, module structure, dependency graph, build pipeline, and security design.

v0.0.25 -- 80 source files, 28K+ lines of TypeScript, 3100+ tests, zero runtime dependencies, 9 dev dependencies.

Overview

NogginLessDom is a testing framework built entirely on Node.js built-in modules. The published package has an empty dependencies field. No third-party code ships to consumers.

This is not aspirational -- it is a hard constraint enforced by CI, code review, and automated checks. Every algorithm, parser, and data structure is implemented from scratch. The framework wraps node:test and node:assert for test execution and assertion foundations, then builds everything else (DOM simulation, mocking, coverage, snapshot testing, dependency analysis) as pure TypeScript with no external imports.

Design Principles

Zero runtime dependencies. The dependencies field is {}. No third-party code ships to consumers.
Node built-ins only. Built on node:test, node:assert, and standard Node.js APIs. No polyfills, shims, or vendored libraries.
Security first. No eval(), new Function(), or dynamic code execution. HTML input is validated through deterministic parsing.
API compatibility. Public API follows widely adopted testing conventions for straightforward adoption.
Explicit over implicit. No magic globals, hidden configuration, or auto-detection. Behavior is controlled through explicit function calls.

Module Dependency Graph

The framework is organized into six core modules. All are exported from src/index.ts.

src/index.ts
  |
  +-- src/test-runner/    -->  node:test
  |     (test execution, lifecycle, reporters, watch, dependency analysis)
  |
  +-- src/assertions/     -->  node:assert, node:fs (snapshots)
  |     (expect, matchers, asymmetric matchers, snapshots, diff)
  |
  +-- src/dom/            -->  (no external deps; pure implementation)
  |     (Document, Element, events, window, CSS, observers, canvas,
  |      SVG, IndexedDB, workers, WebSocket, and more)
  |
  +-- src/mocking/        -->  (no external deps; pure implementation)
  |     (fn, spyOn, vi, fake timers, module mocking, global stubbing)
  |
  +-- src/coverage/       -->  node:fs, node:path, node:inspector
  |     (V8/Istanbul providers, reporters, thresholds, source maps)
  |
  +-- src/hoist/          -->  (no external deps; regex-based transform)
        (mock hoisting for ESM compatibility)

There are no cross-dependencies between the six modules. Each can be imported and used independently.

Test Runner Module

Location: src/test-runner/

Wraps the built-in node:test module to provide a comprehensive test runner interface.

File	Responsibility
`index.ts`	`describe`, `it`, `test`, lifecycle hooks, and modifiers
`reporter.ts`	`ReporterManager` and five built-in reporters
`watch.ts`	File watching, import graph building, glob matching
`cycle-detection.ts`	Circular import detection with configurable strictness
`depth-analysis.ts`	Import chain depth analysis
`unused-imports.ts`	Unused import detection
`dependency-graph.ts`	Dependency graph building with JSON, DOT, Mermaid export

The mapping layer to node:test is intentionally thin. NogginLessDom does not reimplement test scheduling, parallel execution, or native reporting -- it relies on the battle-tested node:test infrastructure. Advanced features like shuffle use a seeded Fisher-Yates algorithm for reproducible randomization.

Assertions Module

Location: src/assertions/

Wraps node:assert to provide an expect(value) API with 30+ chainable matchers.

File	Responsibility
`index.ts`	`expect()`, all matchers, `.not`, `.resolves`, `.rejects`
`asymmetric.ts`	Asymmetric matchers and negated variants
`snapshot.ts`	`SnapshotClient`, `SnapshotManager`, `SnapshotEnvironment`
`diff.ts`	`objectDiff`, `stringDiff`, ANSI error formatting
`extend.ts`	`expect.extend()` for user-defined matchers

Each matcher call translates to the corresponding node:assert function:

toBe(expected) maps to assert.strictEqual
toEqual(expected) maps to assert.deepStrictEqual
toThrow() maps to assert.throws
.not delegates to assert.notStrictEqual, assert.notDeepStrictEqual, assert.doesNotThrow
.resolves / .rejects unwrap promises before applying the inner matcher

DOM Module

Location: src/dom/

The largest module. Provides a complete DOM environment for testing without any third-party code.

Core

File	Contents
`index.ts`	`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`,
	`Comment`, `Event`, `NodeList`, `HTMLCollection`,
	`DOMTokenList`, `CSSStyleDeclaration`, `TreeWalker`,
	`NodeIterator`

HTML Elements

File	Contents
`html-elements.ts`	29 typed HTML element classes plus `ValidityState`

Events

File	Contents
`events.ts`	20 event classes including `CustomEvent`, `MouseEvent`,
	`KeyboardEvent`, `FocusEvent`, `PointerEvent`, `DragEvent`,
	`ClipboardEvent`, and more

Window and Browser APIs

File	Contents
`window.ts`	`Window`, `Storage`, `Location`, `History`, `Navigator`,
	`Clipboard`, `Permissions`, `MediaQueryList`, `Request`,
	`Response`, `createWindow()`
`performance.ts`	`Performance`, `PerformanceObserver`
`animation.ts`	`Animation`, `KeyframeEffect`, `AnimationTimeline`
`websocket.ts`	`WebSocket`, `CloseEvent`, `WSMessageEvent`
`workers.ts`	`Worker`, `SharedWorker`, `MessagePort`,
	`ServiceWorkerContainer`, `ServiceWorker`
`indexeddb.ts`	`IDBFactory`, `IDBDatabase`, `IDBObjectStore`,
	`IDBTransaction`, `IDBRequest`, `IDBIndex`, `IDBCursor`,
	`IDBKeyRange`
`xhr.ts`	`XMLHttpRequest`
`media-query.ts`	`parseMediaQuery`, `evaluateMediaQuery`

DOM Infrastructure

File	Contents
`selector.ts`	CSS selector engine with combinators and
	pseudo-classes
`collections.ts`	`NodeList`, `HTMLCollection`
`shadow.ts`	`ShadowRoot`
`custom-elements.ts`	`CustomElementRegistry`
`mutation-observer.ts`	`MutationObserver`, `MutationRecord`
`intersection-observer.ts`	`IntersectionObserver`
`resize-observer.ts`	`ResizeObserver`
`style.ts`	`CSSStyleDeclaration`
`token-list.ts`	`DOMTokenList`
`tree-walker.ts`	`TreeWalker`, `NodeIterator`, `NodeFilter`
`range.ts`	`Range`
`selection.ts`	`Selection`
`css-cascade.ts`	CSS parsing, specificity, cascade, shorthand
	expansion
`svg.ts`	SVG element classes (`SVGSVGElement`,
	`SVGPathElement`, `SVGCircleElement`, etc.)
`canvas.ts`	`CanvasRenderingContext2D`, `CanvasGradient`,
	`ImageData`

Data and Parsing

File	Contents
`html-parser.ts`	HTML string parser
`html-serializer.ts`	Node-to-HTML serialization
`dom-parser.ts`	`DOMParser`, `XMLSerializer`
`form-data.ts`	`FormData`
`blob.ts`	`Blob`
`headers.ts`	`Headers`
`cookie.ts`	`CookieJar`
`data-transfer.ts`	`DataTransfer`, `DataTransferItemList`
`abort.ts`	`AbortController`, `AbortSignal`
`web-apis.ts`	`atob`, `btoa`, `TextEncoder`, `TextDecoder`,
	`structuredClone`, `crypto`

Mocking Module

Location: src/mocking/

Provides spy, stub, timer mocking, module mocking, and utility functions.

File	Responsibility
`index.ts`	`fn()`, `spyOn()`, timer mocking, module mocking, global/env
	stubbing, bulk operations, async utilities
`vi.ts`	`vi` convenience namespace combining all mocking utilities

Key capabilities:

Mock functions with full call/result tracking, chained return values, promise helpers, and withImplementation()
Spy on methods and accessors (getters/setters)
Fake timers with advanceTimersByTime, runAllTimers, setSystemTime, and full Date constructor mocking
Module mocking with mock.module(), mock.doMock(), and mock.hoisted() for ESM compatibility
Global stubbing with stubGlobal() and env stubbing with stubEnv()
Async utilities with waitFor() and waitUntil()

Coverage Module

Location: src/coverage/

Provides code coverage collection, analysis, and reporting.

File	Responsibility
`index.ts`	Public API (`startCoverage`, `takeCoverage`,
	`stopCoverage`, `reportCoverage`,
	`checkCoverageThresholds`)
`v8-provider.ts`	V8 coverage provider using `node:inspector`
`istanbul-provider.ts`	Istanbul instrumentation-based coverage provider
`v8-to-istanbul.ts`	V8-to-Istanbul format conversion
`coverage-map.ts`	Core data structure for file coverage with merge
`source-map.ts`	Maps coverage data back to original source positions
`config.ts`	Coverage configuration resolution
`nyc-config.ts`	NYC config compatibility
`thresholds.ts`	Configurable coverage thresholds with enforcement
`filter.ts`	File inclusion/exclusion filtering
`ignore.ts`	Istanbul ignore comment parsing
`changed.ts`	Coverage for changed files only
`reporters/`	11 reporter implementations

Hoist Module

Location: src/hoist/

Reorders top-level mock calls (mock.module(), vi.mock(), vi.hoisted()) so they appear before all import declarations. This is necessary for ESM because import bindings are evaluated before any module-level statements execute.

File	Responsibility
`index.ts`	`hoistMocks()` -- regex-based source transform
`bun-plugin.ts`	Bun build plugin that applies hoisting during bundling

The implementation is intentionally regex-based (no AST parser) to preserve the zero-dependency constraint.

Build Pipeline

The build process is driven by make build and consists of two stages:

TypeScript Source (src/)
        |
        v
  bun build src/index.ts --outdir build --target node
        |
        v
  JavaScript output (build/index.js, ESM format)
        |
        v
  tsc --emitDeclarationOnly
        |
        v
  Type declarations (build/*.d.ts) + source maps

Build Artifacts

Artifact	Description
`build/index.js`	Bundled JavaScript, ESM format
`build/index.d.ts`	TypeScript type declarations
`build/*.d.ts.map`	Declaration source maps
`build/*.js.map`	JavaScript source maps

Make Targets

Target	Description
`make build`	Clean build: removes `build/`, compiles, emits declarations
`make clean`	Removes `build/` directory and Docker artifacts
`make lint`	Runs markdownlint, eslint, yamllint, jsonlint, prettier
`make test`	Runs unit, integration, and e2e test suites
`make setup`	Install dependencies and git hooks

CI Pipeline

The CI pipeline runs make lint, make test, and make build in sequence. CodeQL static analysis runs on every push and on a weekly schedule. Dependabot monitors dev dependencies for known vulnerabilities.

Dev Dependencies (9)

Package	Purpose
`@asymmetric-effort/jsonlint`	JSON linting
`@asymmetric-effort/yamllint`	YAML linting
`@typescript-eslint/eslint-plugin`	TypeScript ESLint rules
`@typescript-eslint/parser`	TypeScript ESLint parser
`bun-types`	Bun runtime type definitions
`eslint`	JavaScript/TypeScript linting
`markdownlint-cli`	Markdown linting
`prettier`	Code formatting
`typescript`	TypeScript compiler

Security Design

NogginLessDom's security posture stems from architectural decisions, not bolt-on hardening.

Zero Dependencies

The dependencies field is {}. There is no transitive dependency tree to audit, no packages that can be hijacked, and no supply chain to monitor. This eliminates entire categories of attacks: package takeovers, typosquatting, malicious updates, and dependency confusion.

No Dynamic Code Execution

The DOM module parses HTML without eval(), new Function(), or any form of dynamic code execution. HTML input is validated and sanitized through deterministic parsing algorithms, not regular expressions operating on untrusted input.

Path Validation

File operations in the coverage and snapshot modules validate paths before access. Path traversal attacks (e.g., ../../etc/passwd) and symlink-based escapes are detected and rejected.

Version Validation

The release pipeline validates that VERSION matches the semver pattern ^[0-9]+\.[0-9]+\.[0-9]+$ before proceeding, preventing injection through the version string (GHSA-482x-9gr3-8prm).

Minimal Published Surface

The published package contains only the compiled output (build/), LICENSE.txt, and README.md. Source code, tests, documentation, and build configuration are excluded, reducing the surface area available for analysis by potential attackers.

Developer Guide

This section contains documentation for contributors to NogginLessDom. Whether you are fixing a bug, adding a feature, or improving documentation, start here.

Guides

Environment Setup

Prerequisites, cloning the repository, installing dependencies, IDE configuration, and an overview of the project directory structure. Start here if this is your first time working on the project.

Testing

How tests are organized (unit, integration, e2e), how to run them, coverage requirements (>= 98%), writing effective tests, and naming conventions.

Building

The build pipeline from TypeScript source to publishable artifacts. Covers make build, output artifacts (JS, .d.ts, source maps), clean builds, and troubleshooting.

Releasing

The release process: semantic versioning via the VERSION file, make release targets, what each target does, publishing to npm, and the pre-release checklist.

Key Principles for Contributors

Zero runtime dependencies. This is the project's defining constraint. Never add a package to dependencies in package.json. If you think an exception is warranted, open an issue for discussion before writing code.

Dev dependencies are acceptable but must be MIT or MIT-compatible licensed. Keep them minimal.

Test everything. Coverage must remain at or above 98%. Every public API function needs happy-path and error-path tests.

Document everything. If you add or change a public API, update the corresponding API reference in docs/api/.

Follow existing patterns. Look at how existing modules are structured before creating new ones. Consistency matters.

Quick Reference

Task	Command
Install dependencies	`bun install`
Run all tests	`make test`
Run linters	`make lint`
Build	`make build`
Clean build artifacts	`make clean`
Type check only	`bun run typecheck`
Release (patch)	`make release`
Release (minor)	`make release/minor`
Release (major)	`make release/major`

Development Environment Setup

This guide covers everything needed to set up a development environment for working on NogginLessDom.

Prerequisites

Install the following before you begin:

Bun (latest stable)

Bun is the primary runtime and package manager. Install it from bun.sh:

curl -fsSL https://bun.sh/install | bash

Verify:

bun --version

Go 1.22+

Go is used for supporting build and release tooling. Install it from go.dev:

# macOS (Homebrew)
brew install go

# Linux
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Verify:

go version

Docker

Docker is used for containerized builds and clean-room testing. Install from docker.com.

Verify:

docker --version

GNU Make

Make drives the build pipeline. It is pre-installed on most Linux and macOS systems. On Windows, use WSL or install via Chocolatey:

# Verify
make --version

Git

Git is required for version control. Install from git-scm.com.

Cloning and Installing

# Clone the repository
git clone git@github.com:asymmetric-effort/NogginLessDom.git
cd NogginLessDom

# Install dependencies
bun install

Verifying the Setup

Run the linter and test suite to confirm everything is working:

make lint && make test

If both commands pass without errors, your environment is ready.

IDE Setup

VS Code

Recommended extensions:

ESLint (dbaeumer.vscode-eslint) -- Inline linting for TypeScript.
Prettier (esbenp.prettier-vscode) -- Code formatting on save.
EditorConfig (EditorConfig.EditorConfig) -- Consistent formatting from .editorconfig.
Bun (nicolo-ribaudo.vscode-bun) -- Bun runtime support.

Recommended settings.json additions for this workspace:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.preferences.importModuleSpecifier": "relative",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

JetBrains (WebStorm / IntelliJ)

Enable ESLint under Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint. Select "Automatic ESLint configuration."
Enable Prettier under Settings > Languages & Frameworks > JavaScript > Prettier. Check "On save."
The project's .editorconfig is automatically respected.

Vim / Neovim

If using coc.nvim or nvim-lspconfig, configure the TypeScript language server to use the project's tsconfig.json. Add ESLint via coc-eslint or eslint-lsp.

Project Structure

NogginLessDom/
  src/                     # TypeScript source code
    index.ts               # Package entry point; re-exports all modules
    test-runner/           # Test runner wrapping node:test
      index.ts
    assertions/            # Assertion library wrapping node:assert
    dom/                   # Built-in DOM simulation
    mocking/               # Mock functions, spies, and timer mocking
  tests/                   # Test suites
    unit/                  # Unit tests (isolated function/class tests)
    integration/           # Integration tests (module interaction tests)
    e2e/                   # End-to-end tests (full workflow tests)
  build/                   # Compiled output (gitignored)
  docs/                    # Documentation
    api/                   # API reference for each module
    developer/             # Developer/contributor guides
    user/                  # End-user guides
  Makefile                 # Build, test, lint, release targets
  package.json             # Package manifest (zero runtime deps)
  tsconfig.json            # TypeScript compiler configuration
  bunfig.toml              # Bun runtime and test configuration
  VERSION                  # Current version (semver)
  CONTRIBUTING.md          # Contribution guidelines
  SECURITY.md              # Security policy
  LICENSE.txt              # MIT license

Key Files

File	Purpose
`src/index.ts`	Entry point. Exports all public APIs.
`Makefile`	All build, test, lint, and release automation.
`package.json`	npm package manifest. `dependencies` must be `{}`.
`tsconfig.json`	Strict TypeScript config targeting ESNext.
`bunfig.toml`	Bun test config with 98% coverage thresholds.
`VERSION`	Plain text file containing the current semver.

Workflow Summary

A typical development cycle:

Create a feature branch: git checkout -b feature/my-feature
Make changes in src/.
Write or update tests in tests/.
Run make lint to check for style issues.
Run make test to verify all tests pass.
Run make build to verify the build succeeds.
Push and open a pull request.

Testing Guide

This guide covers how tests are organized in NogginLessDom, how to run them, coverage requirements, and best practices for writing effective tests.

Test Structure

Tests are organized into three directories under tests/:

tests/
  unit/           # Isolated tests for individual functions and classes
  integration/    # Tests for interactions between modules
  e2e/            # End-to-end workflow tests

Unit Tests (`tests/unit/`)

Unit tests verify individual functions, methods, and classes in isolation. Each source module should have a corresponding test file or directory:

tests/unit/
  test-runner/
    describe.test.ts
    it.test.ts
    lifecycle.test.ts
  assertions/
    expect.test.ts
    matchers.test.ts
    not.test.ts
    async.test.ts
  dom/
    document.test.ts
    element.test.ts
    node.test.ts
    event.test.ts
    selectors.test.ts
  mocking/
    fn.test.ts
    spyOn.test.ts
    timers.test.ts

Unit tests should:

Test one behavior per test case.
Not depend on other modules (mock dependencies if needed).
Be fast (no I/O, no timers, no network).

Integration Tests (`tests/integration/`)

Integration tests verify that modules work correctly together. For example, testing that the assertion module works properly with the test runner, or that DOM elements created by Document are correctly queried.

tests/integration/
  runner-with-assertions.test.ts
  dom-with-assertions.test.ts
  mocking-with-runner.test.ts

End-to-End Tests (`tests/e2e/`)

End-to-end tests verify complete user workflows. They simulate how a real user would use the library: importing it, writing tests, and running them.

tests/e2e/
  full-test-suite.test.ts
  dom-testing-workflow.test.ts
  migration-compatibility.test.ts

Running Tests

Run All Tests

make test

This runs unit, integration, and e2e tests in sequence. All three suites must pass for the build to be considered green.

Run a Specific Suite

# Unit tests only
bun test tests/unit

# Integration tests only
bun test tests/integration

# E2E tests only
bun test tests/e2e

Run a Specific Test File

bun test tests/unit/assertions/expect.test.ts

Run Tests Matching a Pattern

bun test --grep "should handle null values"

Run Tests with Coverage

Coverage is enabled by default in bunfig.toml. To see coverage output:

bun test --coverage

Coverage Requirements

NogginLessDom enforces strict coverage thresholds. These are configured in bunfig.toml:

[test]
coverage = true
coverageThreshold = { line = 98, function = 98, statement = 98 }

All three metrics -- line coverage, function coverage, and statement coverage -- must be at or above 98%. The CI pipeline will fail if coverage drops below these thresholds.

Why 98%?

A high coverage threshold:

Ensures every code path is exercised, catching edge cases early.
Forces contributors to write error-path tests, not just happy-path tests.
Catches dead code -- if code cannot be reached by tests, it likely should not exist.

The remaining 2% provides room for genuinely untestable code (defensive error handling, platform-specific branches).

Writing Tests

Test Naming Conventions

Use descriptive names that explain the expected behavior:

// Good: describes behavior
it('should return null when element is not found', () => { /* ... */ });
it('should throw TypeError for non-string selectors', () => { /* ... */ });
it('should preserve attribute order after serialization', () => { /* ... */ });

// Bad: too vague
it('works', () => { /* ... */ });
it('test getElementById', () => { /* ... */ });
it('error case', () => { /* ... */ });

Happy Path Tests

Test the expected behavior with valid inputs:

describe('getElementById', () => {
  it('should find an element by its id', () => {
    const doc = new Document();
    const div = doc.createElement('div');
    div.id = 'target';
    doc.appendChild(div);

    const result = doc.getElementById('target');
    expect(result).toBe(div);
  });
});

Error Path Tests

Test behavior with invalid, missing, or boundary-condition inputs:

describe('getElementById', () => {
  it('should return null when no element has the given id', () => {
    const doc = new Document();
    expect(doc.getElementById('nonexistent')).toBeNull();
  });

  it('should return null for empty string id', () => {
    const doc = new Document();
    expect(doc.getElementById('')).toBeNull();
  });
});

Testing Async Code

Use async/await in your test functions:

it('should resolve with user data', async () => {
  const user = await fetchUser(1);
  expect(user.name).toBe('Alice');
});

it('should reject for invalid user id', async () => {
  await expect(fetchUser(-1)).rejects.toThrow('invalid id');
});

Testing Events

it('should fire click handlers', () => {
  const doc = new Document();
  const button = doc.createElement('button');
  const handler = fn();

  button.addEventListener('click', handler);
  button.dispatchEvent(new Event('click'));

  expect(handler.mock.calls).toHaveLength(1);
});

Testing with Mocks

it('should call the logger on error', () => {
  const logger = { error: fn() };
  const service = new Service(logger);

  service.processInvalid(null);

  expect(logger.error.mock.calls).toHaveLength(1);
  expect(logger.error.mock.calls[0][0]).toMatch(/invalid/i);
});

Best Practices

One assertion concept per test. A test can have multiple expect calls, but they should all verify the same logical behavior.

Arrange-Act-Assert. Structure each test in three phases: set up the state, perform the action, check the result.

Do not test implementation details. Test observable behavior (return values, side effects, state changes), not internal method calls or private state.

Clean up after yourself. Use afterEach to restore mocks, fake timers, and any global state changes.

Avoid test interdependence. Each test should be independent and self-contained. Do not rely on the execution order of other tests.

Keep tests fast. Unit tests should complete in milliseconds. Avoid I/O, network calls, and real timers in unit tests.

Build Process

This guide covers the NogginLessDom build pipeline, from TypeScript source to publishable artifacts.

Overview

The build process compiles TypeScript source in src/ into JavaScript, type declarations, and source maps in build/. The pipeline uses Bun for JavaScript bundling and the TypeScript compiler (tsc) for declaration generation.

src/**/*.ts  -->  bun build  -->  build/*.js
             -->  tsc        -->  build/*.d.ts + *.d.ts.map + *.js.map

Building

Full Build

make build

This runs a clean build:

Clean. Removes the build/ directory and any stale Docker artifacts.
Bundle. Runs bun build src/index.ts --outdir build --target node to produce the JavaScript output. Bun bundles all internal imports into a single file targeting the Node.js runtime.
Declarations. Runs tsc --emitDeclarationOnly to generate .d.ts type declaration files and declaration source maps.

Clean Only

make clean

Removes the build/ directory and recreates it empty. Also removes any Docker containers and images related to the project.

Output Artifacts

After a successful build, the build/ directory contains:

File	Description
`index.js`	Bundled JavaScript (ESM format, Node target)
`index.d.ts`	TypeScript type declarations
`index.d.ts.map`	Declaration source map (for IDE navigation)
`index.js.map`	JavaScript source map (for debugging)

Additional declaration files are generated for each sub-module:

File	Description
`test-runner/index.d.ts`	Test runner type declarations
`assertions/index.d.ts`	Assertions type declarations
`dom/index.d.ts`	DOM simulation type declarations
`mocking/index.d.ts`	Mocking utilities type declarations

Build Configuration

TypeScript Configuration (`tsconfig.json`)

Key compiler options:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "build",
    "rootDir": "src",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "isolatedModules": true
  }
}

Notable settings:

strict: true -- Enables all strict type-checking options.
noUncheckedIndexedAccess: true -- Adds undefined to index signatures, catching potential runtime errors at compile time.
moduleResolution: "bundler" -- Uses Bun-compatible module resolution.
isolatedModules: true -- Ensures each file can be independently transpiled.

Package Exports (`package.json`)

The built package uses ESM exports:

{
  "type": "module",
  "main": "build/index.js",
  "types": "build/index.d.ts",
  "exports": {
    ".": {
      "import": "./build/index.js",
      "types": "./build/index.d.ts"
    }
  },
  "files": [
    "build/",
    "LICENSE.txt",
    "README.md"
  ]
}

The files array controls what is included in the published npm package. Only the build/ directory, license, and readme are published -- source code, tests, docs, and configuration files are excluded.

Build Prerequisites

Before running make build, ensure:

Bun is installed -- The bundler.
TypeScript is installed -- Should be present after bun install (it is a dev dependency).
bun install has been run -- Dev dependencies must be installed.

Troubleshooting

"Cannot find module" errors during build

This usually means bun install has not been run, or a new import was added without updating the export map. Run bun install and try again.

Type declaration errors

If tsc --emitDeclarationOnly fails, run bun run typecheck for more detailed error output. Common causes:

Missing type annotations on exported functions.
Implicit any types (forbidden by strict: true).
Circular type references.

Stale build artifacts

If the build output seems wrong or outdated, run make clean before make build to ensure a fresh build.

Docker-related errors during clean

The make clean target removes Docker containers and images matching the project name. If Docker is not running, you may see warnings -- these are harmless and do not affect the build.

Verifying the Build

After building, verify the output:

# Check that the entry point exists
ls -la build/index.js

# Check that type declarations exist
ls -la build/index.d.ts

# Verify the package can be imported
bun -e "import { describe, expect, Document } from './build/index.js'; console.log('OK')"

Release Process

This guide covers how NogginLessDom releases are created, versioned, tagged, and published.

Semantic Versioning

NogginLessDom follows Semantic Versioning 2.0.0. The current version is stored in a plain text file named VERSION at the project root. This file contains a single line with the version number (e.g., 0.0.1).

Version format: MAJOR.MINOR.PATCH

MAJOR -- Incremented for backwards-incompatible API changes.
MINOR -- Incremented for new features that are backwards-compatible.
PATCH -- Incremented for backwards-compatible bug fixes.

Release Targets

The Makefile provides three release targets:

`make release` (Patch Release)

Bumps the patch version. Use for bug fixes and minor improvements that do not change the public API.

make release
# 0.0.1 -> 0.0.2

`make release/minor` (Minor Release)

Bumps the minor version and resets the patch version to 0. Use for new features that are backwards-compatible.

make release/minor
# 0.0.2 -> 0.1.0

`make release/major` (Major Release)

Bumps the major version and resets both minor and patch to 0. Use for breaking API changes.

make release/major
# 0.1.0 -> 1.0.0

What Each Release Target Does

All three targets perform the same sequence of steps:

Read the current version from the VERSION file.
Bump the appropriate version component.
Write the new version to the VERSION file.
Update the version field in package.json to match.
Stage both VERSION and package.json.
Commit with the message chore: release vX.Y.Z.
Tag the commit with vX.Y.Z.

The release target does not push to the remote or publish to npm. Those steps are done manually after verifying the release.

Publishing to npm

After a release commit and tag have been created:

# Push the commit and tag to the remote
git push origin main --tags

# Publish to npm
npm publish --access public

The npm publish command uses the files field in package.json to determine what is included in the tarball:

build/ -- Compiled JavaScript, type declarations, and source maps.
LICENSE.txt -- MIT license.
README.md -- Package readme.

Source code, tests, documentation, and configuration files are excluded from the published package.

Scoped Package

NogginLessDom is published under the @asymmetric-effort scope. The --access public flag is required for the first publish of a scoped package. Subsequent publishes do not require it (but including it is harmless).

Pre-Release Checklist

Before creating a release, verify each of these items:

Code Quality

[ ] All tests pass: make test
[ ] All linters pass: make lint
[ ] Build succeeds: make build
[ ] Test coverage is >= 98%
[ ] Type checking passes: bun run typecheck

Documentation

[ ] API documentation is up to date for any changed APIs.
[ ] CHANGELOG (if maintained) is updated.
[ ] README.md accurately reflects the current state of the project.

Dependencies

[ ] dependencies in package.json is empty ({}).
[ ] No new dev dependencies have been added without review.
[ ] Existing dev dependencies are up to date.

Security

[ ] No known vulnerabilities in dev dependencies.
[ ] No use of eval(), Function(), or dynamic code execution.
[ ] No secrets or credentials in the codebase.

Version

[ ] The version bump is appropriate for the changes (patch/minor/major).
[ ] The VERSION file matches package.json version.

Post-Release Steps

After publishing:

Verify the published package by installing it in a fresh project:

``bash mkdir /tmp/test-install && cd /tmp/test-install bun init -y bun add @asymmetric-effort/nogginlessdom bun -e "import { describe, expect } from '@asymmetric-effort/nogginlessdom'; console.log('OK')" ``

Create a GitHub release (optional but recommended) linking to the tag with release notes summarizing the changes.

Announce the release in any relevant channels.

Hotfix Process

If a critical bug is found after release:

Create a branch from the release tag: git checkout -b hotfix/description vX.Y.Z
Fix the bug and add tests.
Run the full pre-release checklist.
Use make release to bump the patch version.
Push and publish.

User Guide

This section is for end users who are adopting NogginLessDom in their projects. Whether you are starting fresh or migrating from an existing testing framework, these guides will help you get up and running.

Guides

Installation

How to install NogginLessDom via Bun or npm, verify the installation, and configure TypeScript. Covers peer dependency requirements (there are none) and what gets installed.

Configuration

How to configure test file patterns, coverage thresholds, DOM options, and custom reporters through bunfig.toml and other configuration files.

Why NogginLessDom?

Zero Dependencies

NogginLessDom has no runtime dependencies. The dependencies field in package.json is {}. When you install this package, you get exactly one package -- no transitive dependency tree, no supply chain risk.

This matters because:

Security. Every dependency is a potential attack vector. Package takeovers, typosquatting, and malicious updates in transitive dependencies are real threats. NogginLessDom eliminates this surface entirely.
Stability. No dependency can break your build with a bad release. Your test framework is as stable as Node.js itself.
Speed. No dependency resolution overhead. Installs are fast. Lock file churn is zero.

Built on Node.js Built-ins

The test runner wraps node:test. The assertion library wraps node:assert. These are battle-tested, maintained by the Node.js team, and guaranteed to be available in every Node.js environment. NogginLessDom adds a familiar API layer on top without reinventing the core functionality.

Familiar Testing API

NogginLessDom provides the describe, it, expect, fn, and spyOn APIs that developers already know from modern testing frameworks. The interface follows widely adopted conventions, so getting started is straightforward.

Full-Featured DOM Simulation

The built-in DOM simulation means you do not need any separate DOM library. Create documents, query elements, dispatch events, and test UI logic -- all from the same zero-dependency package.

Quick Start

bun add -d @asymmetric-effort/nogginlessdom

import { describe, it, expect } from '@asymmetric-effort/nogginlessdom';

describe('my first test', () => {
  it('works', () => {
    expect(1 + 1).toBe(2);
  });
});

bun test

For more detail, see the Getting Started guide.

Installation

This guide covers installing NogginLessDom, verifying the installation, and configuring TypeScript support.

Installing with Bun

Bun is the recommended package manager and runtime:

bun add -d @asymmetric-effort/nogginlessdom

The -d flag installs it as a dev dependency, which is appropriate since testing frameworks are not needed at runtime in your application.

Installing with npm

npm install --save-dev @asymmetric-effort/nogginlessdom

Installing with yarn

yarn add -D @asymmetric-effort/nogginlessdom

Installing with pnpm

pnpm add -D @asymmetric-effort/nogginlessdom

Peer Dependencies

NogginLessDom has no peer dependencies and no runtime dependencies. The only thing installed is the package itself. There is no transitive dependency tree to audit, lock, or worry about.

{
  "dependencies": {}
}

This is a core design principle. See the Architecture document for the reasoning behind this decision.

Requirements

Node.js >= 20.0.0
Bun (recommended) or any Node.js-compatible runtime

Verifying the Installation

After installing, verify that the package is importable:

bun -e "import { describe, it, expect } from '@asymmetric-effort/nogginlessdom'; console.log('NogginLessDom installed successfully')"

Or with Node.js:

node -e "import('@asymmetric-effort/nogginlessdom').then(m => console.log('OK:', Object.keys(m).length, 'exports'))"

You should see confirmation that the package loaded and its exports are accessible.

TypeScript Setup

NogginLessDom is written in TypeScript and ships with type declarations (*.d.ts files). No additional @types/ packages are needed.

Basic Imports

import {
  describe,
  it,
  test,
  expect,
  beforeEach,
  afterEach,
  beforeAll,
  afterAll,
  Document,
  Element,
  Node,
  TextNode,
  Event,
  fn,
  spyOn,
  useFakeTimers,
  useRealTimers,
} from '@asymmetric-effort/nogginlessdom';

Import only what you need:

// Just the test runner and assertions
import { describe, it, expect } from '@asymmetric-effort/nogginlessdom';

// Just the DOM simulation
import { Document, Element, Event } from '@asymmetric-effort/nogginlessdom';

// Just mocking utilities
import { fn, spyOn, vi } from '@asymmetric-effort/nogginlessdom';

// Coverage tools
import { startCoverage, stopCoverage } from '@asymmetric-effort/nogginlessdom';

// Dependency analysis
import { detectCircularImports, buildDependencyGraph } from '@asymmetric-effort/nogginlessdom';

TypeScript Configuration

NogginLessDom targets ESNext and uses ESM modules. Your tsconfig.json should be compatible with these settings. A minimal configuration:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true
  }
}

If you are using Bun, add bun-types to your types array for full runtime type support:

{
  "compilerOptions": {
    "types": ["bun-types"]
  }
}

What Gets Installed

The published package contains:

Path	Contents
`build/index.js`	Bundled JavaScript (ESM, Node target)
`build/index.d.ts`	TypeScript type declarations
`build/*.map`	Source maps for debugging and IDE navigation
`LICENSE.txt`	MIT license
`README.md`	Package readme

Source code, tests, documentation, and build configuration are not included in the published package. The install footprint is minimal.

Updating

# Bun
bun update @asymmetric-effort/nogginlessdom

# npm
npm update @asymmetric-effort/nogginlessdom

# yarn
yarn upgrade @asymmetric-effort/nogginlessdom

# pnpm
pnpm update @asymmetric-effort/nogginlessdom

Uninstalling

# Bun
bun remove @asymmetric-effort/nogginlessdom

# npm
npm uninstall @asymmetric-effort/nogginlessdom

# yarn
yarn remove @asymmetric-effort/nogginlessdom

# pnpm
pnpm remove @asymmetric-effort/nogginlessdom

Configuration

NogginLessDom is designed to work with minimal configuration. Most settings are managed through Bun's configuration file (bunfig.toml), standard TypeScript configuration, and environment variables.

Test File Patterns

By default, Bun discovers test files matching these patterns:

**/*.test.ts
**/*.test.tsx
**/*.spec.ts
**/*.spec.tsx

Files in node_modules/ are excluded. You can override test file discovery by passing explicit paths:

# Run tests in a specific directory
bun test tests/unit

# Run a specific test file
bun test tests/unit/assertions/expect.test.ts

# Run multiple specific files
bun test tests/unit/dom/element.test.ts tests/unit/dom/document.test.ts

Programmatic Test File Filtering

You can set a file pattern programmatically:

import {
  setTestFilePattern,
  clearTestFilePattern,
  getTestFilePattern,
} from '@asymmetric-effort/nogginlessdom';

// Only run test files matching this glob
setTestFilePattern('**/dom/**/*.test.ts');

// Check current pattern
console.log(getTestFilePattern());

// Clear the pattern
clearTestFilePattern();

TypeScript Configuration

NogginLessDom targets ESNext and uses ESM modules. Your tsconfig.json should be compatible with these settings:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true
  }
}

If you are using Bun, add bun-types to your types array for full runtime type support:

{
  "compilerOptions": {
    "types": ["bun-types"]
  }
}

NogginLessDom ships with TypeScript type declarations (*.d.ts). No additional @types/ packages are needed.

Coverage Configuration

Coverage is configured in bunfig.toml at the project root.

Basic Coverage

[test]
coverage = true

Coverage Thresholds

Set minimum coverage percentages. The test run fails if any threshold is not met:

[test]
coverage = true
coverageThreshold = { line = 90, function = 90, statement = 90 }

Threshold Field	Description
`line`	Minimum percentage of lines covered
`function`	Minimum percentage of functions covered
`statement`	Minimum percentage of statements covered

Coverage Providers

NogginLessDom supports two coverage providers:

V8 -- Uses the V8 JavaScript engine's built-in coverage instrumentation. Fast and accurate for Node.js and Bun environments.
Istanbul -- Traditional instrumentation-based coverage. Useful for compatibility with existing toolchains.

Coverage Reporters

The framework includes 11 coverage reporters:

Reporter	Description
`text`	Terminal table output
`text-summary`	Condensed terminal summary
`json`	JSON coverage data
`json-summary`	JSON coverage summary
`lcov`	LCOV format with optional HTML
`lcov-only`	LCOV format without HTML
`html`	Full HTML coverage report
`html-spa`	Single-page application HTML report
`clover`	Clover XML format
`cobertura`	Cobertura XML format
`teamcity`	TeamCity service messages

Per-Test Coverage

Track coverage on a per-test basis using the programmatic API:

import {
  startCoverage,
  takeCoverage,
  stopCoverage,
  reportCoverage,
} from '@asymmetric-effort/nogginlessdom';

startCoverage();
// ... run code under test ...
const data = takeCoverage();
stopCoverage();
reportCoverage(data);

Reporter Configuration

NogginLessDom provides built-in test reporters that can be configured programmatically:

import {
  configureReporters,
  DefaultReporter,
  VerboseReporter,
  DotReporter,
  JsonReporter,
  SilentReporter,
} from '@asymmetric-effort/nogginlessdom';

Available Reporters

Reporter	Description
`DefaultReporter`	Standard output with pass/fail indicators
`VerboseReporter`	Detailed output with timing and nested suites
`DotReporter`	Minimal dot-per-test output for CI
`JsonReporter`	Machine-readable JSON output
`SilentReporter`	Suppresses all output (useful for programmatic
	use)

Bun Test Reporters

You can also use Bun's built-in reporter flags:

# Default reporter
bun test

# JUnit reporter (for CI systems)
bun test --reporter junit

# Custom reporter module
bun test --reporter ./reporters/custom.ts

Watch Mode Configuration

Re-run tests automatically when files change:

bun test --watch

You can configure watch mode in bunfig.toml:

[test]
# watch = false

Combine watch mode with test filtering for focused development:

bun test --watch --grep "DOM element"

Programmatic Watch API

import { watchTests } from '@asymmetric-effort/nogginlessdom';

const controller = watchTests({
  // Watch options
});

Test Filtering

Command-Line Filtering

# Run tests matching a name pattern
bun test --grep "should handle"

# Run tests in a specific file
bun test path/to/file.test.ts

# Run tests in a specific directory
bun test tests/unit/dom

Programmatic Name Filtering

import {
  setTestNamePattern,
  clearTestNamePattern,
  getTestNamePattern,
} from '@asymmetric-effort/nogginlessdom';

// Only run tests whose names match this regex
setTestNamePattern(/DOM.*element/i);

// Check current pattern
console.log(getTestNamePattern());

// Clear the filter
clearTestNamePattern();

Test Modifiers

Filter tests directly in your test code:

import { describe, it } from '@asymmetric-effort/nogginlessdom';

describe('Feature', () => {
  it('runs normally', () => { /* ... */ });
  it.skip('is skipped', () => { /* ... */ });
  it.only('runs exclusively', () => { /* ... */ });
  it.todo('is planned for later');
});

Conditional execution:

import { describe, it } from '@asymmetric-effort/nogginlessdom';

const isCI = process.env.CI === 'true';

describe('Platform tests', () => {
  it.skipIf(isCI)('skipped in CI', () => { /* ... */ });
  it.runIf(!isCI)('only runs locally', () => { /* ... */ });
});

Mock Auto-Cleanup Configuration

Configure how mock functions are automatically cleaned up between tests:

import {
  configureMockBehavior,
  getMockConfig,
} from '@asymmetric-effort/nogginlessdom';

configureMockBehavior({
  // Configuration options for mock behavior
});

// Check current mock configuration
const config = getMockConfig();

Auto-Cleanup with Lifecycle Hooks

Install automatic mock cleanup in your test setup:

import { installAutoMockCleanup } from '@asymmetric-effort/nogginlessdom';

// Automatically restore all mocks after each test
installAutoMockCleanup();

This registers afterEach hooks that call restoreAllMocks() so mocks do not leak between tests.

Test Isolation Configuration

Control how tests are isolated from each other:

import { configureIsolation } from '@asymmetric-effort/nogginlessdom';
import type { IsolationConfig } from '@asymmetric-effort/nogginlessdom';

const config: IsolationConfig = {
  // Isolation settings
};

configureIsolation(config);

Serial Execution

Force tests to run sequentially instead of concurrently:

import {
  setSerialMode,
  getSerialMode,
} from '@asymmetric-effort/nogginlessdom';

// Enable serial execution
setSerialMode(true);

// Check current mode
console.log(getSerialMode()); // true

This is useful when tests share state or interact with resources that do not support concurrent access.

Test Setup Files

Run setup code before all tests by creating a preload file:

[test]
preload = ["./tests/setup.ts"]

Example tests/setup.ts:

import {
  Document,
  installAutoMockCleanup,
} from '@asymmetric-effort/nogginlessdom';

// Auto-cleanup mocks after each test
installAutoMockCleanup();

// Create a global document available to all tests
globalThis.testDocument = new Document();

DOM Configuration

The DOM simulation does not require configuration for basic use. Simply import and instantiate:

import { Document } from '@asymmetric-effort/nogginlessdom';

const doc = new Document();

Shared Document via Lifecycle Hooks

import {
  describe,
  beforeEach,
  Document,
} from '@asymmetric-effort/nogginlessdom';

describe('Component Tests', () => {
  let doc: Document;

  beforeEach(() => {
    doc = new Document();
    const root = doc.createElement('div');
    root.id = 'root';
    doc.appendChild(root);
  });

  // tests use `doc` here...
});

innerHTML for Complex Structures

const container = doc.createElement('div');
container.innerHTML = `
  <header>
    <nav>
      <a href="/">Home</a>
      <a href="/about">About</a>
    </nav>
  </header>
  <main>
    <h1>Welcome</h1>
  </main>
`;
doc.appendChild(container);

Dependency Analysis

NogginLessDom includes built-in tools for analyzing your project's import structure. These can be enabled via environment variables or the programmatic API.

Circular Dependency Detection

Detect circular import chains that cause initialization issues and break module mocking.

# Warn on cycles (continues test run)
DETECT_CYCLES=1 bun test

# Fail on cycles (exits before running tests)
DETECT_CYCLES=strict bun test

Programmatic API:

import {
  detectCircularImports,
  formatCycleReport,
  configureCycleDetection,
} from '@asymmetric-effort/nogginlessdom';

// Detect cycles in specific files
const cycles = detectCircularImports(['src/index.ts']);
if (cycles.length > 0) {
  console.log(formatCycleReport(cycles));
}

// Enable during test runs
configureCycleDetection({ enabled: true, strict: true });

Import Depth Analysis

Analyze the depth of your import chains to catch barrel file explosion and deeply nested module structures.

# Warn if any file exceeds depth 8
IMPORT_DEPTH_THRESHOLD=8 bun test

# Strict mode
IMPORT_DEPTH_THRESHOLD=8:strict bun test

Programmatic API:

import { analyzeImportDepth } from '@asymmetric-effort/nogginlessdom';

const result = analyzeImportDepth(['src/index.ts'], { threshold: 10 });
console.log('Max depth:', result.maxDepth);
console.log('Average depth:', result.averageDepth.toFixed(1));
for (const entry of result.filesExceedingThreshold) {
  console.log(`  ${entry.file}: depth ${entry.depth}`);
  console.log(`    Chain: ${entry.longestChain.join(' -> ')}`);
}

Unused Import Detection

Find imports that are declared but never referenced in your source files.

# Warn on unused imports
DETECT_UNUSED_IMPORTS=1 bun test

# Fail on unused imports
DETECT_UNUSED_IMPORTS=strict bun test

Programmatic API:

import {
  detectUnusedImports,
  formatUnusedImportReport,
} from '@asymmetric-effort/nogginlessdom';

const unused = detectUnusedImports(['src/**/*.ts']);
if (unused.length > 0) {
  console.log(formatUnusedImportReport(unused));
}

Configuration options:

import {
  configureUnusedImportDetection,
} from '@asymmetric-effort/nogginlessdom';

configureUnusedImportDetection({
  enabled: true,
  strict: false,
  ignoreTypeImports: true,
  ignoreSideEffectImports: true,
  exclude: ['**/*.d.ts'],
});

Dependency Graph Visualization

Export your project's import graph for visualization and analysis.

# Write JSON graph after tests
EXPORT_DEPENDENCY_GRAPH=deps.json bun test

# Generate Graphviz DOT
EXPORT_DEPENDENCY_GRAPH=deps.dot bun test

# Generate Mermaid
EXPORT_DEPENDENCY_GRAPH=deps.mmd bun test

Programmatic API:

import {
  buildDependencyGraph,
  exportGraphJSON,
  exportGraphDOT,
  exportGraphMermaid,
  saveGraph,
} from '@asymmetric-effort/nogginlessdom';
import * as fs from 'node:fs';

const graph = buildDependencyGraph(['src/index.ts']);

// JSON export
fs.writeFileSync('deps.json', exportGraphJSON(graph, true));

// Graphviz (render with: dot -Tpng deps.dot -o deps.png)
fs.writeFileSync('deps.dot', exportGraphDOT(graph));

// Mermaid (paste into GitHub markdown)
console.log(exportGraphMermaid(graph));

// Save directly to a file (format inferred from extension)
saveGraph(graph, 'deps.json');

// Summary
console.log('Files:', graph.summary.totalFiles);
console.log('Max depth:', graph.summary.maxDepth);
console.log('Cycles:', graph.summary.cycleCount);
console.log('Hub files:', graph.summary.hubFiles.join(', '));

Environment Variables Reference

Variable	Values	Description
`NODE_ENV`	`test`	Set to `test` during test runs (Bun default)
`CI`	`true`	Set in CI environments; can affect reporter and snapshot
		behavior
`BUN_DEBUG`	`true`	Enable Bun debug output
`DETECT_CYCLES`	`1`, `strict`	Enable circular dependency detection; `strict` fails the run
`IMPORT_DEPTH_THRESHOLD`	`N`, `N:strict`	Warn or fail if import depth exceeds N
`DETECT_UNUSED_IMPORTS`	`1`, `strict`	Enable unused import detection; `strict` fails the run
`EXPORT_DEPENDENCY_GRAPH`	file path	Export dependency graph to the given file (JSON, DOT, or
		Mermaid based on extension)