renaming to jest.advanceTimersToNextFrame

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));