jest.fn().waitUntilCalledNTimes() Feature

[benjaminkay93]

🚀 Feature Proposal

Add some kind to feature to jest to wait until a mock function has been called n times.

Motivation

We have an API that recursively sends periodic notifications to another service, we need to check that this works, we currently have a setTimeout wrapped in a promise to make the test wait for a period thats deffinetly longer than needed.

Example

test('some test', async () => {
  const someMock = jest.fn()

  await someMock.waitUntilCalledNTimes(n) // on the nth call, continue.

  expect(someOtherMock).hasBeenCalled()
})

Pitch

Why does this feature belong in the Jest core platform?

It would be an addition to the core jest mocking ability, allowing for dynamic tests ensuring that a function has to of been called n times before moving on to check for its asssertions

Im happy to give this ago myself, if its something thats wanted

[rickhanlonii]

@benjaminkay93 very cool!

I think this is probably best to implement in user land rather than core. If you have something simple and reusable though, we could look into adding it to jest-extended

[SimenB]

await waitForExpect(() => {
  expect(someMock).toHaveBeenCalledTimes(n);
});

https://www.npmjs.com/package/wait-for-expect

Is that enough?

[benjaminkay93]

Well the specific issue that brought this up @SimenB was that the function we are testing doesn’t return the promise where we are wanting to test. So we can’t wait for it to resolve. @rickhanlonii I don’t think we could directly put this in user land? Unless you know of a way to event trigger from the calls of a mock function?

I’ll write a clearer example of the problem below (just on my phone writing this aha)

[benjaminkay93]

so this is the simplified code we have. We have to have our delay between events at least 30 seconds in production, we are artificially lowing this in the tests to like 1 millisecond, but even then we have to put a manual delay in our test, as the recursive calling never makes it back to the original thread that called it. we are mocking out request.post() inside sendPayload and we need to make sure it is called 3 times.

Hence this feature request, if we could say await request.post.waitUntillCalledTimes(3) we would be able to have the test take only as long as we needed it too aha

const delay = async (timeout) => new Promise(resolve) => setTimeout(resolve, timeout)

const someReplayMechanism = async (preparedArrayResponse) => {
  if (preparedArrayResponse.length === 0) {
    return 'done'
  }

  const response = preparedArrayResponse[0]

  await sendPayload(response)
  await delay(30000)
  preparedArrayResponse.shift()

  someReplayMechanism(preparedArrayResponse)
}

const someApiEndpoint = (req) => {
  const preparedArrayResponse = someDataTransformations(req.body)
  someReplayMechanism(preparedArrayResponse)
  return 'Replay Started!'
}

[rickhanlonii]

Thanks for the additional info @benjaminkay93

Have you see toHaveBeenNthCalledWith? Would that be useful for you here?

test('some test', async () => {
  const someMock = jest.fn()

  // n calls

  expect(someOtherMock).toHaveBeenNthCalledWith(n, args)
})

Not sure that this request is a common enough use case to justify adding to core, even if it could only be implemented in core

[SimenB]

@benjaminkay93 can you put together an example that runs bu fails, and is just missing some waitUntilCalledNTimes for the test to pass properly?

[benjaminkay93]

So an example failing test for the above code would be

import { someApiEndpoint } form '../api-manager'
import helper from '../helpers'

test('some api endpoint test', () => {
  helper.sendPayload = jest.fn()

  const req = {body: [ 'some', 'array' ]}
  const response = someApiEndpoint(req)

  expect(response).toBe('Replay Started!')
  expect(helper.sendPayload).toHaveBeenCalledTimes(2) // Fails as it would never of been called 
})

[benjaminkay93]

where the code looks like

import helper from './helpers'

const delay = async (timeout) => new Promise(resolve) => setTimeout(resolve, timeout)

const someReplayMechanism = async (preparedArrayResponse) => {
  if (preparedArrayResponse.length === 0) {
    return 'done'
  }

  const response = preparedArrayResponse[0]

  await helper.sendPayload(response)
  await delay(30000)
  preparedArrayResponse.shift()

  someReplayMechanism(preparedArrayResponse)
}

const someApiEndpoint = (req) => {
  const preparedArrayResponse = someDataTransformations(req.body)
  someReplayMechanism(preparedArrayResponse)
  return 'Replay Started!'
}

