refactor: event code organization (#1939)

Author: mdjastrzebski

contributing/event-dispatch.md

@@ -2,9 +2,23 @@
 
 RNTL has two ways to trigger events. Neither goes through React Native's native event system. Both find `on*` props in the rendered tree and call them inside `act()`.
 
+Both are built on the shared event subsystem in `src/events/`, which also holds `fireEvent` itself:
+
+| File                                        | Contents                                                                                |
+| ------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `fire-event.ts`                             | Public `fireEvent` API                                                                  |
+| `handler.ts`                                | Finding the `on*` handler for an event name in props                                    |
+| `propagation.ts`                            | Bubbling vs direct events, walking up host and composite elements                       |
+| `is-enabled.ts`                             | Whether a device would deliver the event: `pointerEvents`, `editable`, touch responders |
+| `dispatch.ts`                               | `dispatchEvent()`: calls the target's own handler in `act()`, used by `userEvent`       |
+| `builders/`                                 | Event payloads, matching what React Native sends on a device                            |
+| `native-state.ts`, `update-native-state.ts` | [Native state](native-state.md) and how `fireEvent` updates it                          |
+
+`src/user-event/` is a separate module on top of `src/events/` and imports it only through `src/events/index.ts`.
+
 ## `fireEvent`
 
-`src/fire-event.ts` calls a single handler for a single event. The work is in finding the right handler:
+`src/events/fire-event.ts` is the public API. It calls a single handler for a single event, found with `findEventHandler()` from `src/events/propagation.ts`. The work is in finding the right handler:
 
 - It starts at the target and moves up the tree until it finds a handler. It also checks props of composite components, not only host elements.
 - Direct events (see [Native event propagation](native-events.md)) only check the target.
@@ -20,5 +34,5 @@ Each step uses `dispatchEvent()`, which only calls the target's own handler. It
 
 - To change which handler gets a single event, change `fireEvent`. To make an interaction more realistic, change the `userEvent` action.
 - Keep `dispatchEvent()` simple.
-- Put rules that both need, like `pointerEvents` or `editable`, in shared helpers in `src/helpers/`.
+- Put event rules that both need, like the `pointerEvents` and `editable` checks, in `src/events/`. They may build on general helpers from `src/helpers/` (for example `isEditableTextInput`). Code used only by `userEvent`, like delays and scroll steps, stays in `src/user-event/`.
 - Event sequences should match a real device. Check on a device before changing one, and keep the code comments explaining the observed behavior.

contributing/native-events.md

@@ -2,7 +2,7 @@
 
 In React Native, some events **bubble** up to parent elements and others are **direct**, meaning only the element that emitted them receives them. `fireEvent` should behave the same way.
 
-Today, `fireEvent` treats every event as bubbling except `layout`. The list of direct events lives in `isDirectEvent()` in `src/fire-event.ts`.
+Today, `fireEvent` treats every event as bubbling except `layout`. The list of direct events lives in `isDirectEvent()` in `src/events/propagation.ts`.
 
 ## Which events are which
 

contributing/native-state.md

@@ -1,6 +1,6 @@
 # Native State
 
-On a device, some component state lives in native views, not in React. Jest has no native views, so RNTL keeps this state itself in `src/native-state.ts`.
+On a device, some component state lives in native views, not in React. Jest has no native views, so RNTL keeps this state itself in `src/events/native-state.ts`.
 
 ## What is stored
 
@@ -10,7 +10,7 @@ On a device, some component state lives in native views, not in React. Jest has
 
 ## Key points
 
-- **Writes.** `fireEvent` and `userEvent` update native state when they simulate a change that a native view would make.
+- **Writes.** `fireEvent` and `userEvent` update native state when they simulate a change that a native view would make. `fireEvent` does it through `updateNativeStateFromEvent()` in `src/events/update-native-state.ts`. Each `userEvent` action writes it directly.
 - **Reads.** Helpers read native state, like `getTextInputValue()` in `src/helpers/text-input.ts`. Queries and matchers use those helpers instead of reading native state directly.
 - **Props win.** A controlled prop (like `value`) always takes precedence over native state.
 - **No reset.** State is stored in `WeakMap`s keyed by host instance. It disappears when the instance is unmounted, so `cleanup()` doesn't need to clear it.

src/events/__tests__/dispatch.test.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import { Text } from 'react-native';
+
+import { render, screen } from '../..';
+import { buildTouchEvent } from '../builders/common';
+import { dispatchEvent } from '../dispatch';
+
+const TOUCH_EVENT = buildTouchEvent();
+
+test('dispatchEvent calls the target handler', async () => {
+  const onPress = jest.fn();
+  await render(<Text testID="text" onPress={onPress} />);
+
+  await dispatchEvent(screen.getByTestId('text'), 'press', TOUCH_EVENT);
+  expect(onPress).toHaveBeenCalledTimes(1);
+});
+
+test('dispatchEvent does not call the parent host component handler', async () => {
+  const onPressParent = jest.fn();
+  await render(
+    <Text onPress={onPressParent}>
+      <Text testID="text" />
+    </Text>,
+  );
+
+  await dispatchEvent(screen.getByTestId('text'), 'press', TOUCH_EVENT);
+  expect(onPressParent).not.toHaveBeenCalled();
+});
+
+test('dispatchEvent does not throw when no handler is found', async () => {
+  await render(
+    <Text>
+      <Text testID="text" />
+    </Text>,
+  );
+
+  await expect(
+    dispatchEvent(screen.getByTestId('text'), 'press', TOUCH_EVENT),
+  ).resolves.not.toThrow();
+});

src/__tests__/fire-event.test.tsx src/events/__tests__/fire-event.test.tsxsrc/__tests__/fire-event.test.tsx renamed to src/events/__tests__/fire-event.test.tsx

@@ -13,8 +13,8 @@ import {
   View,
 } from 'react-native';
 
-import { fireEvent, render, screen } from '..';
-import { _console } from '../helpers/logger';
+import { fireEvent, render, screen } from '../..';
+import { _console } from '../../helpers/logger';
 import { nativeState } from '../native-state';
 
 const layoutEvent = { nativeEvent: { layout: { width: 100, height: 100 } } };
@@ -37,6 +37,20 @@ test('fireEvent accepts event name with or without "on" prefix', async () => {
   expect(onPress).toHaveBeenCalledTimes(2);
 });
 
+test('fireEvent with "on" prefixed name does not call unprefixed handler props', async () => {
+  const press = jest.fn();
+  const testOnlyPress = jest.fn();
+  // @ts-expect-error Intentionally passing such props
+  await render(<View testID="view" press={press} testOnly_press={testOnlyPress} />);
+
+  await fireEvent(screen.getByTestId('view'), 'onPress');
+  expect(press).not.toHaveBeenCalled();
+  expect(testOnlyPress).not.toHaveBeenCalled();
+
+  await fireEvent(screen.getByTestId('view'), 'press');
+  expect(press).toHaveBeenCalledTimes(1);
+});
+
 test('fireEvent passes event data to handler', async () => {
   const onPress = jest.fn();
   await render(<Pressable testID="btn" onPress={onPress} />);
@@ -194,6 +208,15 @@ describe('fireEvent.changeText', () => {
     expect(nativeState.valueForInstance.get(input)).toBe('new text');
   });
 
+  test('updates native state when fired with `on*` prefixed name', async () => {
+    const onChangeText = jest.fn();
+    await render(<TextInput testID="input" onChangeText={onChangeText} />);
+    const input = screen.getByTestId('input');
+    await fireEvent(input, 'onChangeText', 'new text');
+    expect(onChangeText).toHaveBeenCalledWith('new text');
+    expect(nativeState.valueForInstance.get(input)).toBe('new text');
+  });
+
   test('does not fire on non-editable TextInput', async () => {
     const onChangeText = jest.fn();
     await render(<TextInput testID="input" editable={false} onChangeText={onChangeText} />);
@@ -324,6 +347,18 @@ describe('fireEvent.scroll', () => {
     });
   });
 
+  test('updates native state when fired with `on*` prefixed name', async () => {
+    const onScroll = jest.fn();
+    await render(<ScrollView testID="scroll" onScroll={onScroll} />);
+    const scrollView = screen.getByTestId('scroll');
+    await fireEvent(scrollView, 'onScroll', verticalScrollEvent);
+    expect(onScroll).toHaveBeenCalledWith(verticalScrollEvent);
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toEqual({
+      x: 0,
+      y: 200,
+    });
+  });
+
   test.each([
     ['onScroll', 'scroll'],
     ['onScrollBeginDrag', 'scrollBeginDrag'],

src/__tests__/event-handler.test.tsx src/events/__tests__/handler.test.tsxsrc/__tests__/event-handler.test.tsx renamed to src/events/__tests__/handler.test.tsx

@@ -1,10 +1,10 @@
 import * as React from 'react';
 import { Text, View } from 'react-native';
 
-import { render, screen } from '..';
-import { getEventHandlerFromProps } from '../event-handler';
+import { render, screen } from '../..';
+import { getEventHandlerFromProps, normalizeEventName } from '../handler';
 
-test('getEventHandler strict mode', async () => {
+test('getEventHandlerFromProps strict mode', async () => {
   const onPress = jest.fn();
   const testOnlyOnPress = jest.fn();
 
@@ -31,15 +31,15 @@ test('getEventHandler strict mode', async () => {
   expect(getEventHandlerFromProps(both.props, 'onPress')).toBe(onPress);
 });
 
-test('getEventHandler does not treat event names starting with "on" as prefixed', async () => {
+test('getEventHandlerFromProps does not treat event names starting with "on" as prefixed', async () => {
   const onOnline = jest.fn();
   // @ts-expect-error Intentionally passing such props
   await render(<View testID="view" onOnline={onOnline} />);
 
   expect(getEventHandlerFromProps(screen.getByTestId('view').props, 'online')).toBe(onOnline);
 });
 
-test('getEventHandler loose mode', async () => {
+test('getEventHandlerFromProps loose mode', async () => {
   const onPress = jest.fn();
   const testOnlyOnPress = jest.fn();
 
@@ -67,3 +67,12 @@ test('getEventHandler loose mode', async () => {
   );
   expect(getEventHandlerFromProps(both.props, 'onPress', { loose: true })).toBe(onPress);
 });
+
+test('normalizeEventName strips the `on*` prefix', () => {
+  expect(normalizeEventName('onLayout')).toBe('layout');
+  expect(normalizeEventName('onChangeText')).toBe('changeText');
+  expect(normalizeEventName('layout')).toBe('layout');
+  expect(normalizeEventName('changeText')).toBe('changeText');
+  expect(normalizeEventName('once')).toBe('once');
+  expect(normalizeEventName('on')).toBe('on');
+});

src/event-builder/__tests__/base.test.ts …c/events/builders/__tests__/base.test.tssrc/event-builder/__tests__/base.test.ts renamed to src/events/builders/__tests__/base.test.ts src/event-builder/__tests__/base.test.ts renamed to src/events/builders/__tests__/base.test.ts

@@ -13,4 +13,5 @@ test('re-exports all event builders', () => {
   expect(eventBuilder.buildEndEditingEvent).toBeInstanceOf(Function);
   expect(eventBuilder.buildTextSelectionChangeEvent).toBeInstanceOf(Function);
   expect(eventBuilder.buildContentSizeChangeEvent).toBeInstanceOf(Function);
+  expect(eventBuilder.mergeEventProps).toBeInstanceOf(Function);
 });

…c/event-builder/__tests__/common.test.ts …events/builders/__tests__/common.test.tssrc/event-builder/__tests__/common.test.ts renamed to src/events/builders/__tests__/common.test.ts src/event-builder/__tests__/common.test.ts renamed to src/events/builders/__tests__/common.test.ts

@@ -0,0 +1,35 @@
+import { buildTouchEvent } from '../common';
+import { mergeEventProps } from '../merge';
+
+test('returns the same event when no props are passed', () => {
+  const event = buildTouchEvent();
+  const nativeEvent = { ...event.nativeEvent };
+
+  expect(mergeEventProps(event)).toBe(event);
+  expect(event.nativeEvent).toEqual(nativeEvent);
+});
+
+test('deep merges nested objects and keeps other default fields', () => {
+  const event = mergeEventProps(buildTouchEvent(), { nativeEvent: { pageX: 10, pageY: 20 } });
+
+  expect(event.nativeEvent.pageX).toBe(10);
+  expect(event.nativeEvent.pageY).toBe(20);
+  expect(event.nativeEvent.locationX).toBe(0);
+  expect(typeof event.preventDefault).toBe('function');
+});
+
+test('replaces arrays and primitive values instead of merging them', () => {
+  const event = mergeEventProps(buildTouchEvent(), {
+    nativeEvent: { touches: [{ identifier: 1 }] },
+    timeStamp: 42,
+  });
+
+  expect(event.nativeEvent.touches).toEqual([{ identifier: 1 }]);
+  expect(event.timeStamp).toBe(42);
+});
+
+test('adds props that the event does not have', () => {
+  const event = mergeEventProps(buildTouchEvent(), { custom: { value: 1 } });
+
+  expect(event).toMatchObject({ custom: { value: 1 } });
+});