`waitFor` doesn't work if jest fake timers are used

[DennisSkoko]

• react-hooks-testing-library version: 7.0.0
• react version: 17.0.2
• react-dom version: 17.0.2
• node version: 14.16.0
• npm version: 7.10.0

Problem

When using waitFor when Jest has been configured to use fake timers then the waitFor will not work and only "polls" once. After that the test just hangs until Jest comes in and fails the test with that the test exceeds the timeout time. Below is some code that showcases the problem.

import { renderHook } from '@testing-library/react-hooks'

it('does not work', async () => {
  jest.useFakeTimers()

  const { waitFor } = renderHook(() => {})

  await waitFor(() => {
    console.log('poll') // Is printed just once
    expect(false).toBe(true)
  }, { timeout: 25, interval: 10 })

  // Fails with Exceeded timeout of 5000 ms for a test.
})

Basically the waitFor from @testing-library/react-hooks is using the faked setTimeout or setInterval which prevents it from working correctly.

There is a workaround (see suggested solution) but I recommend providing a nice error message when waitFor is used together with faked timers or maybe change the implemenation so it will work with fake timers.

Suggested solution

I found this issue and it seems that person has already been fixed in @testing-library/dom. From my perspective I can suggest maybe reuse that function instead of implementing it yourselves but I don't really know the internal structure / code.

But after finding that issue and realizing that is has been fixed there, then I use the following code as a workaround which works fine.

import { waitFor } from '@testing-library/react'

it('works', async () => {
  jest.useFakeTimers()

  await waitFor(() => {
    console.log('poll') // Is printed twice
    expect(false).toBe(true)
  }, { timeout: 25, interval: 10 })

  // Fails with false is not equal to true
})

A more real world scenario

If curios on the actual problem I'm facing is to test the following hook:

function useSomething({ onSuccess }) {
  const poll = useCallback(async () => {
    const result = await fetch(/* ... */)
    if (result.ok) onSuccess()
  }, [onSuccess])

  useEffect(() => {
    const id = setInterval(() => { poll() }, 2000)
    return () => clearInterval(id)
  }, [poll])
}

What I want to do is test that it invokes the onSuccess function on a successfull poll.

it('invokes the `onSuccess` on successfull poll', async () => {
  const onSuccess = jest.fn()
  jest.useFakeTimers()

  const { waitFor } = renderHook(() => useSomething({ onSuccess }))

  jest.runOnlyPendingTimers()
  await waitFor(() => expect(onSuccess).toHaveBeenCalled())
})

[mpeyper]

When I was reading this I was thinking the only way I could think of solving it would be to query jest about the timers, so it's interesting that that's effectively how they solved it in dom-testing-library.

Unfortunately we can use the same function as we do not depend on it, or the DOM in general, which their solution uses. That said, the way we waitFor is similar so we can likely take some clues from them.

If anyone is interested in working on the fix for this, I'm more than happy the help you out.

[chris110408]

@mpeyper
I would like to contribute, I think the outline for this solution will be a similar solution used by dom-testing-library

1. We detect if we're in an environment that's faking out timers.
   for this step, I have a question, should we use their helper or we need helps by ourselves for the jestFakeTimersAreEnabled function and the setImmediateFn

  function jestFakeTimersAreEnabled() {
    return hasJestTimers()
        ? usedFakeTimers
        :false
  }


 function hasJestTimers() {
    return (
        typeof jest !== 'undefined' &&
        jest !== null &&
        typeof jest.useRealTimers === 'function'
    )
  }

  const usedFakeTimers = Object.entries(timerAPI).some(
      ([name, func]) => func !== globalObj[name],
  )

const globalObj = typeof window === 'undefined' ? global : window


let   setImmediateFn = globalObj.setImmediate || setImmediatePolyfill,

function setImmediatePolyfill(fn) {
  return globalObj.setTimeout(fn, 0)
}

2. Revise wait function

 const wait = async (callback: () => boolean | void, { interval, timeout }: WaitOptions) => {
    ....
   const waitForFakeTimer=async (interval)=>{
      let finished = false
      while (!finished) {
        if (!jestFakeTimersAreEnabled()) {
           throw new Error(
              `Changed from using fake timers to real timers while using waitFor. This is not allowed and will result in very strange behavior. Please ensure you're awaiting all async things your test is doing before changing to real timers. For more info, please go to https://github.com/testing-library/dom-testing-library/issues/830`,
          )
        }
        jest.advanceTimersByTime(interval)
        await new Promise(r => setImmediate(r))
      }
    }
  ....
    if (!checkResult()) {
     
   ....
      await act(() => Promise.race([waitForResult(), timeoutPromise(),usingJestFakeTimers && waitForFakeTimer(interval)].filter(Boolean)))
      } else {
        await act(() => Promise.race([waitForResult(),usingJestFakeTimers && waitForFakeTimer(interval)].filter(Boolean)))
      }

}

[mpeyper]

