renaming to jest.advanceTimersToNextFrame

Author: alexreardon

docs/JestObjectAPI.md

@@ -989,7 +989,7 @@ This function is not available when using legacy fake timers implementation.
 
 :::
 
-### `jest.runToFrame()`
+### `jest.advanceTimersToNextFrame()`
 
 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`.
 

docs/TimerMocks.md

@@ -167,21 +167,23 @@ 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 to next Frame
+## Advance Timers to the next 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 milliseconds to execute all actively scheduled animation frames.
+In applications, often you want to schedule work inside of an animation frame (with `requestAnimationFrame`). We expose a convenience method `jest.advanceTimersToNextFrame()` to advance all timers enough milliseconds to execute all actively scheduled animation frames.
+
+For mock timing purposes, animation frames are executed every `16ms` (mapping to roughly `60` frames per second) after the clock starts. When you schedule a callback in an animation frame (with `requestAnimationFrame(callback)`), the `callback` will be called when the clock has advanced `16ms`. `jest.advanceTimersToNextFrame()` will advance the clock just enough to get to the next `16ms` increment. If the clock has already advanced `6ms` since a animation frame `callback` was scheduled, then the clock will be advanced by `10ms`.
 
 ```javascript
 jest.useFakeTimers();
-it('calls the animation frame callback after runToFrame()', () => {
+it('calls the animation frame callback after advanceTimersToNextFrame()', () => {
   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();
+  jest.advanceTimersToNextFrame();
 
   // Now our callback should have been called!
   expect(callback).toBeCalled();

packages/jest-environment/src/index.ts

@@ -67,6 +67,14 @@ export interface Jest {
    * Not available when using legacy fake timers implementation.
    */
   advanceTimersByTimeAsync(msToRun: number): Promise<void>;
+  /**
+   * Advances all timers by the needed milliseconds to execute currently scheduled animation frames.
+   * `advanceTimersToNextFrame()` helpful way to execute code that is scheduled using `requestAnimationFrame`.
+   *
+   * @remarks
+   * Not available when using legacy fake timers implementation.
+   */
+  advanceTimersToNextFrame(): void;
   /**
    * Advances all timers by the needed milliseconds so that only the next
    * timeouts/intervals will run. Optionally, you can provide steps, so it will
@@ -349,14 +357,6 @@ export interface Jest {
    * It is recommended to use `jest.mock()` instead. The `jest.mock()` API's second
    * argument is a module factory instead of the expected exported module object.
    */
-  /**
-   * Advances all timers by the needed milliseconds to execute the next animation frame.
-   * `runToFrame()` helpful way to execute code that is scheduled using `requestAnimationFrame`.
-   *
-   * @remarks
-   * Not available when using legacy fake timers implementation.
-   */
-  runToFrame(): void;
   setMock(moduleName: string, moduleExports: unknown): Jest;
   /**
    * Set the current system time used by fake timers. Simulates a user changing

packages/jest-fake-timers/src/__tests__/modernFakeTimers.test.ts

@@ -594,7 +594,7 @@ describe('FakeTimers', () => {
     });
   });
 
-  describe('runToFrame', () => {
+  describe('advanceTimersToNextFrame', () => {
     it('runs scheduled animation frames in order', () => {
       const global = {
         Date,
@@ -616,7 +616,7 @@ describe('FakeTimers', () => {
       global.requestAnimationFrame(mock2);
       global.requestAnimationFrame(mock3);
 
-      timers.runToFrame();
+      timers.advanceTimersToNextFrame();
 
       expect(runOrder).toEqual(['mock1', 'mock2', 'mock3']);
     });
@@ -644,11 +644,11 @@ describe('FakeTimers', () => {
       global.requestAnimationFrame(run);
 
       // only the first frame should be executed
-      timers.runToFrame();
+      timers.advanceTimersToNextFrame();
 
       expect(runOrder).toEqual(['first-frame']);
 
-      timers.runToFrame();
+      timers.advanceTimersToNextFrame();
 
       expect(runOrder).toEqual(['first-frame', 'second-frame']);
     });
@@ -673,7 +673,7 @@ describe('FakeTimers', () => {
       global.cancelAnimationFrame(timerId);
 
       // no frames should be executed
-      timers.runToFrame();
+      timers.advanceTimersToNextFrame();
 
       expect(runOrder).toEqual([]);
     });
@@ -705,7 +705,7 @@ describe('FakeTimers', () => {
       expect(runOrder).toEqual([]);
 
       // move timers forward to execute frame
-      timers.runToFrame();
+      timers.advanceTimersToNextFrame();
 
       // frame has executed as time has moved forward 10ms to get to the 16ms frame time
       expect(runOrder).toEqual(['frame']);
@@ -733,7 +733,7 @@ describe('FakeTimers', () => {
       global.setTimeout(() => runOrder.push('timeout'), 10);
 
       // move timers forward to execute frame
-      timers.runToFrame();
+      timers.advanceTimersToNextFrame();
 
       expect(runOrder).toEqual(['timeout', 'frame']);
     });
@@ -759,7 +759,7 @@ describe('FakeTimers', () => {
         global.setTimeout(() => runOrder.push('timeout'), 1);
       });
 
-      timers.runToFrame();
+      timers.advanceTimersToNextFrame();
 
       // timeout not yet executed
       expect(runOrder).toEqual(['frame']);

packages/jest-fake-timers/src/modernFakeTimers.ts

@@ -110,16 +110,16 @@ export default class FakeTimers {
     }
   }
 
-  runAllTicks(): void {
+  advanceTimersToNextFrame(): void {
     if (this._checkFakeTimers()) {
-      // @ts-expect-error - doesn't exist?
-      this._clock.runMicrotasks();
+      this._clock.runToFrame();
     }
   }
 
-  runToFrame(): void {
+  runAllTicks(): void {
     if (this._checkFakeTimers()) {
-      this._clock.runToFrame();
+      // @ts-expect-error - doesn't exist?
+      this._clock.runMicrotasks();
     }
   }
 

packages/jest-runtime/src/index.ts

@@ -2289,6 +2289,16 @@ export default class Runtime {
           );
         }
       },
+      advanceTimersToNextFrame: () => {
+        const fakeTimers = _getFakeTimers();
+
+        if (fakeTimers === this._environment.fakeTimersModern) {
+          return fakeTimers.advanceTimersToNextFrame();
+        }
+        throw new TypeError(
+          '`jest.advanceTimersToNextFrame()` is not available when using legacy fake timers.',
+        );
+      },
       advanceTimersToNextTimer: steps =>
         _getFakeTimers().advanceTimersToNextTimer(steps),
       advanceTimersToNextTimerAsync: async steps => {
@@ -2403,16 +2413,6 @@ export default class Runtime {
           );
         }
       },
-      runToFrame: () => {
-        const fakeTimers = _getFakeTimers();
-
-        if (fakeTimers === this._environment.fakeTimersModern) {
-          return fakeTimers.runToFrame();
-        }
-        throw new TypeError(
-          '`jest.runToFrame()` is not available when using legacy fake timers.',
-        );
-      },
       setMock: (moduleName, mock) => setMockFactory(moduleName, () => mock),
       setSystemTime: now => {
         const fakeTimers = _getFakeTimers();

packages/jest-types/__typetests__/jest.test.ts

@@ -527,9 +527,9 @@ expectError(jest.runOnlyPendingTimers(true));
 expectType<Promise<void>>(jest.runOnlyPendingTimersAsync());
 expectError(jest.runOnlyPendingTimersAsync(true));
 
-expectType<void>(jest.runToFrame());
-expectError(jest.runToFrame(true));
-expectError(jest.runToFrame(100));
+expectType<void>(jest.advanceTimersToNextFrame());
+expectError(jest.advanceTimersToNextFrame(true));
+expectError(jest.advanceTimersToNextFrame(100));
 
 expectType<void>(jest.setSystemTime());
 expectType<void>(jest.setSystemTime(1_483_228_800_000));