Migrate from Jest to `node:test` in CommonJS

Though this post is a bit minor content, please refer this when you need to migrate from Jest to Node.js built-in test runner (node:test).

Use Node.js Type Stripping or Deno when you start a new project or your current project doesn't have large codebase.

I've decided to use tsx (not Type Stripping) for transpiler because we need to migrate regular TypeScript source code to ESModule first and Type Stripping doesn't support *.tsx.

Environment

• Node.js v22.x
  • "type": "commonjs"
• tsx@4
• typescript@5

tsconfig.json example (Some options are not important.)

{
  "compilerOptions": {
    "lib": ["ES2023"],
    "baseUrl": ".",
    "allowSyntheticDefaultImports": true,
    "erasableSyntaxOnly": true,
    "strict": true,
    "esModuleInterop": true,
    "module": "Node18",
    "moduleResolution": "Node16",
    "target": "ES2022"
  },
  "include": ["src/**/*"]
}

Steps

1. Use @jest/globals instead of @types/jest if you use global Jest APIs (prefer-importing-jest-globals of eslint-plugin-jest would be helpful.)
2. Use node:assert instead of Jest expect API
3. Use sinon or other mocking libraries instead of Jest mocking APIs (e.g. jest.mock(), jest.spyOn())
4. Migrate {it,test}.each() w/ regular JS loop

After all of them are applied, you would run test via node --test instead of jest.

expect -> node:assert

// before

import { describe, expect, it } from "@jest/globals";

describe("foo()", () => {
  it("returns 'foo'", () => {
    expect(foo()).toEqual("foo");
  });
});

// after

import { describe, it } from "@jest/globals";
import assert from "node:assert/strict";

describe("foo()", () => {
  it("returns 'foo'", () => {
    assert.equal(foo(), "foo");
  });
});

jest.mock() -> sinon

If your stub, spy, or mock target is not an object, change source code first because tsx (esbuild) can't handle it. see

Before

// src/bar.ts

export function bar(): string {
  return "bar";
}

// src/foo.ts

import { bar } from "./bar";

export function fooBar(): string {
  return `foo${bar()}`;
}

// src/foo.test.ts

import { fooBar } from "./foo";

import * as barMod from "./bar";

import { afterEach, beforeEach, describe, it } from "@jest/globals";
import assert from "node:assert/strict";
import sinon from "sinon";

describe("fooBar()", () => {
  let barStub: sinon.SinonStub;

  beforeEach(() => {
    barStub = sinon.stub(barMod, "bar");
  });

  afterEach(() => {
    barStub.restore();
  });

  it("returns 'fooXXX'", () => {
    // This fails
    barStub.returns("XXX");

    assert.equal(fooBar(), "fooXXX");
  });
});

After

// src/bar.ts

export const barMod = {
  bar(): string {
    return "bar";
  },
};

// src/foo.ts

import { barMod } from "./bar";

export function fooBar(): string {
  return `foo${barMod.bar()}`;
}

// src/foo.test.ts

import { foo } from "./foo";

// This works
import { barMod } from "./bar";

// ...

it.each -> regular JS loop

// before
it.each([
  { input: {}, expected: { page: 1, limit: 20 } },
  { input: { name: "foo" }, expected: { name: "foo", page: 1, limit: 20 } },
  {
    input: { name: "", page: "2", limit: "50" },
    expected: { page: 2, limit: 50 },
  },
])("returns $expected w/ $input", ({ input, expected }) => {
  assert.deepEqual(validate(input), expected);
});

// after
[
  { input: {}, expected: { page: 1, limit: 20 } },
  { input: { name: "foo" }, expected: { name: "foo", page: 1, limit: 20 } },
  {
    input: { name: "", page: "2", limit: "50" },
    expected: { page: 2, limit: 50 },
  },
].forEach(({ input, expected }) => {
  it(`returns ${JSON.stringify(expected)} w/ ${JSON.stringify(input)}`, () => {
    assert.deepEqual(validate(input), expected);
  });
});

Command

The test command would be like this:

$ node --import=tsx --test '**/*.test.*'

Node.js test runner mocks

After the migration, you can use Node.js test runner's mocking APIs.

But you need a bit hard work for Module Mocking. (and you need --experimental-test-module-mocks flag)

The former example would be like the following:

src/foo/foo.test.ts

// no mocks are used in this file.

import { foo } from "./foo";

import assert from "node:assert/strict";
import { describe, it } from "node:test";

describe("foo()", () => {
  it("returns 'foo'", () => {
    assert.equal(foo(), "foo");
  });
});

src/foo/foo-bar.test.ts

// mocks are used in this file.

import assert from "node:assert/strict";
import { beforeEach, describe, it, mock } from "node:test";

describe("fooBar()", () => {
  let barMock = mock.fn<() => string>();
  let fooBar: () => string;

  beforeEach(async () => {
    // This can stub function
    mock.module("./bar", {
      namedExports: { bar: barMock },
    });

    // Load the target file after mocking
    ({ fooBar } = await import("./foo.js"));
  });

  it("returns 'fooXXX'", () => {
    barMock.mock.mockImplementation(() => "XXX");

    assert.equal(fooBar(), "fooXXX");
  });
});

I hope the Module Mocking API will be better in the future.