Native test runner: document how to mock standalone imported functions

[GabeAtWork]

Details

Currently, when adopting the native test runner, it is very hard to understand how to mock standalone functions used in the unit under test. Judging by this SO question, I'm not the only one who can't figure this out 😄

None of the documentation examples on the Test runner demonstrate the mocking of imported functions.

The only way I found to mock functions used in another function is to export all functions of the depended-on function's file, e.g. export default {all, my, functions}. From a production code standpoint, it's both unnecessary (if I want to only use one function from a file, why should I need to import the whole default and access the function I need as a member?) and in some contexts undesirable (my gut feeling is that it would make treeshaking impossible, but I haven't verified this).

You'll find an example in this repository: https://github.com/GabeAtWork/node-test-runner-cannot-mock-function-minimal-example

The file demonstrates 3 approaches:

• Using default exports and mock.method (works, but is not desirable as explained above)
• Using single import and mock.fn (our go-to way of writing code, but doesn't mock the function, so the actual function gets called)
• Using star imports and mock.method (would be an ok compromise, but it seems to fail in what looks like a bug)

It may be that there is an alternate way of solving this problem which I haven't found yet, so please do let me know if it exists! Since this feature is so fresh, there's not a lot of content on it yet. Blog posts and videos I found don't actually show functions imported from different files or only show default imports and classes being mocked.

Feature request on the node repo: nodejs/node#51164

Node.js version

20.8.0

Example code

You can find a minimal example in this repository: https://github.com/GabeAtWork/node-test-runner-cannot-mock-function-minimal-example

Operating system

MacOS (but not relevant)

Scope

Documentation / API design

Module and version

Not applicable.

[GabeAtWork]

As an example, what jest does is that it allows you to mock a module by path:

jest.mock("../add", () => ({
  add: jest.fn(),
})

[GabeAtWork]

I also realised this has been discussed here: nodejs/node#42242
Also there is a reference here to the fact that mocking modules is still being worked on (May 2023) to make that work with ESM: https://github.com/orgs/nodejs/discussions/47959

[GabeAtWork]

Further findings
The following library does a pretty good job at work with this on CJS: https://github.com/mhweiner/cjs-mock

[anandkhatri]

Hi @GabeAtWork I'm facing a similar issue, where want to mock an external lib function. but it's always making a real call to function and returning the actual result instead of a mocked result.

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

it("Hello", () => {
      mock.fn(getParametersByName, async () => {
		return {
			 _errors: [],
			 parameters: {
			 	"paramKey1":"value",
			 	"paramKey2":"value"
			 }
			};
		});
});

Do you have a solution for this? I don't want to use any lib other than default NodeJs test runner.

[GabeAtWork]

Hi @anandkhatri, AFAIK there is no known workaround that doesn't involve using a third-party lib or rolling out your own module mocking function.

[doug-wade]

I'm also struggling with this. I'm trying to use node-fetch-cache to cache results between network requests. The library has a default export, and it is important that I not make network calls at test time to avoid test flakiness when the dependency is having downtime, and to avoid putting undue load on my dependency while developing. I don't have the ability to refactor this dependency to use the export default {all, my, functions} syntax, as this is a dependency I don't control.

I would like to be able to use

import * as fetch from 'node-fetch-cache';
...
mock.method(fetch, 'default', () => Promise.resolve(response));

But I get the error

  TypeError [Error]: Cannot redefine property: default
      at defineProperty (<anonymous>)
      at MockTracker.method (node:internal/test_runner/mock/mock:268:5)
      at TestContext.<anonymous> (~/my_project)
      at Test.runInAsyncScope (node:async_hooks:206:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
      at Test.postRun (node:internal/test_runner/test:715:19)
      at Test.run (node:internal/test_runner/test:673:12)
      at async Promise.all (index 0)
      at async Suite.run (node:internal/test_runner/test:948:7)

I've been using esmock to work around this, but it feels like something that the node test runner is able to support without a third-party library and I just haven't figured out how yet.

[GabeAtWork]

Note: there is now an issue for this on the node repo itself: nodejs/node#51164

[mhweiner]

Creator of cjs-mock here. I'm not convinced that it's a test runner's job to do mocking. Their job is just to run tests, not care about what is in them. Sure, it needs to support async, etc. but mocking seems a bit heavy of a lift and dependent on the module type (ie, CJS, ESM, AMD, etc.). I also created a test runner, hoare, which does not do mocking. There's also sinon, which is more about building fake objects than module importing but useful in mocking. I haven't dabbled much with ESM testing yet (I'm using Typescript so I'm a bit insulated) but will work on an ESM version if there is enough interest.

If anyone has any advice on how to make cjs-mock or hoare any better, I'd love to hear from you (or collaborate). I'm also able to answer questions! I'm really passionate about both projects and testing in general. My background is in safety-critical software, working in healthcare and aerospace industries.

[m-sureshraj]

Hi @doug-wade,

Have you tried using the default import import fetch from 'node-fetch-cache instead of import * as ...?

I encountered the same error on Node version v20.12.2, but using the default import did not have any issues with mocking.

import childProcess from 'node:child_process';

test('some-test', () => {
  const mockedExecSync = mock.method(childProcess, 'execSync', () => {});
  ...
});

---

From Node version v22.3.0, named exports can be mocked using the mock.module feature. I haven't tested this functionality myself yet, though.

[danielbayley]

I would like to be able to use

import * as fetch from 'node-fetch-cache';
...
mock.method(fetch, 'default', () => Promise.resolve(response));

But I get the error

  TypeError [Error]: Cannot redefine property: default
      at defineProperty (<anonymous>)
      at MockTracker.method (node:internal/test_runner/mock/mock:268:5)
      at TestContext.<anonymous> (~/my_project)
      at Test.runInAsyncScope (node:async_hooks:206:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
      at Test.postRun (node:internal/test_runner/test:715:19)
      at Test.run (node:internal/test_runner/test:673:12)
      at async Promise.all (index 0)
      at async Suite.run (node:internal/test_runner/test:948:7)

I’m trying to do basically exactly the same thing—mock a method from * star import (although not the default export, in my case)—but unfortunately, even though nodejs/node#52848 was merged, it does not address the above use case.