@hyperfrontend/testing§

What is @hyperfrontend/testing?

@hyperfrontend/testing is a thin layer over Node's built-in test runner. It supplies the four things a suite written in the Jest idiom needs and node:test does not have: a describe and it carrying Jest's modifiers, an expect with Jest's matcher names, a jest namespace for mock functions, spies and fake timers, and a loader that honours jest.mock under native ES modules. Everything Node already provides, the runner, the lifecycle hooks, the assertion error, the coverage collector, is used as it is.

It is not Jest and does not try to be. The matcher set is closed, there are no snapshots, no watch mode and no HTML coverage report, and the places where behaviour differs are listed in this document rather than papered over. What it offers is the familiar shape of a Jest spec on a runtime that ships with Node, with no test framework installed.

Key Features

Why Use @hyperfrontend/testing?

Fewer dependencies, same habits

Node ships a test runner, an assertion module, a module mocking facility, fake timers and a coverage collector. What it does not ship is the shape of a Jest spec, and that shape is what most teams have in their fingers. This package supplies the shape and nothing else, so the install is one package with no runtime dependencies instead of a framework, a transformer and a reporter.

A migration, not a rewrite

Suites written against Jest keep their describe blocks, matchers, mock functions and jest.mock declarations as written. The lifecycle hooks come from node:test, the configuration file changes shape, and the differences that remain are listed in Migrating from Jest rather than discovered one failing test at a time.

Coverage you can trust

Node's coverage omits files no test loaded and counts a re-evaluated module once per evaluation. The runner merges the lcov records per file, judges thresholds on the merged totals, and fails a run that left an included source file unmeasured, so a full-coverage gate guarantees what it says.

With thanks to Jest

Jest set the vocabulary this package speaks. expect(value).toEqual(...), jest.fn() and jest.mock('./module') read the way they do because Jest made them read that way for a decade of JavaScript developers, and the familiarity that gives a new team member is Jest's achievement, not this package's. Jest remains the fuller tool, with snapshots, a watch mode, custom matchers, an interactive runner and an ecosystem of reporters and environments. This package is for the case where Node's built-ins are enough and the familiar syntax is what you want to keep.

Who it is for

Teams moving suites written against Jest onto Node's built-in runner, and anyone who wants Jest-style assertions and mocks with no test framework installed. A project that depends on snapshot testing, expect.extend, watch mode or an HTML coverage report should keep Jest, or choose a framework that provides them.

Installation

npm install --save-dev @hyperfrontend/testing

The package needs Node.js 22.18 or later: the preload installs synchronous module hooks and loads TypeScript specs through Node's own type stripping, neither of which older releases provide. It declares no runtime dependencies.

A DOM is opt-in. Install jsdom alongside the package when a suite needs document; the /dom entry imports it, and nothing else does.

npm install --save-dev jsdom

Quick Start

A spec

import { afterEach, beforeEach, before as beforeAll, after as afterAll } from 'node:test'
import { describe, expect, it, jest } from '@hyperfrontend/testing'
import { createCart } from './cart'

jest.mock('./pricing', () => ({
  priceOf: (sku: string) => (sku === 'tea' ? 3 : 5),
}))

describe('cart', () => {
  let cart: ReturnType<typeof createCart>

  beforeEach(() => {
    cart = createCart()
  })

  it('totals the priced lines', () => {
    cart.add('tea', 2)
    expect(cart.total()).toBe(6)
  })

  it.each([
    ['tea', 3],
    ['coffee', 5],
  ])('prices %s at %d', (sku: string, price: number) => {
    cart.add(sku, 1)
    expect(cart.total()).toBe(price)
  })

  it('notifies subscribers once per change', () => {
    const onChange = jest.fn()
    cart.subscribe(onChange)
    cart.add('tea', 1)
    expect(onChange).toHaveBeenCalledTimes(1)
    expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ total: 3 }))
  })
})

