This is a great follow-up to But really, what is a JavaScript
test? So here we go!
Step 0
To learn about mocks we have to have something to test and something to mock, so
here’s the module we’ll be testing today:
// thumb-war.js
import {getWinner} from './utils'
function thumbWar(player1, player2) {
const numberToWin = 2
let player1Wins = 0
let player2Wins = 0
while (player1Wins < numberToWin && player2Wins < numberToWin) {
const winner = getWinner(player1, player2)
if (winner === player1) {
player1Wins++
} else if (winner === player2) {
player2Wins++
}
}
return player1Wins > player2Wins ? player1 : player2
}
export default thumbWar
It’s a thumb war game where you play best 2 out of three. It uses a function
called getWinner from utils. getWinner returns the winning player or null
for a tie. We’re going to pretend this is making a call to some third party
machine learning service that has a testing environment we don’t control and
is unreliable so we want to mock it out for tests. This is one of the (rare)
situations where mocking is really your only choice to reliably test your code.
(I’m still making it synchronous to simplify our example further).
In addition, unless we re-implement all the inner-workings of getWinner in our
tests, there’s no way for us to really make useful assertions because the winner
of the thumb war is non-deterministic. So without mocking anything, here’s the
best our test can do:
// thumb-war.0.js
import thumbWar from '../thumb-war'
test('returns winner', () => {
const winner = thumbWar('Ken Wheeler', 'Kent C. Dodds')
expect(['Ken Wheeler', 'Kent C. Dodds'].includes(winner)).toBe(true)
})
We can only assert that the winner is one of the players, and maybe that’s
enough. But if we really want to ensure that our thumbWarfunction is
integrating properly with getWinner (as much as we reasonably can), then we’ll
want to create a mock for it and assert on a real winner.
Step 1
The simplest form of mocking is monkey-patching values. Here’s an example of
what our test looks like when we do that:
import thumbWar from '../thumb-war'
import * as utils from '~/utils'
test('returns winner', () => {
const originalGetWinner = utils.getWinner
// eslint-disable-next-line import/namespace
utils.getWinner = (p1, p2) => p2
const winner = thumbWar('Ken Wheeler', 'Kent C. Dodds')
expect(winner).toBe('Kent C. Dodds')
// eslint-disable-next-line import/namespace
utils.getWinner = originalGetWinner
})
You’ll notice a few things here. First we have to import the utils module as a
* import so we have an object that we can manipulate (NOTE: read that with a
grain of salt! More on why this is bad later). Then we need to store the
original function at the beginning of our test and restore it at the end so
other tests aren’t impacted by the changes we’re making to the utils module.
All of that is just setup for the actual mocking part of our changes. The mock
is the line that reads:
utils.getWinner = (p1, p2) => p2
This is monkey-patching mocking.
It’s effective (we’re now able to ensure there’s a specific winner of the
thumbWar game), but there are some limitations to this. One thing that’s
annoying is the eslint warning, so we’ve disabled that (again, don’t actually do
this as it makes your code non-spec compliant! Again, more on this later). Also,
we don’t actually know for sure whether the utils.getWinner function was
called as much as it should have been (twice, for a best 2 out of 3 game). This
may or may not be important for the application, but it’s important for what I’m
trying to teach you so let’s improve that!
Step 2
Let’s add some code to make sure that the getWinner function was called twice,
and ensure it was called with the right arguments.
import thumbWar from '../thumb-war'
import * as utils from '~/utils'
test('returns winner', () => {
const originalGetWinner = utils.getWinner
// eslint-disable-next-line import/namespace
utils.getWinner = (...args) => {
utils.getWinner.mock.calls.push(args)
return args[1]
}
utils.getWinner.mock = {calls: []}
const winner = thumbWar('Ken Wheeler', 'Kent C. Dodds')
expect(winner).toBe('Kent C. Dodds')
expect(utils.getWinner.mock.calls).toHaveLength(2)
utils.getWinner.mock.calls.forEach(args => {
expect(args).toEqual(['Ken Wheeler', 'Kent C. Dodds'])
})
// eslint-disable-next-line import/namespace
utils.getWinner = originalGetWinner
})
So here we’re adding a mock object to our mock function so we can keep some
mock metadata about how the function is called. This allows us to add these two
assertions:
expect(utils.getWinner.mock.calls).toHaveLength(2)
utils.getWinner.mock.calls.forEach(args => {
expect(args).toEqual(['Ken Wheeler', 'Kent C. Dodds'])
})
This helps us ensure that our mock is being called properly (with the right
arguments) and that it’s being called the right number of times (twice for a two
out of three game).
Now so long as our mock can model what the real world version does, we can get
back a little confidence that our code is working despite having to mock out
what getWinner is actually doing. It may not be a bad idea to implement some
contract testing to ensure
that the contract between getWinner and the third party service is kept in
check. But I’ll leave that to your imagination!
Step 3
So all of this stuff is cool, but it’s annoying to have to keep track of when
our mock is called all the time. Turns out that what we’ve done is manually
implement a mock function and Jest comes built-in with a utility for exactly
this. So let’s simplify our code by using that!
import thumbWar from '../thumb-war'
import * as utils from '~/utils'
test('returns winner', () => {
const originalGetWinner = utils.getWinner
// eslint-disable-next-line import/namespace
utils.getWinner = jest.fn((p1, p2) => p2)
const winner = thumbWar('Ken Wheeler', 'Kent C. Dodds')
expect(winner).toBe('Kent C. Dodds')
expect(utils.getWinner).toHaveBeenCalledTimes(2)
utils.getWinner.mock.calls.forEach(args => {
expect(args).toEqual(['Ken Wheeler', 'Kent C. Dodds'])
})
// eslint-disable-next-line import/namespace
utils.getWinner = originalGetWinner
})
Here we’ve simply wrapped our getWinner mock implementation with
jest.fn.
This effectively does all the same stuff we were doing, except because it’s a
special Jest mock function, there are some special assertions we can use just
for that purpose (like toHaveBeenCalledTimes). Jest has an assertion called
toHaveBeenNthCalledWith,
so we could have avoided our forEach, but I think it’s ok as it is (and
luckily we implemented our own metadata collection in the same way Jest does, so
we don’t need to change that assertion. Fancy that!).
The next thing I don’t like is having to keep track of originalGetWinner and
restore that at the end. I’m also bothered by those eslint comments I had to put
there (remember! That rule is super important and we’ll talk about it in a
moment). Let’s see if we can simplify things further with another Jest utility.
Step 4
Luckily, Jest has a utility called
spyOn
which does exactly what we need:
import thumbWar from '../thumb-war'
import * as utils from '~/utils'
test('returns winner', () => {
jest.spyOn(utils, 'getWinner')
utils.getWinner.mockImplementation((p1, p2) => p2)
const winner = thumbWar('Ken Wheeler', 'Kent C. Dodds')
expect(winner).toBe('Kent C. Dodds')
utils.getWinner.mockRestore()
})
Sweet! We’ve really simplified things! Mock functions are also called spies
(which is why the API for this is called spyOn). By default, Jest will just
keep the original implementation of getWinner but still keep track of how it’s
called. For us though we don’t want the original implementation to be called so
we use mockImplementation to mock out what happens when it’s called. Then at
the end we use mockRestore to clean up after ourselves just as we were before.
Neat right!?
So remember the eslint errors we were seeing? Let’s address those next!
Step 5
The ESLint error we were seeing is actually really important. We got around the
issue because we change our code in such a way that eslint-plugin-import was
unable to statically detect that we are still actually breaking the rule. But
this rule is actually very important. The rule is:
import/namespace.
The reason it’s broken in this case is:
Reports on assignment to a member of an imported namespace.
So why is this a problem? It’s because the fact that our code works is just the
luck of how Babel transpiles it to CommonJS and how the require cache works.
When I import a module, I’m importing immutable bindings to the functions in
that module, so if I import the same module in two different files and attempt
to mutate the bindings, the mutation will only apply for the module where the
mutation occurred (I’m actually not sure about this, I may get an error, which
would probably be better). So if you rely on this, you’re probably in for
tears when you try to upgrade to ES modules for realzies.
That said, what we’re about to do doesn’t really comply with the spec either
(it’s test utilities doing some magic for us), but our code looks like it
complies with the spec which is important so folks on the team don’t learn bad
habits that could find their way into application code.
So to solve this, we could attempt to muck with the require.cacheto swap the
actual implementation of the module for our mock version, but we’d find out that
imports happen before our code runs and so we wouldn’t be able to run it in
time without pulling it into another file. Also, my kids are about to wake up
and I gotta get this done!
So now we come to the jest.mock API. Because Jest actually simulates the
module system for us, it can very easily and seamlessly swap out a mock
implementation of a module for the real one! Here’s what our test looks like
now:
import thumbWar from '../thumb-war'
import * as utilsMock from '~/utils'
jest.mock('~/utils', () => {
return {
getWinner: jest.fn((p1, p2) => p2),
}
})
test('returns winner', () => {
const winner = thumbWar('Ken Wheeler', 'Kent C. Dodds')
expect(winner).toBe('Kent C. Dodds')
expect(utilsMock.getWinner).toHaveBeenCalledTimes(2)
utilsMock.getWinner.mock.calls.forEach(args => {
expect(args).toEqual(['Ken Wheeler', 'Kent C. Dodds'])
})
})
Cool right!? We just tell Jest we want all files to use our mock version instead
and poof! It does! Notice also that I changed the name of the import from
utils to utilsMock. That’s not required, but I like doing that to
communicate the intention that this should be importing a mocked version of the
module, not the real thing.
Common question: If you only want to mock one of several functions in a
module, then you may like the
jest.requireActual
API.
Step 6
Ok, so we’re almost done. What if we’re using this getWinner function in
several of our tests and we don’t want to copy/paste this mock everywhere?
That’s where the
__mocks__
directory comes in
handy! So we create a __mocks__ directory right next to the file that we want
to mock, and then create a file with the same name:
other/whats-a-mock/
├── __mocks__
│ └── utils.js
├── __tests__/
├── thumb-war.js
└── utils.jsInside the __mocks__/utils.js file, we’ll put this:
// __mocks__/utils.js
export const getWinner = jest.fn((p1, p2) => p2)
And with that, we can update our test:
// __tests__/thumb-war.js
import thumbWar from '../thumb-war'
import * as utilsMock from '~/utils'
jest.mock('~/utils')
test('returns winner', () => {
const winner = thumbWar('Ken Wheeler', 'Kent C. Dodds')
expect(winner).toBe('Kent C. Dodds')
expect(utilsMock.getWinner).toHaveBeenCalledTimes(2)
utilsMock.getWinner.mock.calls.forEach(args => {
expect(args).toEqual(['Ken Wheeler', 'Kent C. Dodds'])
})
})
🎉 Woo! Now we just say jest.mock(pathToModule) and it’ll pick up the mock
file we created for us automatically.
Now we may not want this mock to always return the second player, so we can use
mockImplementation for specific tests to verify that it works if we return the
second and then first and then second again, etc. Feel free to try that on your
own. You can also equip your mock with some utilities as well if you like. The
world is your oyster.
Good luck!
Source link
