Add Imperative Gesture Handler Testing API (#4309)

## Description

The goal is to make gesture lifecycle tests easier to write when we want
to assert application state after each gesture step, without requiring
users to manually construct RNGH state events with `state`, `oldState`,
or `handlerTag`.

Instead of this lower-level style:

```ts
fireGestureHandler(panGesture, [
  { oldState: State.UNDETERMINED, state: State.BEGAN },
  { oldState: State.BEGAN, state: State.ACTIVE },
  { oldState: State.ACTIVE, state: State.END },
]);
```

tests can now use imperative controller:
```ts
const gesture = createGestureController(panGesture);

gesture.begin();
expect(onBegin).toHaveBeenCalled();

gesture.activate();
expect(onActivate).toHaveBeenCalled();

gesture.update({ translationX: 50 });
expect(onUpdate).toHaveBeenCalledWith(
  expect.objectContaining({ translationX: 50 })
);

gesture.end();
expect(onFinalize).toHaveBeenCalledWith(
  expect.objectContaining({ canceled: false })
);
```

## Hook gesture rerenders

Hook-based gestures can be recreated when their callbacks or
configuration change during a React rerender while retaining the same
handler tag. The controller now resolves the latest registered gesture
before every lifecycle operation. This ensures that subsequent steps use
the newest callback closures and configuration, including the current
enabled value.

For example, if a rerender occurs between `begin()` and `activate()`,
`activate()` invokes the callback from the latest render rather than the
callback captured when the controller was created.


## Reusing a controller for another stream

A controller can now run multiple gesture streams.

After `end()`, `fail()`, or `cancel()`, the terminal state remains
available for assertions through `getState()`. Calling `begin()` again
resets the finished controller internally and starts a new stream.

```ts
controller.begin();
controller.activate();
controller.end();

expect(controller.getState()).toBe(State.END);

controller.begin();
expect(controller.getState()).toBe(State.BEGAN);
```

## Test plan

Added tests using new API.

---------

Co-authored-by: Jakub Piasecki <jakubpiasecki67@gmail.com>
Co-authored-by: Michał Bert <63123542+m-bert@users.noreply.github.com>

Author: 3 people

packages/docs-gesture-handler/docs/guides/testing.mdx

@@ -62,7 +62,119 @@ In order to load mocks provided by RNGH, add the following to your jest config:
 
 ## Testing Gestures' and Gesture handlers' callbacks
 
-RNGH provides APIs, specifically [`fireGestureHandler`](#firegesturehandler) and [`getByGestureTestId`](#getbygesturetestid), to trigger selected handlers.
+RNGH provides the following APIs for triggering selected handlers:
+
+- [`createGestureController`](#creategesturecontroller) to imperatively control a gesture lifecycle one step at a time.
+- [`fireGestureHandler`](#firegesturehandler) to dispatch a complete event stream.
+- [`getByGestureTestId`](#getbygesturetestid) to find a gesture by its test ID.
+
+### createGestureController
+
+<CollapsibleCode
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 3]}
+src={`
+import { createGestureController } from 'react-native-gesture-handler/jest-utils';
+
+createGestureController: (componentOrGesture) => GestureController;
+
+export interface GestureController<
+  TEventPayload extends Record<string, unknown> = Record<string, unknown>,
+> {
+  begin: (event?: GestureControllerEvent<TEventPayload>) => void;
+  activate: (event?: GestureControllerEvent<TEventPayload>) => void;
+  update: (event?: GestureControllerEvent<TEventPayload>) => void;
+  end: (event?: GestureControllerEvent<TEventPayload>) => void;
+  fail: (event?: GestureControllerEvent<TEventPayload>) => void;
+  cancel: (event?: GestureControllerEvent<TEventPayload>) => void;
+}
+
+export type GestureControllerEvent<
+  TEventPayload extends Record<string, unknown> = Record<string, unknown>,
+> = Partial<TEventPayload> & {
+  handlerTag?: never;
+  nativeEvent?: never;
+  oldState?: never;
+  state?: never;
+};
+`}/>
+
+Creates an imperative controller that dispatches gesture lifecycle events one step
+at a time. This allows the test to assert application state between lifecycle steps
+without manually supplying `state`, `oldState`, or `handlerTag`.
+
+`componentOrGesture` can be:
+
+- A Gesture Handler component found using a Jest query such as `getByTestId`.
+- A gesture object.
+- A gesture test ID string.
+
+When a gesture object is passed directly, the event payload type is inferred from
+the gesture. Every lifecycle method accepts an optional partial event payload and
+fills omitted handler-specific properties with defaults.
+
+The controller exposes the following methods:
+
+| Method       | Behavior                                                                                                         |
+| ------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `begin()`    | Starts a stream and calls `onBegin`. If the previous stream finished, the controller resets it before beginning. |
+| `activate()` | Activates a begun stream and calls `onActivate`.                                                                 |
+| `update()`   | Dispatches an update for an active stream and calls `onUpdate`. It can be called multiple times.                 |
+| `end()`      | Ends a begun or active stream. Calls `onDeactivate` if active, then `onFinalize` with `canceled: false`.         |
+| `fail()`     | Fails a begun or active stream. Calls `onDeactivate` if active, then `onFinalize` with `canceled: true`.         |
+| `cancel()`   | Cancels a begun or active stream. Calls `onDeactivate` if active, then `onFinalize` with `canceled: true`.       |
+
+Calling `begin()` again after `end()`, `fail()`, or `cancel()` starts another stream with the same controller.
+Calling methods in an invalid order throws an error. State-machine fields such as
+`state`, `oldState`, `handlerTag`, and `nativeEvent` cannot be supplied in event
+payloads because the controller manages them internally.
+
+```tsx
+test('updates application state after each gesture step', () => {
+  const onBegin = jest.fn();
+  const onActivate = jest.fn();
+  const onUpdate = jest.fn();
+  const onDeactivate = jest.fn();
+  const onFinalize = jest.fn();
+
+  const panGesture = renderHook(() =>
+    usePanGesture({
+      disableReanimated: true,
+      onBegin,
+      onActivate,
+      onUpdate,
+      onDeactivate,
+      onFinalize,
+    })
+  ).result.current;
+
+  const controller = createGestureController(panGesture);
+
+  controller.begin();
+  expect(onBegin).toHaveBeenCalledTimes(1);
+
+  controller.activate();
+  expect(onActivate).toHaveBeenCalledTimes(1);
+
+  controller.update({ translationX: 50 });
+  expect(onUpdate).toHaveBeenCalledWith(
+    expect.objectContaining({ translationX: 50 })
+  );
+
+  controller.end();
+  expect(onDeactivate).toHaveBeenCalledTimes(1);
+  expect(onFinalize).toHaveBeenCalledWith(
+    expect.objectContaining({ canceled: false })
+  );
+});
+```
+
+:::note
+`createGestureController` controls lifecycle events directly. It does not generate
+pointer input, run platform gesture recognizers, or evaluate relations between
+gestures.
+:::
 
 ### fireGestureHandler
 
@@ -133,7 +245,7 @@ components.
 `testID` must be unique among components rendered in test.
 :::
 
-## Example
+## fireGestureHandler example
 
 Extracted from RNGH tests, check [`api_v3.test.tsx`](https://github.com/software-mansion/react-native-gesture-handler/blob/main/packages/react-native-gesture-handler/src/__tests__/api_v3.test.tsx) for full implementation.
 

packages/react-native-gesture-handler/src/__tests__/Errors.test.tsx

@@ -65,7 +65,10 @@ describe('VirtualDetector', () => {
 
     function InterceptingDetectorMultipleTypes() {
       const tap = useTapGesture({ useAnimated: true });
-      const tap2 = useTapGesture({ onActivate: mockWorklet });
+      const tap2 = useTapGesture({
+        disableReanimated: false,
+        onActivate: mockWorklet,
+      });
       return (
         <GestureHandlerRootView>
           <InterceptingGestureDetector gesture={tap}>