@simonegianni/node-test-jest-compat

Run your existing Jest suites on Node's built-in test runner without having to rewrite your tests.

Features

• Drop-in replacement for Jest's test runner
• Compatible with both ESM and CommonJS modules
• Uses Jest's own mocking library for maximum compatibility
• Supports all common Jest globals (describe, test, it, beforeEach, etc.)
• Includes Jest's expect assertions for seamless test migration
• No need to change your test files - just change how you run them

Installation

Just install the package as a development dependency in your project using your preferred package manager:

npm install --save-dev @simonegianni/node-test-jest-compat

yarn add --dev @simonegianni/node-test-jest-compat

pnpm add --save-dev @simonegianni/node-test-jest-compat

bun add --dev @simonegianni/node-test-jest-compat

Code changes

If you import or require 'jest' in your test files, you need to change it to import 'node-test-jest-compat' instead. This is because the package is a drop-in replacement for Jest's test runner.

// Before
import 'jest';
// After
import '@simonegianni/node-test-jest-compat';

What you do not need to do

• You do not need to change your test files. The package is designed to be a drop-in replacement for Jest's test runner (but see below for unsupported features).
• You do not need to change your tsconfig.json or jsconfig.json files. From a typing perspective, you can keep using jest types.

Usage

You can run your tests using Node's built-in test runner by running the following command:

node --test

See Node.js documentation for more information on the test runner.

If you are not importing @simonegianni/node-test-jest-compat in your test files, you can run the tests with the following command:

node --test --import @simonegianni/node-test-jest-compat

Or, if you are using CommonJS modules, you can run the tests with the following command:

node --test --require @simonegianni/node-test-jest-compat

For TypeScript projects, you can easily stack ts-node:

node --test --import ts-node/esm --import @simonegianni/node-test-jest-compat

However note that there are various issues with ts-node, ESM and loaders, as the NodeJS team is evolving those APIs and they are not yet stable. So, pre-compiling your TypeScript files to JavaScript and running them with Node's test runner is recommended.

Supported Jest Features

Basic Features

• ✅ describe, test, it for defining test suites and cases
• ✅ beforeEach, afterEach, beforeAll, afterAll hooks
• ✅ expect assertions (using Jest's own expect library)
• ✅ jest.getSeed() - Returns a seed value for deterministic randomness

Mocking and Spying

• ✅ Mock functions with jest.fn() or vi.fn()
• ✅ Spies with jest.spyOn() or vi.spyOn()
• ✅ Mock clearing with jest.clearAllMocks() or vi.clearAllMocks()
• ✅ Mock resetting with jest.resetAllMocks() or vi.resetAllMocks()
• ✅ Mock restoring with jest.restoreAllMocks() or vi.restoreAllMocks()
• ✅ Check if a function is a mock with jest.isMockFunction(fn) or vi.isMockFunction(fn)
• ✅ Require actual modules with jest.requireActual(moduleName)
• ✅ Require mocked modules with jest.requireMock(moduleName)
• ✅ Reset module registry with jest.resetModules()
• ✅ Set test timeout with jest.setTimeout(timeout)
• ✅ Fake timers with jest.useFakeTimers(), jest.useRealTimers(), etc.

Snapshot Testing

• ✅ expect().toMatchSnapshot() - Uses Node.js test runner's snapshot functionality
• ✅ Snapshot file generation and comparison
• ✅ Snapshot directory structure matching Jest's conventions

Module Mocking

NOTICE: This is currently still experimental in NodeJs and works only under certain conditions. See Node.js documentation for more information.

• ✅ jest.mock() - Uses Node.js test runner's mock.module() function
• ✅ jest.unmock() - Restores mocked modules
• ✅ Factory functions for custom mock implementations

Test Filtering

• ✅ test.only() - Runs only tests marked with .only
• ✅ describe.only() - Runs only test suites marked with .only
• ✅ it.only() - Alias for test.only()

Test Retries

• ✅ jest.retryTimes() - Retries failed tests a specified number of times
• ✅ Support for logging errors before retry

Unsupported Jest Features

The following Jest features are NOT supported:

Automocking

• ❌ jest.enableAutomock() - Node's test runner doesn't have an automocking system
• ❌ jest.disableAutomock() - Related to automocking

Misc

• ❌ jest.isEnvironmentTornDown() - Specific to Jest's test environment

Module Support

The package is designed to work with both CommonJS and ESM modules. You can use it in your existing projects without any issues.

• If you are using ESM, you can import the package using import { test, expect } from '@simonegianni/node-test-jest-compat'.
• If you are using CommonJS, you can import the package using const { test, expect } = require('@simonegianni/node-test-jest-compat').

Implementation Details

This package:

1. Uses TypeScript to build both ESM and CommonJS versions
2. Uses jest-mock for mocking functions
3. Uses the actual Jest expect for assertions
4. Provides a seamless compatibility layer between Jest's API and Node's built-in test runner

For Developers

Development Workflow

1. Clone the repository
2. Install dependencies:

   npm install

3. Make your changes in the src directory
4. Build the project:

   npm run build

5. Build and then run tests:

   npm test

Publishing to npm

To publish a new version to npm:

1. Update the version in package.json
2. Build and run tests to ensure everything works:

   npm test

3. Publish to npm:

   npm publish

Note: You need to be logged in to npm (npm login) and have appropriate permissions to publish the package.

License

APACHE 2.0