With React Native Testing Library and jest.useFakeTimers(), how do waitFor and userEvent.setup advance the fake clock, and when must you pass advanceTimers yourself?

## Why fake timers matter in RNTL tests **React Native Testing Library (RNTL)** interactions and screens often involve real waiting: `userEvent`'s `press` holds the press for at least 130 ms because React Native's `Pressability` does, `longPress` holds for 500 ms by default, and the catalog app's search field debounces keystrokes by 400 ms before calling `searchBooks`. With real timers each of those is real wall-clock time. With Jest's fake timers the waits become instant, but only if something moves the fake clock forward. RNTL does that for you in two places. ## Detection RNTL checks the global `setTimeout` before waiting. If Jest has replaced it (a mock function for **legacy** fake timers, or a clock-backed one for **modern** fake timers), RNTL switches to fake-timer mode. The detection only recognises Jest's fake timers, and it can be disabled with the `RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS` environment variable. ## How waitFor and findBy behave under fake timers In fake-timer mode `waitFor` runs this loop: 1. Check the expectation once. 2. If the fake-time budget (`timeout`) is used up, reject with the last error. 3. Advance the fake clock by `interval` (50 ms) inside `act`, using `jest.advanceTimersByTimeAsync` for modern timers. 4. Check the expectation again, then flush pending microtasks so resolved promises can update state. 5. Repeat from step 2. Consequences worth stating in an interview: - **`timeout` counts fake time.** With the default 1000 ms, `waitFor` advances the clock by at most 1000 ms in total. A component that shows a banner after `setTimeout(..., 3000)` needs `{ timeout: 3000 }` or more, and the test still runs in milliseconds. - **You do not advance the clock by hand** around a `findBy*` or `waitFor`; doing so as well can skip past states you meant to observe. - **Do not switch timer modes mid-wait.** Calling `jest.useRealTimers()` while a fake-timer `waitFor` is pending, or the reverse, makes it reject with an error saying the timers changed during the wait. Await every async utility before switching. ## How userEvent behaves under fake timers `userEvent.setup(options)` takes two options: | Option | Default | Purpose | |---|---|---| | `delay` | `0` | Pause between consecutive inputs, such as keystrokes in `type` | | `advanceTimers` | detects Jest fake timers | Function called with each pause length to move a fake clock | Every internal pause starts a `setTimeout` and calls `advanceTimers(ms)` alongside it. The default implementation calls `jest.advanceTimersByTime(ms)` when Jest fake timers are on and does nothing under real timers. That is why, in RNTL, `userEvent.setup()` with no options works under `jest.useFakeTimers()`: the 130 ms press, the 500 ms long press and the typing delay all complete on the fake clock. You pass `advanceTimers` yourself only when time is faked by **something other than Jest**, for example a separate fake-clock library installed by a test helper; the default would not detect it, the pause's `setTimeout` would never fire, and the interaction would hang until Jest's test timeout. Passing `advanceTimers: jest.advanceTimersByTime`, the common web idiom, does the same thing under Jest fake timers, so in RNTL it is redundant. ## The catalog search test ```tsx jest.useFakeTimers(); test('debounced search shows one result', async () => { mockSearchBooks.mockResolvedValue([{ id: 'b7', title: 'Middlemarch' }]); const user = userEvent.setup(); await render(<CatalogSearch />); await user.type(screen.getByLabelText('Search catalog'), 'middle'); expect(await screen.findByText('Middlemarch')).toBeOnTheScreen(); expect(mockSearchBooks).toHaveBeenCalledTimes(1); }); ``` Typing advances the fake clock through each keystroke's zero-length pause, restarting the 400 ms debounce each time. `findByText` then steps the clock in 50 ms increments; at 400 ms the debounce fires, the mocked search resolves, microtasks are flushed, and the result renders well inside the 1000 ms fake budget. The call count is exactly one because the debounce collapsed the keystrokes. ## Why the loop is built this way Advancing in fixed `interval` steps, rather than jumping straight to the next scheduled timer, keeps the loop bounded: code that keeps scheduling new timers cannot trap `waitFor` forever, because the fake-time budget always runs out. Flushing microtasks after each check lets promise chains started by a timer, such as the debounced search call resolving and calling `setState`, finish before the next step. ## Pitfalls - Enabling fake timers after `render` means timers the mount already scheduled are real ones. - A `setTimeout` of more than the `timeout` needs a larger `timeout`, not a manual advance plus a default wait. - Jest's fake-timer API itself (`runAllTimers`, `runOnlyPendingTimers`, restoring real timers after each test) is Jest's, not RNTL's; RNTL only drives the clock inside its own waits and events.