Support for useReanimatedGestureHandler in Jest

[piaskowyk]

Description

I want to add support for useReanimatedGestureHandler in Jest tests and I want to make it user-friendly. So I added configuration for events, ready to use in Jest.

Related PR: software-mansion/react-native-reanimated#2747

Test plan

1. Apply patch - https://patch-diff.githubusercontent.com/raw/software-mansion/react-native-reanimated/pull/2747.patch
2. Run:

yarn test -i Event

Example usage

import { 
  fireGestureHandlerPan,
  ghTagEventMacro
} from '../src/jestUtils'

// ...

const eventHandler = useAnimatedGestureHandler({
  onStart: () => props.begin(),
  onActive: () => props.progress(),
  onEnd: () => props.end()
});

<TapGestureHandler onHandlerStateChange={eventHandler}>
  <Text {...ghTagEventMacro()}>TapGestureHandlerTest</Text>
</TapGestureHandler>

// ...

test('test fireGestureHandlerPan', () => {
  const begin = jest.fn();
  const { getByText } = render(<App begin={begin} ... />);

  firePanGestureHandler(
    getByText('PanGestureHandlerTest'),
    { 
      configBegin: { x: 1, y: 1 },
      configProgress: [{ x: 2, y: 2 }, { x: 3, y: 3 }],
      configEnd: { x: 4, y: 4 }
    },
  );
  
  expect(eventFunctions.begin).toHaveBeenCalledTimes(1);
});

[j-piasecki]

Suggested change

	const sendProgressEventFirst: SendEventWrapper = (
	const sendActivateEvent: SendEventWrapper = (

Since it's sending a StateChangeEvent I would put the state in the method name like it is with other states.

[j-piasecki]

Suggested change

	states = { oldState: 2, state: 2 };
	states = { oldState: 2, state: 3 };

Is it a typo, or is there a reason for it?

[j-piasecki]

Only one of those should be sent at a time - gesture cannot end and fail or be cancelled at the same time. (END state means that the gesture finished because the user stopped interaction, i.e. the gesture finished "successfully").

[j-piasecki]

I think this approach will fail when there are two handlers of the same type attached to the same view, then there is no way to send an event to only one of them.
This has a use case for detecting a single and double tap on a view, or a fling with separate handlers for each direction.

[j-piasecki]

Suggested change

	eventData?: FireGestureHandlerConfig<RotationConfig>
	eventData?: FireGestureHandlerConfig<TapConfig>

I'm not sure if sharing a config type between Tap and Fling is a good idea even though they have exactly the same properties. It may be confusing when looking at the API.

[j-piasecki]

Suggested change

	eventData?: FireGestureHandlerConfig<RotationConfig>
	eventData?: FireGestureHandlerConfig<PinchConfig>

[j-piasecki]

There is no need to handle onFinish separately. useAnimatedGestureHandler implements a state machine that calls it when it receives a StateChangeEvent where oldState is either ACTIVE or BEGAN, and the state is not (so it must be END, FAILED, CANCELLED or UNDETERMINED).

[j-piasecki]

This is a potential problem, as handlerTag is initialized in the attachHandlers method which is called in the useEffect hook. This has a value of -1 here.

[j-piasecki]

Suggested change

	onStart: handlers.onBegin,
	onActive: handlers.onUpdate,
	onEnd: handlers.onEnd,
	onFinish: handlers.onFinalize,
	// this one passes the context to the onBegin callback, but I think it's fine in tests
	onStart: handlers.onBegin,
	onActive: (event, context) => {
	// useAnimatedGestureHandler passes all events with state === 4 (ACTIVE) to the onActive
	// callback, event the StateChangeEvent from 2 (BEGAN) to 4. Since the StateChangeEvent
	// will always be the first in the new state we can just check a flag here.
	if (context.active) {
	handlers.onUpdate?.(event);
	} else {
	handlers.onStart?.(event);
	context.active = true;
	}
	},
	onEnd: (event, context) => {
	// in the new API onEnd, onFail and onCancel callbacks are merged into one, because
	// - from the user's perspective there is no meaningfull difference between gesture failing
	// and being cancelled, so having separate callbacks for it makes no sense
	// - most of the time you want to clean up after the gesture in all of those callbacks,
	// so there is no point in repeating the same logic three times
	// new onEnd callback receives a bool as the second argument which tells whether the gesture
	// has finished gracefully or not, and if you really need to know if it failed or was cancelled
	// you can chech the state property of event
	handlers.onEnd?.(event, true);
	context.success = true;
	},
	onCancel: (event, context) => {
	handlers.onEnd?.(event, false);
	context.success = false;
	},
	onFail: (event, context) => {
	handlers.onEnd?.(event, false);
	context.success = false;
	},
	onFinish: (event, context) => {
	// onFinalize, like onEnd, requires a flag that tells whether the gesture finished gracefully
	handlers.onFinalize?.(event, context.success ?? false);
	},

[j-piasecki]

I'm not sure if emulating the new API using the old one is the best approach.

[j-piasecki]

I think this may fail if you were to use your own component as a child of GestureDetector, then its inner structure wouldn't be decorated. In case of gesture handlers it shouldn't matter that much since they required a native view as a direct child.

[jgonet]

Superseded by #1844.