[Feature]: Jest should expose @sinonjs/fake-timers async APIs

[yjaaidi]

🚀 Feature Proposal

Jest should expose @sinonjs/fake-timers async APIs: tickAsync(time), nextAsync(), runAllAsync() & runToLastAsync().

Motivation

There are circumstances where microtasks should be flushed between different timers.
This will often happen when the system under test is mixing microtasks (promises, async / await) and timers.

🚫 Here is an example that will not work:

const spy = jest.fn();

setTimeout(async () => {
  await Promise.resolve();
  setTimeout(spy, 10);
}, 10);

jest.advanceTimersByTime(20);

expect(spy).toBeCalled();

🫤 The common way of testing this with jest needs coupling the test to implementation details as one must know that they have to advance the timer, flush some microtasks and advance the second timer with a logic similar to this one.

const spy = jest.fn();

setTimeout(async () => {
  await Promise.resolve();
  setTimeout(spy, 10);
}, 10);

jest.advanceTimersByTime(10);
await flushMicrotasks()
jest.advanceTimersByTime(10);

expect(spy).toBeCalled();

where one must implement a custom function like this one to manually flush microtasks:

async function flushMicrotasks() {
  await new Promise(resolve => jest.requireActual('timers').setImmediate(resolve));
}

✅ Sinon's async API makes it easier as it will flush microtasks when necessary:

const spy = jest.fn();

setTimeout(async () => {
  await Promise.resolve();
  setTimeout(spy, 10);
}, 10);

await clock.tickAsync(20);

expect(spy).toBeCalled();

Example

This could look like this:

const spy = jest.fn();

setTimeout(async () => {
  await Promise.resolve();
  setTimeout(spy, 10);
}, 10);

await jest.tickAsync(20);

expect(spy).toBeCalled();

Pitch

While this will of course increase the Jest surface, this will help with:

• making the tests more maintainable & stable
• not having to manually set up sinon fake timers as it's hard to decide when one should use jest timers or sinon's
• encourage developers to write tests

Cf. related issues & problems

• Provide an API to flush the Promise resolution queue #2157
• https://stackoverflow.com/questions/44741102/how-to-make-jest-wait-for-all-asynchronous-code-to-finish-execution-before-expec
• https://salesforce.stackexchange.com/questions/310307/in-an-unit-test-for-an-lwc-how-can-i-prove-an-async-chain-is-setting-a-value-in

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[SimenB]

Happy to take a PR adding this 👍

[yjaaidi]

Hi @SimenB! Sorry that I just noticed your reply.
I'll be happy to help with a PR as soon as I can!

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[SimenB]

https://github.com/facebook/jest/releases/tag/v29.5.0

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.