[m-bert]

Description

GestureDetector throws in development when it is not rendered inside GestureHandlerRootView. This also happens under Jest, where the check is usually just noise, and the testing guide did not mention it.

This PR:

• adds react-native-gesture-handler/jest-setup/disableRootViewCheck.js, an opt-in setup file that mocks useEnsureGestureHandlerRootView for both src and lib/module,
• moves the existing Jest mocks to jest-setup/index.js and keeps jestSetup.js as a one-line re-export, so existing configs keep working,
• extends the error message in test environments with a hint on how to fix or disable the check, linking to the new docs section,
• documents it in the testing guide.

The check stays enabled by default, so tests that forget the root view still fail the same way they would on a device.

Fixes #4657

Test plan

Packed the library with yarn pack and installed it in a Jest app with @testing-library/react-native, then rendered a GestureDetector without GestureHandlerRootView:

• jestSetup.js only: test fails with the new error message.
• jestSetup.js + jest-setup/disableRootViewCheck.js: test passes.
• jest-setup + jest-setup/disableRootViewCheck.js: test passes.
• jestSetup.js shim keeps working.

Errors.test.tsx passes, the existing assertions still match since the message starts with the original text.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 530b915f-a839-49f4-89e1-487477bcefe3

Commits

Reviewing files that changed from the base of the PR and between 589ff6f and 1902fea.

Files selected for processing: 1

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

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.

Summary

Summary by CodeRabbit

• Bug Fixes
  • Improved Jest setup so gesture-handler components are mocked consistently across package builds.
  • Added Jest-specific guidance when a gesture detector is rendered without GestureHandlerRootView, with options to wrap the rendered tree or disable the check.
• Documentation
  • Updated testing instructions with the recommended setup path and details on handling the root-view requirement in Jest.

The root-view check now uses a Jest-specific error message. The Jest setup centralizes module mocks and includes an optional setup file that disables the check. The testing guide describes how to wrap rendered trees or configure the optional setup file.

Changes: Jest root-view check support

Layer / File(s)	Summary
Jest-specific root-view error packages/react-native-gesture-handler/src/v3/detectors/useEnsureGestureHandlerRootView.ts	The root-view check uses a Jest-specific error message in test environments. Other environments retain the existing message.
Jest mocks and setup instructions packages/react-native-gesture-handler/jest-setup/*, packages/react-native-gesture-handler/jestSetup.js, packages/react-native-gesture-handler/package.json, packages/docs-gesture-handler/docs/guides/testing.mdx	The Jest setup centralizes mocks for source and compiled modules. An optional setup file mocks the root-view check with a no-op hook. The package includes the setup directory, and the guide explains how to use it or wrap rendered trees in GestureHandlerRootView.

Possibly related issues

• software-mansion/react-native-gesture-handler#4657: The change adds an optional Jest setup that mocks the hook identified in this issue. It also documents wrapping rendered trees in GestureHandlerRootView.

Possibly related PRs

• software-mansion/react-native-gesture-handler#4615: This PR adds the UI runtime mock that the Jest setup reorganizes alongside other mocks.

Suggested reviewers: j-piasecki, coado

Severity of issue fixed: Medium

Merge Risk: Low · up to 1902f

The change is largely mergeable, but the documented Jest configuration should remove the invalid placeholder before users copy it.

Pre-merge checks: 3

Check name	Status	Explanation
Title check		The title "[Jest] Add opt-out for the GestureHandlerRootView check" matches the main change. The PR adds an opt-in Jest setup file, jest-setup/disableRootViewCheck.js, that mocks useEnsureGestureHan…
Linked Issues check		The PR satisfies the coding requirements in [#4657]. The testing guide documents wrapping rendered trees in GestureHandlerRootView and provides the opt-in jest-setup/disableRootViewCheck.js setup.…
Out of Scope Changes check		The changes stay within [#4657]. The setup files, package inclusion, compatibility re-export, test-environment error hint, and testing-guide update all address the Jest root-view failure or its docume…

Full details: Title check

Explanation

The title "[Jest] Add opt-out for the GestureHandlerRootView check" matches the main change. The PR adds an opt-in Jest setup file, jest-setup/disableRootViewCheck.js, that mocks useEnsureGestureHandlerRootView. The title names the Jest scope and the opt-out behavior. It does not mention the moved mocks in jest-setup/index.js or the documentation update, which is expected for a title.

Full details: Linked Issues check

Explanation

The PR satisfies the coding requirements in [#4657]. The testing guide documents wrapping rendered trees in GestureHandlerRootView and provides the opt-in jest-setup/disableRootViewCheck.js setup. The setup mocks useEnsureGestureHandlerRootView for src and lib/module. jestSetup.js remains compatible through its re-export. The root-view check remains enabled by default.

Full details: Out of Scope Changes check

Explanation

The changes stay within [#4657]. The setup files, package inclusion, compatibility re-export, test-environment error hint, and testing-guide update all address the Jest root-view failure or its documented workaround. No unrelated change is established by the reviewed summary.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

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

Parsing error: ESLint was configured to run on <tsconfigRootDir>/packages/docs-gesture-handler/docs/guides/testing.mdx using parserOptions.project: /tsconfig.json
The extension for the file (.mdx) is non-standard. You should add parserOptions.extraFileExtensions to your config.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[Copilot]

🟢 Approval recommended

No active review issues block approval of the opt-in Jest root-view-check setup change.

No open issues 🎉

What changed in this PR

Adds an opt-in Jest setup file to disable the v3 GestureDetector root-view check, addressing #4657 while keeping the check enabled by default.

Changes:

• Adds root-view-check mocks for both source and compiled module imports.
• Moves existing Jest mocks into jest-setup/index.js, preserving compatibility through the jestSetup.js shim.
• Adds Jest-specific error guidance and documents how to disable the check.

File	Description
packages/​react-native-gesture-handler/​src/​v3/​detectors/​useEnsureGestureHandlerRootView.ts	Adds test-specific guidance to the root-view error.
packages/​react-native-gesture-handler/​package.json	Includes the new setup directory in the published package.
packages/​react-native-gesture-handler/​jestSetup.js	Preserves the existing entry point through a compatibility shim.
packages/​react-native-gesture-handler/​jest-setup/​index.js	Houses existing Jest mocks with adjusted relative paths.
packages/​react-native-gesture-handler/​jest-setup/​disableRootViewCheck.js	Provides opt-in mocks that disable the root-view check.
packages/​docs-gesture-handler/​docs/​guides/​testing.mdx	Documents root-view wrapping and the Jest opt-out.

_{Review effort: Balanced}

[coderabbitai]

• Fix comments: Fix CodeRabbit comments on this PR

[coderabbitai]

• Fix comments: Fix CodeRabbit comments on this PR