Lifecycle hooks come straight from node:test, which already has them; its before and after are what Jest calls beforeAll and afterAll. Take describe and it from this package even in files that use no modifier: it is the package's it that resets the assertion counter and checks expect.assertions once the body settles, and a spec running on Node's own it would declare a count nobody verifies. Nothing is global: expect and jest are imports too.

Running with node --test

node --import @hyperfrontend/testing/hooks --test 'src/**/*.spec.ts'

The /hooks preload is what makes the spec above loadable: it resolves extensionless and aliased specifiers, applies specifier redirects, and reads the jest.mock calls out of each spec before its imports link. Add the /dom preload after it when a suite needs a browser-shaped global, and --test-only when a suite relies on .only:

node --import @hyperfrontend/testing/hooks \
  --import @hyperfrontend/testing/dom \
  --test 'src/**/*.browser.spec.ts'

Running from a configuration

A test.config.ts takes the place of a Jest configuration. Each environment is its own node --test run, selecting its own files and loading its own setup modules; the coverage settings apply to the project as a whole:

import type { TestConfig } from '@hyperfrontend/testing/runner'

const config: TestConfig = {
  environments: [
    {
      name: 'node',
      testMatch: ['src/**/*.spec.ts'],
      testIgnore: ['**/*.browser.spec.ts'],
    },
    {
      name: 'browser',
      testMatch: ['src/**/*.browser.spec.ts'],
      dom: true,
      setupFiles: ['test.setup.ts'],
    },
  ],
  coverageInclude: ['src/**/*.ts'],
  coverageExclude: ['src/**/index.ts'],
  coverageThresholds: { lines: 100, branches: 95, functions: 100 },
  moduleNameMapper: { '^@app/(.*)$': '<rootDir>/src/$1' },
  testTimeout: 10_000,
}

export default config

A short script drives it. runProjectTests spawns the runs, merges the reports and judges them; the script decides what to print and what the exit code is:

import { runProjectTests } from '@hyperfrontend/testing/runner'
import config from './test.config.ts'

const outcome = runProjectTests(config, {
  workspaceRoot: import.meta.dirname,
  projectRoot: import.meta.dirname,
  coverageDir: `${import.meta.dirname}/coverage`,
})

for (const row of outcome.coverageTable) console.log(row)
for (const failure of outcome.failures) console.error(failure)
process.exitCode = outcome.success ? 0 : 1

node run-tests.ts

The run leaves lcov.<environment>.info per environment and a merged lcov.info in the coverage directory, with paths relative to the workspace root so a coverage service can match them to the repository. A package script, a task runner target or a CI step can each be the driver; the package ships no command line of its own.

API Overview