[rickhanlonii]

Hm, I'm pretty confused by this. Should you be returning a promise in someApiEndpoint so you can wait on it? Are you creating promises without completing them?

[benjaminkay93]

sorry its my lack of ability to explain things properly, ill try again hopefully I make sense this time.

so its designed to call off to someReplayMechanism and then return, allowing for the task to run in the back ground with no interaction from the main thread.

someReplayMechanism will take a long time to run in the background, so we can't wait for that to resolve in production, before returning, hence not waiting for it in someApiEndpoint, the return is there just so we know its started, progress can be monitored in other ways on other endpoints.

to test this, we have to have a set timeout currently to an arbitrary length that we feel is long enough to make sure everything is called. I know its niche but I think this is something that might of come up before as its definitely the second time I've had to do this, and the arbitrary delay isn't pretty aha

an example of the current test, and and ideal test is below, hope it helps :)

Current

import { someApiEndpoint } form '../api-manager'
import helper from '../helpers'

const delay = async (timeout) => new Promise(resolve) => setTimeout(resolve, timeout)

test('some api endpoint test', async () => {
  helper.sendPayload = jest.fn()

  const req = {body: [ 'some', 'array' ]}
  const response = someApiEndpoint(req)

  expect(response).toBe('Replay Started!')

  await delay(2) // note an artbitary time here, (this is assuming defat is mocked out to be 1 ms in code)

  expect(helper.sendPayload).toHaveBeenCalledTimes(2)
})

Ideal

import { someApiEndpoint } form '../api-manager'
import helper from '../helpers'

const delay = async (timeout) => new Promise(resolve) => setTimeout(resolve, timeout)

test('some api endpoint test', async () => {
  helper.sendPayload = jest.fn()

  const req = {body: [ 'some', 'array' ]}
  const response = someApiEndpoint(req)

  expect(response).toBe('Replay Started!')

  await helper.sendPayload.waitToHaveBeenCalled(2) // explicit number of calls to be made then continue with assertions

  expect(helper.sendPayload).toHaveBeenCalledTimes(2) // I know here redundant but in actual code we have many calls out to things that could be assert to of happened twice
})

I hope that helps?

[rickhanlonii]

Yeah that makes sense @benjaminkay93

I think this makes more sense in userland, as you said, it's pretty niche

Here's an example of how you could implement, let me know what you think

import { someApiEndpoint } form '../api-manager'
import helper from '../helpers'

const createWaitableMock = () => {
  let resolve;
  let times;
  let calledCount = 0;
  const mock = jest.fn();
  mock.mockImplementation(() => {
    calledCount +=1;
    if (resolve && calledCount >= times) {
      resolve(); 
    }
  });

  
  mock.waitToHaveBeenCalled = t => {
    times = t;
    return new Promise(r => {
      resolve = r;
    })
  }

  return mock;
}

test('some api endpoint test', async () => {
  helper.sendPayload = createWaitableMock();

  const req = {body: [ 'some', 'array' ]}
  const response = someApiEndpoint(req)

  expect(response).toBe('Replay Started!')

  await helper.sendPayload.waitToHaveBeenCalled(2) // explicit number of calls to be made then continue with assertions

  expect(helper.sendPayload).toHaveBeenCalledTimes(2) // I know here redundant but in actual code we have many calls out to things that could be assert to of happened twice
})

[SimenB]

I'm not sure why my suggestion of using wait-for-expect is not enough.

import waitForExpect from 'wait-for-expect'
import { someApiEndpoint } form '../api-manager'
import helper from '../helpers'

test('some api endpoint test', async () => {
  helper.sendPayload = jest.fn()

  const req = {body: [ 'some', 'array' ]}
  const response = someApiEndpoint(req)

  expect(response).toBe('Replay Started!')

  await waitForExpect(() => {
    expect(helper.sendPayload).toHaveBeenCalledTimes(2)
  })

  // do other assertions
})

[benjaminkay93]

Yeah that would work a treat :) something to bear in mind if anyone ever asks for something like this again, been a good discussion, ta :)

[benjaminkay93]

Sorry @SimenB I must of just missed the entirety of the context of your earlier suggestion for this, I'm full of a flu so I'm gonna use that as my defence for missing that, that should work, ta :)

[SimenB]

Perfect!