Proposal: Change vi.mock signature to return the mocked module instead of void

[webbertakken]

Introduction

Vocabulary

unit: a single method or function
side-effect: another function that is called from inside your unit
unit test: testing a unit without testing the logic of side-effects

Use case

Consider making a dead simple unit test that needs to mock either a 3rd part or local module that's called as a side-effect.

• This is simple: You can just add vi.mock('./localModule') or vi.mock('third-party-module') at the top of the file as per the docs [1, 2].

Now try to imagine also asserting that methods from that module are only called once by your unit.

• Suddenly not as straightforward anymore.

Explanation

You won't get this to work before realising a few things:

1. vi.mock() returns void, meaning it doesn't give you a reference to any of the methods, that you can assert on.
2. The documentation quickly becomes pretty thin on this topic. It's mentioned almost as an afterthought at the bottom of one of the four warnings in the relevant section.

You can also reference variables defined by vi.hoisted method if it was declared before vi.mock:

3. Stackoverflow isn't exactly overflowing with helpful examples that work for both internal and external modules either.
4. When first defining a spy and passing that into the second (factory) argument of vi.mock(), you'll soon find out that you can't do that because the act of mocking a module is hoisted (pulled to the top at runtime). See "Invalid example" below.
5. Eventually you'll reach a working syntax. See "Correct example" below.

Invalid example

import { vi, describe, expect, it } from 'vitest'
import { useCookie } from './useCookie'

const get = vi.fn() // THIS WON'T WORK

vi.mock('js-cookie', () => ({ default: { get } }))

describe('useCookie', () => {
  describe('getValue', () => {
    it('calls js-cookie.get once', () => {
      // Act
      useCookie('test').getValue()

      // Assert
      expect(jsCookie.get).toHaveBeenCalledTimes(1)
    })
  })
})

Correct example

import { vi, describe, expect, it } from 'vitest'
import { useCookie } from './useCookie'

// Methods must be hoisted to reference them in `vi.mock`
const jsCookie = vi.hoisted(() => ({
  get: vi.fn(),
  set: vi.fn(),
  remove: vi.fn(),
}))

vi.mock('js-cookie', () => ({ default: jsCookie }))

describe('useCookie', () => {
  describe('getValue', () => {
    it('calls js-cookie.get once', () => {
      // Act
      useCookie('test').getValue()

      // Assert
      expect(jsCookie.get).toHaveBeenCalledTimes(1)
    })
  })
})

Better correct example

import { vi, describe, expect, it } from 'vitest'
import { useCookie } from './useCookie'
import * as jsCookie from 'js-cookie'
// or import jsCookie from 'js-cookie'

vi.mock('js-cookie', () => ({
  default: {
    get: vi.fn(),
    set: vi.fn(),
    remove: vi.fn(),
  },
}))

describe('useCookie', () => {
  describe('getValue', () => {
    it('calls js-cookie.get once', () => {
      // Act
      useCookie('test').getValue()

      // Assert
      expect(jsCookie.default.get).toHaveBeenCalledTimes(1)
      // or expect(jsCookie.get).toHaveBeenCalledTimes(1)
    })
  })
})

Proposal 1 (superseded)

I'd propose for vi.mock to return the mocked module (the outcome of the factory method) and make it accessible much like the jsCookie variable is in "Correct example".

This would effectively combine the syntax of vi.hoisted and vi.mock into a single call for many use cases and make those tests easier to remember how to write, as well as lot more readable.

-const jsCookie = vi.hoisted(() => ({
+const jsCookie = vi.mock('js-cookie', () => ({
+  default: {
     get: vi.fn(),
     set: vi.fn(),
     remove: vi.fn(),
+  }
}))
-vi.mock('js-cookie', () => ({ default: jsCookie }))

This would look even simpler with named exports/imports, as you don't need default.
For complex methods the pattern might be repeated several times.

Proposal 2 (current)

1. Update the example on https://vitest.dev/api/vi.html#vi-mock to include an assertion like discussed above Because then it's clear how to reference the mock.
2. Split the example on https://vitest.dev/guide/mocking.html#example-2 into showing the different concepts. Again so it's easier to deduce how to mock a module and use the mock.

Other thoughts

Perhaps there are better signatures that are repeatable for both ./localModule and third-party-module than I've found so far ("Correct example"), in which case please share them 🧡

[sheremet-va]

Why can't you just import the module with import keyword? It returns the same object

[sheremet-va]

This works if you change line 3 to

This would be a wrong thing to do in the context of this proposal because * is the same object you returned in vi.mock, and default import is default key on that object.

[webbertakken]

I see.

Note that your example uses incorrect syntax. I'm assuming you meant to do a namespace import then.

-import * jsCookie from 'js-cookie'
+ import * as jsCookie from 'js-cookie'

I did test my previous comment (with the default import) and it worked too.

Any reason why a namespace import is better than a default import in this case?

[sheremet-va]

It's not better to use. It's just a good demonstration that this is the same object returned from vi.mock

[webbertakken]

Thank you very much for the responses. It's clear to me now.

Would you like me to send a PR to clear up the documentation to better convey this knowledge?

[sheremet-va]

Sure