Jest: Timer and Promise don't work well. (setTimeout and async function)
Yes, you're on the right track.
What happens
await simpleTimer(callback)
will wait for the Promise returned by simpleTimer()
to resolve so callback()
gets called the first time and setTimeout()
also gets called. jest.useFakeTimers()
replaced setTimeout()
with a mock so the mock records that it was called with [ () => { simpleTimer(callback) }, 1000 ]
.
jest.advanceTimersByTime(8000)
runs () => { simpleTimer(callback) }
(since 1000 < 8000) which calls setTimer(callback)
which calls callback()
the second time and returns the Promise created by await
. setTimeout()
does not run a second time since the rest of setTimer(callback)
is queued in the PromiseJobs
queue and has not had a chance to run.
expect(callback).toHaveBeenCalledTimes(9)
fails reporting that callback()
was only called twice.
Additional Information
This is a good question. It draws attention to some unique characteristics of JavaScript and how it works under the hood.
Message Queue
JavaScript uses a message queue. Each message is run to completion before the runtime returns to the queue to retrieve the next message. Functions like setTimeout()
add messages to the queue.
Job Queues
ES6 introduces Job Queues
and one of the required job queues is PromiseJobs
which handles "Jobs that are responses to the settlement of a Promise". Any jobs in this queue run after the current message completes and before the next message begins.
then()
queues a job in PromiseJobs
when the Promise it is called on resolves.
async / await
async / await
is just syntactic sugar over promises and generators. async
always returns a Promise and await
essentially wraps the rest of the function in a then
callback attached to the Promise it is given.
Timer Mocks
Timer Mocks work by replacing functions like setTimeout()
with mocks when jest.useFakeTimers()
is called. These mocks record the arguments they were called with. Then when jest.advanceTimersByTime()
is called a loop runs that synchronously calls any callbacks that would have been scheduled in the elapsed time, including any that get added while running the callbacks.
In other words, setTimeout()
normally queues messages that must wait until the current message completes before they can run. Timer Mocks allow the callbacks to be run synchronously within the current message.
Here is an example that demonstrates the above information:
jest.useFakeTimers();
test('execution order', async () => {
const order = [];
order.push('1');
setTimeout(() => { order.push('6'); }, 0);
const promise = new Promise(resolve => {
order.push('2');
resolve();
}).then(() => {
order.push('4');
});
order.push('3');
await promise;
order.push('5');
jest.advanceTimersByTime(0);
expect(order).toEqual([ '1', '2', '3', '4', '5', '6' ]);
});
How to get Timer Mocks and Promises to play nice
Timer Mocks will execute the callbacks synchronously, but those callbacks may cause jobs to be queued in PromiseJobs
.
Fortunately it is actually quite easy to let all pending jobs in PromiseJobs
run within an async
test, all you need to do is call await Promise.resolve()
. This will essentially queue the remainder of the test at the end of the PromiseJobs
queue and let everything already in the queue run first.
With that in mind, here is a working version of the test:
jest.useFakeTimers()
it('simpleTimer', async () => {
async function simpleTimer(callback) {
await callback();
setTimeout(() => {
simpleTimer(callback);
}, 1000);
}
const callback = jest.fn();
await simpleTimer(callback);
for(let i = 0; i < 8; i++) {
jest.advanceTimersByTime(1000);
await Promise.resolve(); // allow any pending jobs in the PromiseJobs queue to run
}
expect(callback).toHaveBeenCalledTimes(9); // SUCCESS
});
Brian Adams' answer is spot on.
But calling await Promise.resolve()
only seems to resolve one pending promise.
In the real world, testing functions having multiple asynchronous calls would be painful if we have to call this expression over and over again per iteration.
Instead, if your function has multiple await
s it's easier to use jwbay's response:
- Create this function somewhere
function flushPromises() { return new Promise(resolve => setImmediate(resolve)); }
- Now call
await flushPromises()
wherever you would have otherwise called multipleawait Promise.resolve()
s
There is a use case I just couldn't find a solution:
function action(){
return new Promise(function(resolve, reject){
let poll
(function run(){
callAPI().then(function(resp){
if (resp.completed) {
resolve(response)
return
}
poll = setTimeout(run, 100)
})
})()
})
}
And the test looks like:
jest.useFakeTimers()
const promise = action()
// jest.advanceTimersByTime(1000) // this won't work because the timer is not created
await expect(promise).resolves.toEqual(({completed:true})
// jest.advanceTimersByTime(1000) // this won't work either because the promise will never resolve
Basically the action won't resolve unless the timer advances. Feels like a circular dependency here: promise need timer to advance to resolve, fake timer need promise to resolve to advance.