The root entry is the spec surface. describe and it wrap their node:test namesakes and add what Node lacks: .each over an array of rows (an array row is spread across the parameters, anything else arrives as one argument, and the title takes %s, %d, %i, %f, %j, %o, %p, %# and %%), .only and .skip on both, and .todo, .concurrent and .failing on it. A body may take the done callback; a trailing number is the per-test timeout in milliseconds.

expect carries a closed set of matchers, small enough to list. Equality and identity: toBe, toEqual, toStrictEqual, toMatchObject. Presence and type: toBeDefined, toBeUndefined, toBeNull, toBeNaN, toBeTruthy, toBeFalsy, toBeInstanceOf. Numbers: toBeGreaterThan, toBeGreaterThanOrEqual, toBeLessThan, toBeLessThanOrEqual, toBeCloseTo.

Collections and strings: toHaveLength, toContain, toContainEqual, toMatch, toHaveProperty. Mocks: toHaveBeenCalled, toHaveBeenCalledTimes, toHaveBeenCalledWith, toHaveBeenLastCalledWith, toHaveBeenNthCalledWith. Errors: toThrow and its alias toThrowError, accepting a message fragment, a pattern, an error class, an error whose message must match, or an object shape.

Every matcher is reachable through .not, and through .resolves and .rejects, which await the subject first and return promises. The statics are the asymmetric matchers expect.any, expect.anything, expect.objectContaining, expect.arrayContaining, expect.stringContaining, expect.stringMatching and expect.closeTo, their negations under expect.not, and the counters expect.assertions and expect.hasAssertions.

A failed matcher throws Node's own AssertionError with its actual, expected and operator fields filled in, so reporters and editors treat it like any node:assert failure. The comparison behind the matchers is exported as equals and matchesSubset for code that needs the same answer outside an assertion.

jest is one object with three jobs. Mocks: jest.fn returns a MockFn whose mock record holds calls, results, instances, lastCall and invocationCallOrder, and which takes mockImplementation, mockReturnValue, mockResolvedValue, mockRejectedValue, each with a once-only variant, plus mockReturnThis, mockName, mockClear, mockReset and mockRestore; jest.spyOn replaces a method, or a getter or setter, with a mock that calls through until restored; jest.mocked narrows a value for the type checker; and clearAllMocks, resetAllMocks and restoreAllMocks reach every mock created in the process.

Timers: useFakeTimers installs Node's fake clock over setTimeout, setInterval, setImmediate and Date, taking doNotFake and now; advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runOnlyPendingTimers, clearAllTimers, setSystemTime and useRealTimers drive it. Modules: jest.mock and jest.unmock are read out of the spec's source by the preload and have no runtime work left to do, jest.doMock registers a replacement for modules imported after it, jest.requireActual and jest.requireMock read the real module and the factory's product, and jest.resetModules makes later dynamic imports evaluate their target again.

The other entries are the machinery around a run, and the root entry never re-exports the two that act on import. /hooks is the node --import preload that installs the resolution hooks. /dom is the preload that installs the jsdom window. /reporter is Node's spec reporter minus the per-evaluation coverage summary. /runner holds runProjectTests, the pieces it is built from (buildRunPlan, withDefaults, BASELINE_COVERAGE_EXCLUDE) and the configuration types TestConfig, TestEnvironment, CoverageThresholds, RunContext and RunOutcome.

/coverage holds the lcov merge (mergeLcov, renderLcov), the arithmetic (fileTotals, overallTotals, percentOf, uncoveredRanges), the gate (findThresholdShortfalls, renderCoverageTable) and the completeness check (findUnmeasuredFiles).

Every option, type and signature is in the API reference.

Migrating from Jest

What stays

describe and it with .each, .only, .skip, .todo, .concurrent and .failing; expect with the matchers listed above, the asymmetric matchers, .not, .resolves, .rejects, expect.assertions and expect.hasAssertions; jest.fn, jest.spyOn, jest.mocked and the three *AllMocks resets; the fake timer controls; jest.mock, jest.unmock, jest.doMock, jest.requireActual, jest.requireMock and jest.resetModules; moduleNameMapper and setupFiles in the configuration.

What changes

• Imports. Nothing is global. describe, it, expect and jest are imported from the package; there is no test alias, so import it under that name if a suite uses it. The hooks come from node:test, with before and after standing in for beforeAll and afterAll, and a hook timeout is passed as { timeout } rather than a trailing number.
• Configuration. A test.config.ts exporting a TestConfig replaces the Jest configuration. Environments select files by glob instead of by docblock, a DOM is a per-environment flag, and setupFilesAfterEnv becomes setupFiles. The default timeout is 30 seconds and there is no jest.setTimeout; set testTimeout or pass a trailing timeout to one test.
• Coverage. The provider is V8 through Node's collector, not istanbul. There is no statements metric, so a statements threshold is carried by lines; branch percentages read lower because V8 counts the untaken side of default parameters and optional chaining; /* istanbul ignore */ does nothing and /* node:coverage ignore next N */ is the replacement; there is no HTML report, only the per-file table and the lcov files.
• Not provided. Snapshot matchers, expect.extend and custom matchers, watch mode, jest.isolateModules, jest.retryTimes and the rest of the jest surface not listed above. A spec that needs them is a spec to keep on Jest.

Behavioural differences

The places where the same call cannot behave exactly as it did under Jest, and what it does instead.

Compatibility

Peer Dependencies

Only the /dom entry imports jsdom. A project that never preloads it never needs it installed.