Support Node.js fake timers

[avivkeller]

• @testing-library/react version: 16.3.0
• Testing Framework and version: node:test, 22.14.0
• DOM Environment: jsdom 26.0.0

Relevant code or config:

import { screen } from '@testing-library/react';
import { it } from 'node:test';

await it('example', async (t) => {
   t.mock.timers.enable();  // Mocking timers using Node.js test runner
   await screen.findByText('some text');  // Attempting to find text
});

What you did:

In the code above, the timers are mocked using t.mock, which is provided by the Node.js test runner. The findByText query is used to search for specific text in the rendered output.

What happened:

When running this test, the following error message is displayed:

'Promise resolution is still pending but the event loop has already resolved'

This occurs because findByText internally uses setTimeout or setInterval (i.e., timers) to wait for the text to appear, and these timers are being mocked using t.mock.timers.enable(). As a result, the timer-based mechanism in findByText does not work correctly, causing the test to fail prematurely with the error message mentioned above.

Reproduction:

1. Mock timers using t.mock.timers.enable() in the Node.js test runner.
2. Attempt to find text asynchronously using screen.findByText().
3. The error will occur when the test tries to resolve the promise.

Problem description:

The core issue is that findByText relies on timers internally to wait for the element to appear, but when these timers are mocked (using t.mock.timers.enable()), the expected behavior of waiting for the element to render is disrupted. This leads to the error:

'Promise resolution is still pending but the event loop has already resolved'

This behavior makes it difficult to use findByText in tests where timers are mocked or disabled. This can cause confusion and make it harder to test components that rely on async behavior.

Suggested solution:

One possible solution would be to handle cases where timers are mocked explicitly within the findByText query, by either:

1. Detecting whether timers are mocked and adapting the logic accordingly, or
2. Providing a way to configure findByText to explicitly use a custom timer (so the user can provide an unmocked version) or use a different timing mechanism (e.g., using async/await without relying on setTimeout).

Alternatively, allowing the user to opt-out of using timers in certain test scenarios (such as when mocking them) would be helpful.

Another workaround could be to manually wait for the element to appear without relying on findByText, using custom logic that doesn’t involve setTimeout or other mocked timers.

[avivkeller]

Could be related to

react-testing-library/src/pure.js

Line 16 in 9fc6a75

function jestFakeTimersAreEnabled() {

?

[eps1lon]

Same as #1187 but for fake Node.js timers.