docs

Author: mdjastrzebski

website/docs/13.x/docs/guides/_meta.json

@@ -1 +1 @@
-["how-to-query", "troubleshooting", "faq", "community-resources"]
+["how-to-query", "troubleshooting", "faq", "community-resources", "third-party-integration"]

website/docs/13.x/docs/guides/third-party-integration.mdx

@@ -0,0 +1,46 @@
+# Third-Party Library Integration
+
+React Native Testing Library (RNTL) is designed to simulate core React Native behaviors.
+However, it does not replicate the internal logic of third-party libraries. This guide
+explains how to integrate your library with RNTL.
+
+## Handling Events in Third-Party Libraries
+
+RNTL provides two subsystems for simulating events:
+
+- Fire Event: A lightweight event simulation system that can trigger event handlers defined on both host and composite components.
+- User Event: A more realistic interaction simulation system that can only trigger event handlers defined on host components.
+
+In many third-party libraries, event handling involves native code. In such cases, RNTL cannot
+fully simulate the event flow. To address this, you can use testOnly_onXxx props on host components
+to expose custom events to RNTL's event subsystems. Both subsystems will first attempt to locate the standard onEvent handlers. If these are not available, they will fall back to testOnly_onXxx handlers.
+
+### Example: React Native Gesture Handler
+
+React Native Gesture Handler (RNGH) provides a composite `Pressable` component with `onPress` props.
+These props are part of the library's internal event flow, which involves native modules and
+`EventEmitters`. As a result, they are not directly exposed to the host components rendered by
+`Pressable`, making them inaccessible to RNTL's event subsystems.
+
+To enable RNTL to interact with RNGH's `Pressable` component, the library exposes `testOnly_onPress`
+props on the `NativeButton` host component rendered by `Pressable`. This allows RNTL to simulate
+interactions during testing.
+
+```tsx title="Simplified RNGH Pressable component"
+function Pressable({ onPress, onPressIn, onPressOut, ... }) {
+    // Component logic...
+
+    const isTestEnv = process.env.NODE_ENV === 'test';
+
+    return (
+        <GestureDetector gesture={gesture}>
+            <NativeButton
+                { /* Other props... */ }
+                testOnly_onPress={isTestEnv ? onPress : undefined}
+                testOnly_onPressIn={isTestEnv ? onPressIn : undefined}
+                testOnly_onPressOut={isTestEnv ? onPressOut : undefined}
+        />
+    </GestureDetector>
+    );
+}
+```