js-te

한국어

A lightweight JavaScript test framework inspired by Jest.

📎 Latest Update — 0.7.4

Project homepage (0.7.4)

• package.json now declares a homepage field, so the npm package page links to the project site. Metadata-only — no API or runtime changes.

Browser entry & TypeScript declarations (0.7.3)

• Browser entry — @dannysir/js-te/browser re-exports the core API (test, describe, beforeEach, expect, fn, testManager) for browsers and Web Workers, where the Node CLI runner can't run
• Importing /browser from a Node runtime throws immediately with a clear error, steering you to the main entry or the js-te CLI
• TypeScript — .d.ts declarations now ship for both the main and /browser entries, so the package is fully typed out of the box

See Browser usage for details.

Requirements

• Node.js >= 22.15.0 (version that introduced module.registerHooks)

Installation

npm install --save-dev @dannysir/js-te

Quick Start

1. Create a test file

Any *.test.js file is picked up and run automatically. No import needed — describe, test, expect, and friends are available globally.

// math.test.js
describe('[arithmetic]', () => {
  test('addition', () => {
    expect(1 + 2).toBe(3);
  });
});

2. Add a script to package.json

Both ESM and CommonJS projects are supported.

{
  "scripts": {
    "test": "js-te"
  }
}

3. Run

npm test

Example output

Running a subset

js-te                 # all tests
js-te user            # files whose path includes "user"
js-te -t "login"      # tests whose full name includes "login"
js-te auth -t "token" # combine both
js-te --testLocation test/user.test.js:42  # single test by file and line
js-te --reporter json # JSON output for IDE/CI
js-te --help          # help

See the CLI reference for full options, matching rules, and exit codes.

--help output

Features

• Test writing — test(), describe(), beforeEach(), test.each()
• Matchers — toBe, toEqual, toThrow, toBeTruthy, toBeFalsy, toContain, toBeInstanceOf, toBeNull, toBeUndefined, toBeDefined, toHaveBeenCalled, toHaveBeenCalledWith, toHaveBeenCalledTimes, .not chaining
• Mock Functions — fn(), mockImplementation, mockReturnValue, mockReturnValueOnce, mockClear, mock.calls
• Module Mocking — mock(path, mockObj) (relative & absolute paths), clearAllMocks, unmock, isMocked
• Module systems — ESM (import) and CommonJS (require)
• CLI — single js-te command
• Browser entry — @dannysir/js-te/browser exposes the core API for browsers and Web Workers
• TypeScript — bundled .d.ts declarations for the main and /browser entries

Examples

Tests & Matchers

describe('calculator', () => {
  test('addition', () => {
    expect(2 + 3).toBe(5);
  });
 
  test('object equality', () => {
    expect({ name: 'Alice' }).toEqual({ name: 'Alice' });
  });
});

Module Mocking

// game.js
import { random } from './random.js';
export const play = () => random() * 10;
 
// game.test.js
import { play } from './game.js';
 
test('mock random function', () => {
  const mocked = mock('./random.js', {
    random: () => 0.5,
  });
 
  expect(play()).toBe(5);
 
  // dynamically change return value via mock function methods
  mocked.random.mockReturnValue(0.3);
  expect(play()).toBe(3);
});

⚠️ Mock function methods (mockReturnValue, etc.) are only accessible through the object returned by mock(). See why in the API docs.

Browser usage

@dannysir/js-te/browser is a browser/Web Worker-safe entry that re-exports the pure test core. Reach for it when you run js-te test code directly in the browser (interactive demos, playgrounds) — the default @dannysir/js-te entry depends on the Node CLI runner and can't run there.

import { describe, test, expect, fn, beforeEach, testManager } from '@dannysir/js-te/browser';
 
describe('math', () => {
  test('addition', () => {
    expect(1 + 2).toBe(3);
  });
});
 
await testManager.run();

Exported: test (with test.each), describe, beforeEach, expect, fn, testManager.

Not exported: module mocking (mock, unmock, isMocked, clearAllMocks, mockStore) and the CLI runner (run) — these are Node-only and intentionally left out.

testManager is a module-level singleton. If you collect tests more than once on the same page, call testManager.clearTests() between runs.

Node guard — importing this entry from a Node runtime throws immediately, pointing you to the main @dannysir/js-te entry (or the js-te CLI):

@dannysir/js-te/browser cannot be used in a Node.js runtime.
It is designed for browsers and Web Workers only.

TypeScript — type declarations ship with the package (types/browser.d.ts), so the entry is fully typed with no extra setup.

Test File Discovery

The following files are found and run automatically:

1. *.test.js files anywhere in the project
2. All .js files inside a test/ folder

project/
├── src/
│   ├── utils.js
│   └── utils.test.js       ✅
├── test/
│   ├── integration.js      ✅
│   └── e2e.js              ✅
└── calculator.test.js      ✅

Documentation

• API Reference — full usage for test, expect, mock, fn, beforeEach, test.each
• CLI Reference — command-line options, matching rules, and exit codes
• Loader hook-based in-memory transform — 0.5.0 internals (Korean)
• CHANGELOG — version history

Links

• GitHub
• Blog series (Korean)

Motivation

Built out of curiosity about how JavaScript test frameworks like Jest work under the hood.

License

ISC