diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index c830e0ab7295..6825b67a9ea6 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -989,6 +989,16 @@ This function is not available when using legacy fake timers implementation. ::: +### `jest.runToFrame()` + +Advances all timers by the needed milliseconds to execute the next animation frame. This function is a helpful way to execute code that is scheduled using `requestAnimationFrame`. + +:::info + +This function is not available when using legacy fake timers implementation. + +::: + ### `jest.clearAllTimers()` Removes any pending timers from the timer system. diff --git a/docs/TimerMocks.md b/docs/TimerMocks.md index 1e0260c7def6..c8663a87cac3 100644 --- a/docs/TimerMocks.md +++ b/docs/TimerMocks.md @@ -167,6 +167,28 @@ it('calls the callback after 1 second via advanceTimersByTime', () => { Lastly, it may occasionally be useful in some tests to be able to clear all of the pending timers. For this, we have `jest.clearAllTimers()`. +## Advance Timers by frame + +In applications, often you want to schedule work inside of an animation frame (via `requestAnimationFrame`). We expose a convenance method `jest.runToFrame()` to advance all timers enough to execute all actively scheduled animation frames. + +```javascript +jest.useFakeTimers(); +it('calls the animation frame callback after runToFrame()', () => { + const callback = jest.fn(); + + requestAnimationFrame(callback); + + // At this point in time, the callback should not have been called yet + expect(callback).not.toBeCalled(); + + jest.runToFrame(); + + // Now our callback should have been called! + expect(callback).toBeCalled(); + expect(callback).toHaveBeenCalledTimes(1); +}); +``` + ## Selective Faking Sometimes your code may require to avoid overwriting the original implementation of one or another API. If that is the case, you can use `doNotFake` option. For example, here is how you could provide a custom mock function for `performance.mark()` in jsdom environment: