Mocking a module API pains

Firstly, I think jest is a great test runner and I appreciate all the hard work that has gone in to it. Awesome job 👍

However, the mock API does irk me. So I’d like to open this issue to see if there’s something that we can do about it. Some documentation changes may help, some different APIs also may be beneficial.

Do you want to request a feature or report a bug? Feature

What is the current API? Here are some of my pain points with the mocking APIs:

Unclear semantics

The difference in semantics between jest.mock and jest.doMock are not apparent from the names alone, I have to check the docs to remind myself. Same goes for jest.unmock and jest.dontMock. And jest.resetAllMocks and jest.restoreAllMocks. And mockFn.mockReset and mockFn.mockRestore. I think you get the picture…

jest.mock hoisting

jest.mock calls are hoisted to the top of the scope (via babel-jest). The issues I see here:

1. Hoisting function calls to the top of the current scope is non-standard JS, it’s a language extension. Users probably won’t expect it, which may cause them problems until the new behaviour is learnt. For example:

   // original
   import foo from './foo'
   jest.mock('./foo')
   foo() // is this call mocked?
   

   // transpiled output
   jest.mock('./foo')
   import foo from './foo'
   foo() // yes! it is mocked.
   

2. It feels like the hoisting was added to fit in with the way existing tests were written, rather than attempting to change the way people write tests to fit the mocking problem. I think TestDouble.js has an interesting solution to this problem. An obvious rip off of their API might look like:

   let mockedFoo = jest.replace('./foo')
   let mockedBar = jest.replace('./bar').default // in this case bar is a default export
   let subject = require('./subject') // subject now depends on mocked foo and bar
   

   The CommonJS (CJS) module format is more flexible for messing around with modules than ES6 modules (ESM). I would suggest keeping both the current API for ESM and introducing the new for CJS tests and in some future version suggest new tests should be written in the CJS style. This way the hoisting behaviour, as well as some of the lesser known caveats of ESM, can be avoided.

Large API surface

The API relating to mocking a module as of v22.4.2 consists of:

• jest.mock/jest.unmock
• jest.doMock/jest.dontMock
• jest.setMock
• jest.genMockFromModule
• import * as foo from './foo' + jest.spyOn (See #936)
• Manual mocks
• require.requireMock
• jest.enableAutoMock/jest.disableAutomock

Are all of these different methods of mocking a module required? Can a simpler, smaller API be found to cover the above cases? I don’t have any immediate answers but would love to see what the community come up with.

---

I can probably fix most of these by using a 3rd party lib but it would be nice if Jest made some changes so I didn’t have to. I willing to accept that I hold a minority opinion on these APIs and if so, it may not be worth anyones time to work on this. I thought it was worth raising all the same.

[nfantone]

I second this. jest mock API is convoluted, at best, and generally confusing, IMHO.

• Do I need to reset, restore or clear a mock?
• Why do restore work only on spies?
• Is it a module or a mock that needs restoring?
• Do I use genMockFromModule or plain .mock to mock a module?
• Was it .mock that gets automatically hoisted… or is it doMock?
• Why is there an unmock?
• How do I partially mock a module’s API?
• Why is it not straightforward to declare mocks per test?

I’m not saying these questions don’t have proper answers. I’m making the point that it’s the fact that you need to consider those answers and think about them every time you (or at least I) write a test using jest. I end up losing myself in the docs and/or SO more than I feel I should.

[aaronjensen]

Hi all, I’ve been using jest for quite a while now. I agree with OP that the runner itself is fantastic. That said, I’ve tried a number of times over the many projects I’ve used jest on to use jest mocks. I always run into confusion and problems. It’s very possible that I’m doing something wrong and have some fundamental misunderstanding, but the current API doesn’t appear to lead to the pit of success.

I think that the problems I’ve run into boil down to a simple fact: jest mocks are not generally safe to use between tests. That is, they leak state between tests by default. As far as I can tell, they leak recordings and implementations. If I mockReturnValue in a test then the next test will get that return value too if I don’t manually restore the mock.

This plays poorly with some of the other features of jest like manual mocks. Here’s an example of something I’m trying to do right now that led me to this issue.

__mocks__/service.js

export default {
  foo: jest.fn(() => 'original')
}

__tests__/mytest.js

import service from '../service'

it('original', () => {
  expect(service.foo()).toEqual('original')
})

it('override', () => {
  trelloService.foo.mockReturnValue('override')
  expect(service.foo()).toEqual('override')
})

it('original', () => {
  // none of these matter:
  // jest.restoreAllMocks()
  // jest.resetAllMocks()
  // jest.clearAllMocks()
  expect(service.foo()).toEqual('original') // FAIL
})

So, I know I’m doing something “wrong” here. I probably shouldn’t be using manual mocks in these ways. However, the problem doesn’t end with manual mocks. Many of the jest examples in the docs show mocks being created at the module level. This fails too:

const foo = jest.fn(() => 'original')

it('original', () => {
  expect(foo()).toEqual('original')
})

it('override', () => {
  foo.mockReturnValue('override')
  expect(foo()).toEqual('override')
})

it('original', () => {
  expect(foo()).toEqual('original') // FAIL
})

Furthermore, the necessity for jest.mock to be at the module level makes it more likely that jest.fn()'s will be created at the module level. Basically, every time I’ve used jest I’ve felt pushed to create mocks at the module level only to find that, like the north, mocks remember.

What I think would be fantastic is if:

1. There was a single function to completely reset mocks to the state they were in when they were created.
2. That function worked on jest.fn()'s created at the module level (or in manual mocks).
3. That function was called between tests by default.

I believe, if those were true, then mocks would “just work” and wouldn’t leak state between tests.

The API mentioned above looks nicer, but, at least for me, this is the much bigger pain point.