Add fireGesture jest API#4301
Draft
coado wants to merge 10 commits into
Draft
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a new v3-first Jest testing helper, fireGesture(target, scenario?), for simulating a gesture’s JS callback lifecycle using the production v3 event pipeline (including derived “change” fields), while also extracting the web gesture arbitration logic into a reusable, platform-neutral GestureArbitrator core.
Changes:
- Introduces
fireGesture+ scenario types/builders, backed by a lightweightJestGestureHandlerthat routes transitions through the shared arbitration core. - Extracts orchestration/arbitration state machine into
GestureArbitratorand adapts the webGestureHandlerOrchestratorto delegate to it via a web-specific relation policy. - Refines v3 hook gesture typing (
typebecomes a discriminant generic) and addsAnySingleGestureunion for better type narrowing (notably for testID lookup scenarios).
Reviewed changes
Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/react-native-gesture-handler/src/web/tools/GestureHandlerOrchestrator.ts | Replaces inlined orchestration logic with GestureArbitrator + web relation policy; keeps web-specific overlap behavior. |
| packages/react-native-gesture-handler/src/v3/types/GestureTypes.ts | Adds TType generic to make type a proper discriminant for narrowing. |
| packages/react-native-gesture-handler/src/v3/hooks/useGesture.ts | Propagates TType through useGesture so hook-returned gestures preserve discriminant types. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/tap/useTapGesture.ts | Updates useGesture generics so type stays narrowed to Tap. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/tap/TapTypes.ts | Specializes tap gesture types to SingleGestureName.Tap. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/singleGestureUnion.ts | Adds AnySingleGesture discriminated union across v3 single gestures. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/rotation/RotationTypes.ts | Specializes rotation gesture types to SingleGestureName.Rotation. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/pinch/PinchTypes.ts | Specializes pinch gesture types to SingleGestureName.Pinch. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/pan/usePanGesture.ts | Updates useGesture generics so type stays narrowed to Pan. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/pan/PanTypes.ts | Specializes pan gesture types to SingleGestureName.Pan. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/native/NativeTypes.ts | Specializes native gesture types to SingleGestureName.Native. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/manual/ManualTypes.ts | Specializes manual gesture types to SingleGestureName.Manual. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/longPress/useLongPressGesture.ts | Updates useGesture generics so type stays narrowed to LongPress. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/longPress/LongPressTypes.ts | Specializes long-press gesture types to SingleGestureName.LongPress. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/index.ts | Replaces inline single-gesture union export with AnySingleGesture re-export/alias. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/hover/HoverTypes.ts | Specializes hover gesture types to SingleGestureName.Hover. |
| packages/react-native-gesture-handler/src/v3/hooks/gestures/fling/FlingTypes.ts | Specializes fling gesture types to SingleGestureName.Fling. |
| packages/react-native-gesture-handler/src/jestUtils/JestGestureHandler.ts | Adds lightweight arbitrated handler used by fireGesture to emit test events into v3 pipeline. |
| packages/react-native-gesture-handler/src/jestUtils/index.ts | Exposes fireGesture and scenario-related types from jest utils entrypoint. |
| packages/react-native-gesture-handler/src/jestUtils/gestureScenarioTypes.ts | Adds strongly typed scenario shapes keyed off the gesture discriminant type. |
| packages/react-native-gesture-handler/src/jestUtils/gestureScenarios.ts | Implements scenario validation + default payload builders + outcome runners (sync/async). |
| packages/react-native-gesture-handler/src/jestUtils/fireGesture.ts | Implements fireGesture and fireGesture.setup({ advanceTimers }), wiring through GestureArbitrator. |
| packages/react-native-gesture-handler/src/handlers/handlersRegistry.ts | Stores hook gestures as AnySingleGesture so testID lookups can narrow on type. |
| packages/react-native-gesture-handler/src/handlers/gestureArbitration/GestureArbitrator.ts | New platform-neutral arbitration core extracted from web orchestrator logic. |
| packages/react-native-gesture-handler/src/handlers/gestureArbitration/GestureArbitrationTypes.ts | New minimal handler + relation-policy contracts for the arbitration core. |
| packages/react-native-gesture-handler/src/tests/jestUtilsCharacterization.test.tsx | Characterizes current fireGestureHandler behavior to ensure fireGesture can coexist without regressions. |
| packages/react-native-gesture-handler/src/tests/GestureHandlerOrchestrator.test.ts | Adds tests characterizing orchestrator/arbitration behavior using a fake handler (no DOM/pointers). |
| packages/react-native-gesture-handler/src/tests/fireGesture.test.tsx | Adds comprehensive tests for fireGesture scenarios, payload defaults, typing checks, and timer advancement contract. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+96
to
+110
| function validatePayload( | ||
| payload: Record<string, unknown>, | ||
| description: string | ||
| ) { | ||
| for (const field of FORBIDDEN_PAYLOAD_FIELDS) { | ||
| if (field in payload) { | ||
| throw new Error( | ||
| tagMessage( | ||
| `fireGesture scenarios describe interactions in gesture terms — '${field}' found in ${description} is managed internally and cannot be provided. ` + | ||
| `If you need to control exact state transitions, use fireGestureHandler instead.` | ||
| ) | ||
| ); | ||
| } | ||
| } | ||
| } |
| const shouldBeCancelledBy = (otherHandler: IGestureHandler) => { | ||
| return this.shouldHandlerBeCancelledBy(handler, otherHandler); | ||
| }; | ||
| // Private beacuse of Singleton |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a v3-first testing helper,
fireGesture(target, scenario?), that simulates a gesture's JavaScript callback lifecycle in gesture terms. It resolves a test ID or a hook gesture, drives a lightweightJestGestureHandlerthrough the shared arbitration core, and reuses the production v3 event pipeline (so derived fields like changeX are computed for real).Test plan
Added tests using new API