Introduce Fantom.unstable_advanceAnimationsByTime (#51752)

Summary:
Pull Request resolved: #51752

changelog: [internal]

Introduce a way to test animations: `unstable_advanceAnimationsByTime`. An API that fakes passage of time and triggers UI ticks to simulate how animations are run on iOS and Android.

The API is marked as unstable because it might evolve as we write more tests for C++ Animated.

Reviewed By: mdvacca

Differential Revision: D75787082

fbshipit-source-id: 24e29732bbbf581871e7868289257ab60d891ddf

Author: sammy-SC

packages/react-native-fantom/src/index.js

@@ -186,6 +186,17 @@ export function runTask(task: () => void | Promise<void>) {
   runWorkLoop();
 }
 
+/**
+ * Advances the animation clock by the specified number of milliseconds.
+ * This function allows tests to simulate the passage of time for animations
+ * without actually waiting, making animation testing more efficient.
+ *
+ * @param miliseconds - The number of milliseconds to advance animations by
+ */
+export function unstable_advanceAnimationsByTime(milliseconds: number) {
+  NativeFantom.advanceAnimationsByTime(milliseconds);
+}
+
 /**
  * Simulates running a task on the UI thread and forces side effect to drain
  * the event queue, scheduling events to be dispatched to JavaScript.

packages/react-native/Libraries/Animated/__tests__/Animated-itest.js

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
+
+import type {HostInstance} from 'react-native';
+
+import ensureInstance from '../../../src/private/__tests__/utilities/ensureInstance';
+import * as Fantom from '@react-native/fantom';
+import {createRef} from 'react';
+import {Animated, useAnimatedValue} from 'react-native';
+import ReactNativeElement from 'react-native/src/private/webapis/dom/nodes/ReactNativeElement';
+
+test('moving box by 100 points', () => {
+  let _translateX;
+  const viewRef = createRef<HostInstance>();
+
+  function MyApp() {
+    const translateX = useAnimatedValue(0);
+    _translateX = translateX;
+    return (
+      <Animated.View
+        ref={viewRef}
+        style={[
+          {
+            width: 100,
+            height: 100,
+            backgroundColor: 'red',
+          },
+          {transform: [{translateX}]},
+        ]}
+        testID="box"
+      />
+    );
+  }
+
+  const root = Fantom.createRoot();
+
+  Fantom.runTask(() => {
+    root.render(<MyApp />);
+  });
+
+  const viewElement = ensureInstance(viewRef.current, ReactNativeElement);
+
+  let boundingClientRect = viewElement.getBoundingClientRect();
+
+  expect(boundingClientRect.x).toBe(0);
+
+  Fantom.runTask(() => {
+    Animated.timing(_translateX, {
+      toValue: 100,
+      duration: 1000, // 1 second
+      useNativeDriver: true,
+    }).start();
+  });
+
+  // TODO: this fails with any value below 1038, even though anything above 1000 should be enough.
+  Fantom.unstable_advanceAnimationsByTime(1038);
+  boundingClientRect = viewElement.getBoundingClientRect();
+  expect(boundingClientRect.x).toBe(100);
+
+  // TODO: this shouldn't be needed but C++ Animated still schedules a React state update
+  // for synchronisation, even though it doesn't need to.
+  Fantom.runWorkLoop();
+  boundingClientRect = viewElement.getBoundingClientRect();
+  expect(boundingClientRect.x).toBe(100);
+});

packages/react-native/src/private/testing/fantom/specs/NativeFantom.js

@@ -90,6 +90,7 @@ interface Spec extends TurboModule {
   takeMountingManagerLogs: (surfaceId: number) => Array<string>;
   flushMessageQueue: () => void;
   flushEventQueue: () => void;
+  advanceAnimationsByTime: (miliseconds: number) => void;
   validateEmptyMessageQueue: () => void;
   getRenderedOutput: (surfaceId: number, config: RenderFormatOptions) => string;
   reportTestSuiteResultsJSON: (results: string) => void;