doc : jest fake timers : expect on setTimeout not working

🐛 Bug Report

In https://jestjs.io/fr/docs/timer-mocks, we can see that we can assert that setTimeout has been called once : expect(setTimeout).toHaveBeenCalledTimes(1);

However, if you do this in a test, jest will complain :

expect(received).toHaveBeenCalledTimes(expected)

Matcher error: received value must be a mock or spy function

Received has type:  function
Received has value: [Function setTimeout]

  216 |     //TODO: test refresh works
> 217 |     expect(setTimeout).toHaveBeenCalledTimes(1);
      |                        ^
  218 |   });
  219 | });
  220 |

  at Object.<anonymous> (xxx.spec.ts:217:24)

I think the documentation should be fixed to explain how we can do …

[kleinfreund]

How is one supposed to solve this issue?

My tests start to fail as described in the inital report (i.e. I get a “received value must be a mock or spy function” error when invoking expect(setTimeout).not.toHaveBeenCalled() in a test).

Adding jest.spyOn(window, 'setTimeout') inexplicably produces a “ReferenceError: setTimeout is not defined” error:

node:internal/process/promises:246
          triggerUncaughtException(err, true /* fromPromise */);
          ^

[UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "ReferenceError: setTimeout is not defined".] {
  code: 'ERR_UNHANDLED_REJECTION'
}

I’m using testEnvironment: 'jsdom'. The function window.setTimeout does exist in the test, so I don’t really understand how it can appear as not defined to the test runner.

[sigveio]

Why wouldn’t I be able to spy on a global function? I understand how this could lead to testing internals of an implementation that might not contribute to a proper unit test, but that’s a decision a developer should be able to make rather than having the testing framework force this decision upon them.

I went by all the reports about it not working and thought that perhaps it was sacrificed for the fact that relying on an external library greatly simplifies things for Jest.

But actually, I was partially wrong and should have tested it more thoroughly.

After you have enabled the fake timers you can spy on the global:

jest.spyOn(global, 'setTimeout');

That said; I do still stand by my comment on it most often being more favourable not to do so.

Side note: Specifically what I’d like to still be able to do is assess whether certain calls happened in an expected order. I don’t much care about the exact processor time that elapses but rather the information that events A, B, and C happened before event D.

When you use the modern fake timers, “processor time” should not play into the millisecond timing of when a given task can be expected to run though, because time is entirely faked. So with for example jest.advanceTimersByTime() you do have a lot of power.

I would also think that tasks under fake timers would run in the natural order they are scheduled in. So if you want to ignore the exact timing… and only care about the order… then perhaps you can use jest.runAllTimers() to fast forward in time and exhaust all the queues, and then toHaveBeenNthCalledWith() to verify them?