Sorry for the delay in responding @chris110408. Any contributions towards this are very welcome.

I think taking a similar approach to dom-testing-library is a good idea and I proposed solution seems fine to me (assuming it works).

My only other thought is the inclusion of timeoutPromise() or not in the race feels like it could be achievable with the .filter(Boolean) as well, but I'll hold judgement on the readability until the PR 😉.

[chris110408]

Thanks @mpeyper I will work on the PR

[chris110408]

I have been trying to find the fix for a typescript error.

I am not sure how to fix it yet. and I am not able to use // @ts-ignore to quickly fix it.
I guess I also should not use // eslint-disable-next-line @typescript-eslint/ban-ts-comment // @ts-expect-error 😄
@mpeyper I need some help for this problem

[mpeyper]

Give this a shot:

  Object.entries(timerAPI).some(
    ([name, func]) =>  func !== globalObj[name as keyof typeof timerAPI]
  )

Object.entries returns [string, T][] so you need to destructure the tuple (the ([name, func]) => ... change) and the first index of the tuple is annoyingly a string instead the the keys of the object (there are reasons for this though, so it needs to be cast in order to use it as an index of globalObj.

Hope this helps.

[chris110408]

Give this a shot:

  Object.entries(timerAPI).some(
    ([name, func]) =>  func !== globalObj[name as keyof typeof timerAPI]
  )

Object.entries returns [string, T][] so you need to destructure the tuple (the ([name, func]) => ... change) and the first index of the tuple is annoyingly a string instead the the keys of the object (there are reasons for this though, so it needs to be cast in order to use it as an index of globalObj.

Hope this helps.

It works
Thanks a lot for the explanation

[chris110408]

@mpeyper
I has been working on this issue recently,
I changed the fackerTimer detection code to this

const usedFakeTimers = ()=>!!(global.setTimeout.mock||global.setTimeout.clock)

However, I have a hard time to understand the issue,

import { renderHook } from '@testing-library/react-hooks'

it('does not work', async () => {
  jest.useFakeTimers()

  const { waitFor } = renderHook(() => {})

  await waitFor(() => {
    console.log('poll') // Is printed just once
    expect(false).toBe(true)
  }, { timeout: 25, interval: 10 })

  // Fails with Exceeded timeout of 5000 ms for a test.
})

this test will never pass no matter we use useFakeTimers or not.

and I change the test code to

it('useFakeTimers test', async () => {
        jest.useFakeTimers()
        const { waitFor } = renderHook(() =>{})

        let actual = 0
        const expected = 1

        setTimeout(() => {
                actual = expected
        }, 200)
// show Fails with Exceeded timeout of 5000 ms for a test. if we do not use  jest.advanceTimersByTime(200)
        jest.advanceTimersByTime(200)
        let complete = false
        await waitFor(() => {
                expect(actual).toBe(expected)
                complete = true
        },{ interval: 50 })
        expect(complete).toBe(true)
})

our test library does not have any problem running it.

Could you please help me confirm what is our problem here?

Should I just add this unit test to prove waitFor works when using jest.useFakeTimers() ?

[mpeyper]

To be honest, I don't use fake timers when I write tests, so I'm also unsure of what the desired outcome is.

I think the difference you have here is advanceTimersByTime is going to advance the internal timers as well, even as new timers are created for the different intervals, but runOnlyPendingTimers will only advance existing timers and the new ones never advance.

@DennisSkoko is there more info you can provide to help @chris110408 out?

[chris110408]

To be honest, I don't use fake timers when I write tests, so I'm also unsure of what the desired outcome is.

I think the difference you have here is advanceTimersByTime is going to advance the internal timers as well, even as new timers are created for the different intervals, but runOnlyPendingTimers will only advance existing timers and the new ones never advance.

@DennisSkoko is there more info you can provide to help @chris110408 out?

@DennisSkoko @mpeyper

I add another test that uses the runOnlyPendingTimers and useFakeTimer and both test successfully pass

[mpeyper]

Now I'm even more confused about what the actual issue is here. There must be a reason dom-testing-library has such an implementation?

Do they want it to work automagically without explicitly advancing the timers? (Some of the samples provided imply this)

[chris110408]

Now I'm even more confused about what the actual issue is here. There must be a reason dom-testing-library has such an implementation?

Do they want it to work automagically without explicitly advancing the timers? (Some of the samples provided imply this)

I am also confused about the actual issue. Yes, the dom-testing-library solution is useFakeTimer and without explicitly advancing the timers? in the test. However, I think it is comment practice to use advanceTimersByTime when use useFakeTimeber in the test. (I have not to use useFakeTimer before. my assumption was made by reading the Jest document the timer mock is used for setting up a testing environment not depend on real-time to elapse and jest mock timer functions that allow you to control the passage of time ) and I am not sure why they make it work automagically without explicitly advancing the timers? Please let me know if you want me to make the wait for function of react-hooks-testing-library works in that way.