@hyperfrontend/testing
v0.5.3
Published
A lightweight Jest-like testing library built on native Node capabilities.
Maintainers
Readme
A lightweight Jest-like testing library built on native Node capabilities.
• 👉 See documentation • 👉 See guides & tutorials
What is @hyperfrontend/testing?
@hyperfrontend/testing lets you write tests the way you would for Jest and run them on Node's built-in test runner. It adds only what Node lacks and leaves the rest to Node.
It is not Jest, which remains the fuller tool. It is for projects where Node's built-ins are enough and the familiar syntax is worth keeping.
Key Features
- The Jest syntax you know - Describe blocks, matchers, mock functions and spies read the way a Jest suite already does
- Module mocks without a transpiler - Factories, partial mocks and automocks apply under native ES modules before a spec's imports link
- Fake timers on Node's clock - Advance time, drain pending timers and set the system time from inside a test
- A coverage gate you can trust - A source file no test loaded fails the run instead of quietly vanishing from the report
- Optional DOM - One preload gives browser-facing suites a jsdom window; suites that do not need it never install it
- TypeScript specs as written - Node's own type stripping runs them, with extensionless imports and tsconfig path aliases resolved
- The helpers suites keep rewriting - Typed object mocks, condition waits, self-cleaning temporary directories, linked windows, and stand-ins for a terminal, the standard streams and child processes
Architecture Highlights
Nothing is injected into the global scope: a spec imports what it uses. The architecture guide covers the preload, the mock registry and the coverage pipeline.
Why Use @hyperfrontend/testing?
Fewer dependencies, same habits
Node already ships a test runner, assertions, module mocking, fake timers and coverage. This package adds the shape of a Jest spec on top: one dev dependency instead of a framework, a transformer and a reporter, with nothing but Node built-ins at runtime.
A migration, not a rewrite
Jest suites keep their describe blocks, matchers and module mocks as written. Migrate a Jest suite to Node's test runner lists what does change.
Installation
npm install --save-dev @hyperfrontend/testingAdd jsdom as well only if a suite needs a DOM.
Quick Start
import { beforeEach } from 'node:test'
import { describe, expect, it, jest } from '@hyperfrontend/testing'
import { createCart } from './cart'
jest.mock('./pricing', () => ({ priceOf: () => 3 }))
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('notifies subscribers once per change', () => {
const onChange = jest.fn()
cart.subscribe(onChange)
cart.add('tea', 1)
expect(onChange).toHaveBeenCalledTimes(1)
})
})node --import @hyperfrontend/testing/hooks --test 'src/**/*.spec.ts'Lifecycle hooks come straight from node:test. The /hooks preload lets the spec load as TypeScript with its module mock in place.
For several environments, setup files and a coverage gate, declare a test.config.ts and run it with runProjectTests. Configure and run TypeScript tests on Node's test runner walks through a full setup.
API Overview
| Entry | What it is |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| @hyperfrontend/testing | What a spec imports |
| /hooks | The node --import preload: TypeScript resolution and mocks |
| /dom | The preload that puts a jsdom window on the global |
| /browser | Linked windows for cross-origin messaging, a driven ResizeObserver |
| /consumer | A packed package installed and run the way a consumer runs it |
| /fs | Temporary directories and fixture trees written from data |
| /process | Terminal, standard stream and child process stand-ins, npm on Windows |
| /runner | The config-driven runner, one node --test per environment |
| /coverage | The lcov merge and the threshold gate |
| /reporter | Node's spec reporter without the per-evaluation coverage noise |
Every matcher, option and signature is in the API reference.
Limitations
- No snapshots, custom matchers or watch mode. A suite that depends on them should stay on Jest.
- Coverage is V8 through Node's collector: no statements metric and no HTML report.
The full list is in Where behaviour differs from Jest.
Compatibility
Requires Node.js 22.18 or later. There is no browser build.
| Operating System | Supported | | ---------------- | :-------: | | Linux | ✅ | | macOS | ✅ | | Windows | ✅ |
Output Formats
| Format | File | Tree-Shakeable |
| ------ | ----------- | :------------: |
| ESM | index.mjs | ✅ |
| CJS | index.cjs | ❌ |
Peer Dependencies
| Package | Version | Type | | ------- | --------- | -------- | | jsdom | >= 26.0.0 | Optional |
Part of hyperfrontend
This library is part of the hyperfrontend monorepo.
