@testing-library/react-native 12.1.3 → 12.2.1

package/src/user-event/index.ts

@@ -1,6 +1,9 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { setup } from './setup';
-import { PressOptions } from './press/press';
+import { PressOptions } from './press';
+import { TypeOptions } from './type';
+
+export { UserEventConfig } from './setup';
 
 export const userEvent = {
   setup,
@@ -9,6 +12,7 @@ export const userEvent = {
   press: (element: ReactTestInstance) => setup().press(element),
   longPress: (element: ReactTestInstance, options?: PressOptions) =>
     setup().longPress(element, options),
-  type: (element: ReactTestInstance, text: string) =>
-    setup().type(element, text),
+  type: (element: ReactTestInstance, text: string, options?: TypeOptions) =>
+    setup().type(element, text, options),
+  clear: (element: ReactTestInstance) => setup().clear(element),
 };

package/src/user-event/press/__tests__/longPress.real-timers.test.tsx

@@ -2,13 +2,15 @@ import React from 'react';
 import { Pressable, Text } from 'react-native';
 import { render, screen } from '../../../pure';
 import { userEvent } from '../..';
-import * as WarnAboutRealTimers from '../utils/warnAboutRealTimers';
+import * as WarnAboutRealTimers from '../../utils/warn-about-real-timers';
 
 describe('userEvent.longPress with real timers', () => {
   beforeEach(() => {
     jest.useRealTimers();
     jest.restoreAllMocks();
-    jest.spyOn(WarnAboutRealTimers, 'warnAboutRealTimers').mockImplementation();
+    jest
+      .spyOn(WarnAboutRealTimers, 'warnAboutRealTimersIfNeeded')
+      .mockImplementation();
   });
 
   test('calls onLongPress if the delayLongPress is the default one', async () => {

package/src/user-event/press/__tests__/press.real-timers.test.tsx

@@ -10,13 +10,15 @@ import {
 import { createEventLogger, getEventsName } from '../../../test-utils';
 import { render, screen } from '../../..';
 import { userEvent } from '../..';
-import * as WarnAboutRealTimers from '../utils/warnAboutRealTimers';
+import * as WarnAboutRealTimers from '../../utils/warn-about-real-timers';
 
 describe('userEvent.press with real timers', () => {
   beforeEach(() => {
     jest.useRealTimers();
     jest.restoreAllMocks();
-    jest.spyOn(WarnAboutRealTimers, 'warnAboutRealTimers').mockImplementation();
+    jest
+      .spyOn(WarnAboutRealTimers, 'warnAboutRealTimersIfNeeded')
+      .mockImplementation();
   });
 
   test('calls onPressIn, onPress and onPressOut prop of touchable', async () => {

package/src/user-event/press/__tests__/press.test.tsx

@@ -304,7 +304,7 @@ describe('userEvent.press with fake timers', () => {
     expect(mockOnPress).toHaveBeenCalled();
   });
 
-  test('works on Text', async () => {
+  test('press works on Text', async () => {
     const { events, logEvent } = createEventLogger();
 
     render(
@@ -317,11 +317,29 @@ describe('userEvent.press with fake timers', () => {
         press me
       </Text>
     );
-    await userEvent.press(screen.getByText('press me'));
 
+    await userEvent.press(screen.getByText('press me'));
     expect(getEventsName(events)).toEqual(['pressIn', 'press', 'pressOut']);
   });
 
+  test('longPress works Text', async () => {
+    const { events, logEvent } = createEventLogger();
+
+    render(
+      <Text
+        onPress={logEvent('press')}
+        onPressIn={logEvent('pressIn')}
+        onPressOut={logEvent('pressOut')}
+        onLongPress={logEvent('longPress')}
+      >
+        press me
+      </Text>
+    );
+
+    await userEvent.longPress(screen.getByText('press me'));
+    expect(getEventsName(events)).toEqual(['pressIn', 'longPress', 'pressOut']);
+  });
+
   test('doesnt trigger on disabled Text', async () => {
     const { events, logEvent } = createEventLogger();
 
@@ -361,7 +379,7 @@ describe('userEvent.press with fake timers', () => {
     expect(events).toEqual([]);
   });
 
-  test('works on TetInput', async () => {
+  test('press works on TextInput', async () => {
     const { events, logEvent } = createEventLogger();
 
     render(
@@ -371,12 +389,27 @@ describe('userEvent.press with fake timers', () => {
         onPressOut={logEvent('pressOut')}
       />
     );
+
     await userEvent.press(screen.getByPlaceholderText('email'));
+    expect(getEventsName(events)).toEqual(['pressIn', 'pressOut']);
+  });
+
+  test('longPress works on TextInput', async () => {
+    const { events, logEvent } = createEventLogger();
+
+    render(
+      <TextInput
+        placeholder="email"
+        onPressIn={logEvent('pressIn')}
+        onPressOut={logEvent('pressOut')}
+      />
+    );
 
+    await userEvent.longPress(screen.getByPlaceholderText('email'));
     expect(getEventsName(events)).toEqual(['pressIn', 'pressOut']);
   });
 
-  test('does not call onPressIn and onPressOut on non editable TetInput', async () => {
+  test('does not call onPressIn and onPressOut on non editable TextInput', async () => {
     const { events, logEvent } = createEventLogger();
 
     render(
@@ -387,11 +420,12 @@ describe('userEvent.press with fake timers', () => {
         onPressOut={logEvent('pressOut')}
       />
     );
+
     await userEvent.press(screen.getByPlaceholderText('email'));
     expect(events).toEqual([]);
   });
 
-  test('does not call onPressIn and onPressOut on TetInput with pointer events disabled', async () => {
+  test('does not call onPressIn and onPressOut on TextInput with pointer events disabled', async () => {
     const { events, logEvent } = createEventLogger();
 
     render(
@@ -402,6 +436,7 @@ describe('userEvent.press with fake timers', () => {
         onPressOut={logEvent('pressOut')}
       />
     );
+
     await userEvent.press(screen.getByPlaceholderText('email'));
     expect(events).toEqual([]);
   });

package/src/user-event/press/index.ts

@@ -1 +1 @@
-export { press, longPress } from './press';
+export { PressOptions, press, longPress } from './press';

package/src/user-event/press/press.ts

@@ -1,50 +1,65 @@
 import { ReactTestInstance } from 'react-test-renderer';
-import { EventBuilder } from '../event-builder';
-import { UserEventInstance } from '../setup';
-import { wait } from '../utils';
 import act from '../../act';
 import { getHostParent } from '../../helpers/component-tree';
-import { filterNodeByType } from '../../helpers/filterNodeByType';
 import { isPointerEventEnabled } from '../../helpers/pointer-events';
-import { getHostComponentNames } from '../../helpers/host-component-names';
-import { jestFakeTimersAreEnabled } from '../../helpers/timers';
+import { isHostText } from '../../helpers/host-component-names';
+import { EventBuilder } from '../event-builder';
+import { UserEventConfig, UserEventInstance } from '../setup';
+import {
+  dispatchEvent,
+  isEditableTextInput,
+  wait,
+  warnAboutRealTimersIfNeeded,
+} from '../utils';
 import { DEFAULT_MIN_PRESS_DURATION } from './constants';
-import { warnAboutRealTimers } from './utils/warnAboutRealTimers';
 
-export type PressOptions = {
-  duration: number;
-};
+export interface PressOptions {
+  duration?: number;
+}
 
 export async function press(
   this: UserEventInstance,
   element: ReactTestInstance
 ): Promise<void> {
-  await basePress(this.config, element);
+  await basePress(this.config, element, {
+    type: 'press',
+    duration: 0,
+  });
 }
 
 export async function longPress(
   this: UserEventInstance,
   element: ReactTestInstance,
-  options: PressOptions = { duration: 500 }
+  options?: PressOptions
 ): Promise<void> {
-  await basePress(this.config, element, options);
+  await basePress(this.config, element, {
+    type: 'longPress',
+    duration: options?.duration ?? 500,
+  });
+}
+
+interface BasePressOptions {
+  type: 'press' | 'longPress';
+  duration: number;
 }
 
 const basePress = async (
-  config: UserEventInstance['config'],
+  config: UserEventConfig,
   element: ReactTestInstance,
-  options: PressOptions = { duration: 0 }
+  options: BasePressOptions
 ): Promise<void> => {
-  // Text and TextInput components are mocked in React Native preset so the mock
-  // doesn't implement the pressability class
-  // Thus we need to call the props directly on the host component
-  if (isEnabledHostText(element) || isEnabledTextInput(element)) {
-    await triggerMockPressEvent(config, element, options);
+  if (isPressableText(element)) {
+    await emitTextPressEvents(config, element, options);
+    return;
+  }
+
+  if (isEditableTextInput(element) && isPointerEventEnabled(element)) {
+    await emitTextInputPressEvents(config, element, options);
     return;
   }
 
   if (isEnabledTouchResponder(element)) {
-    await triggerPressEvent(config, element, options);
+    await emitPressablePressEvents(config, element, options);
     return;
   }
 
@@ -56,31 +71,33 @@ const basePress = async (
   await basePress(config, hostParentElement, options);
 };
 
-const triggerPressEvent = async (
-  config: UserEventInstance['config'],
+const emitPressablePressEvents = async (
+  config: UserEventConfig,
   element: ReactTestInstance,
-  options: PressOptions = { duration: 0 }
+  options: BasePressOptions
 ) => {
-  const areFakeTimersEnabled = jestFakeTimersAreEnabled();
-  if (!areFakeTimersEnabled) {
-    warnAboutRealTimers();
-  }
+  warnAboutRealTimersIfNeeded();
 
   await wait(config);
 
   await act(async () => {
-    element.props.onResponderGrant({
-      ...EventBuilder.Common.touch(),
-      dispatchConfig: { registrationName: 'onResponderGrant' },
-    });
+    dispatchEvent(
+      element,
+      'responderGrant',
+      EventBuilder.Common.responderGrant()
+    );
 
     await wait(config, options.duration);
 
-    element.props.onResponderRelease({
-      ...EventBuilder.Common.touch(),
-      dispatchConfig: { registrationName: 'onResponderRelease' },
-    });
+    dispatchEvent(
+      element,
+      'responderRelease',
+      EventBuilder.Common.responderRelease()
+    );
 
+    // React Native will wait for minimal delay of DEFAULT_MIN_PRESS_DURATION
+    // before emitting the `pressOut` event. We need to wait here, so that
+    // `press()` function does not return before that.
     if (DEFAULT_MIN_PRESS_DURATION - options.duration > 0) {
       await wait(config, DEFAULT_MIN_PRESS_DURATION - options.duration);
     }
@@ -94,41 +111,53 @@ const isEnabledTouchResponder = (element: ReactTestInstance) => {
   );
 };
 
-const isEnabledHostText = (element: ReactTestInstance) => {
-  return (
-    filterNodeByType(element, getHostComponentNames().text) &&
-    isPointerEventEnabled(element) &&
-    !element.props.disabled &&
-    element.props.onPress
+const isPressableText = (element: ReactTestInstance) => {
+  const hasPressEventHandler = Boolean(
+    element.props.onPress ||
+      element.props.onLongPress ||
+      element.props.onPressIn ||
+      element.props.onPressOut
   );
-};
 
-const isEnabledTextInput = (element: ReactTestInstance) => {
   return (
-    filterNodeByType(element, getHostComponentNames().textInput) &&
+    isHostText(element) &&
     isPointerEventEnabled(element) &&
-    element.props.editable !== false
+    !element.props.disabled &&
+    hasPressEventHandler
   );
 };
 
-const triggerMockPressEvent = async (
-  config: UserEventInstance['config'],
+/**
+ * Dispatches a press event sequence for Text.
+ */
+async function emitTextPressEvents(
+  config: UserEventConfig,
   element: ReactTestInstance,
-  options: PressOptions = { duration: 0 }
-) => {
-  const { onPressIn, onPress, onPressOut } = element.props;
+  options: BasePressOptions
+) {
   await wait(config);
-  if (onPressIn) {
-    onPressIn(EventBuilder.Common.touch());
-  }
-  if (onPress) {
-    onPress(EventBuilder.Common.touch());
-  }
+  dispatchEvent(element, 'pressIn', EventBuilder.Common.touch());
+
+  // Emit either `press` or `longPress`.
+  dispatchEvent(element, options.type, EventBuilder.Common.touch());
+
   await wait(config, options.duration);
-  if (onPressOut) {
-    if (DEFAULT_MIN_PRESS_DURATION - options.duration > 0) {
-      await wait(config, DEFAULT_MIN_PRESS_DURATION - options.duration);
-    }
-    onPressOut(EventBuilder.Common.touch());
-  }
-};
+  dispatchEvent(element, 'pressOut', EventBuilder.Common.touch());
+}
+
+/**
+ * Dispatches a press event sequence for TextInput.
+ */
+async function emitTextInputPressEvents(
+  config: UserEventConfig,
+  element: ReactTestInstance,
+  options: BasePressOptions
+) {
+  await wait(config);
+  dispatchEvent(element, 'pressIn', EventBuilder.Common.touch());
+
+  // Note: TextInput does not have `onPress`/`onLongPress` props.
+
+  await wait(config, options.duration);
+  dispatchEvent(element, 'pressOut', EventBuilder.Common.touch());
+}

package/src/user-event/setup/setup.ts

@@ -1,8 +1,8 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { jestFakeTimersAreEnabled } from '../../helpers/timers';
-import { press, longPress } from '../press';
-import { type } from '../type';
-import { PressOptions } from '../press/press';
+import { PressOptions, press, longPress } from '../press';
+import { TypeOptions, type } from '../type';
+import { clear } from '../clear';
 
 export interface UserEventSetupOptions {
   /**
@@ -46,7 +46,7 @@ const defaultOptions: Required<UserEventSetupOptions> = {
  * Creates a new instance of user event instance with the given options.
  *
  * @param options
- * @returns
+ * @returns UserEvent instance
  */
 export function setup(options?: UserEventSetupOptions) {
   const config = createConfig(options);
@@ -54,6 +54,12 @@ export function setup(options?: UserEventSetupOptions) {
   return instance;
 }
 
+/**
+ * Options affecting all user event interactions.
+ *
+ * @param delay between some subsequent inputs like typing a series of characters
+ * @param advanceTimers function to be called to advance fake timers
+ */
 export interface UserEventConfig {
   delay: number;
   advanceTimers: (delay: number) => Promise<void> | void;
@@ -66,14 +72,56 @@ function createConfig(options?: UserEventSetupOptions): UserEventConfig {
   };
 }
 
+/**
+ * UserEvent instance used to invoke user interaction functions.
+ */
 export interface UserEventInstance {
   config: UserEventConfig;
+
   press: (element: ReactTestInstance) => Promise<void>;
   longPress: (
     element: ReactTestInstance,
     options?: PressOptions
   ) => Promise<void>;
-  type: (element: ReactTestInstance, text: string) => Promise<void>;
+
+  /**
+   * Simulate user pressing on a given `TextInput` element and typing given text.
+   *
+   * This method will trigger the events for each character of the text:
+   * `keyPress`, `change`, `changeText`, `endEditing`, etc.
+   *
+   * It will also trigger events connected with entering and leaving the text
+   * input.
+   *
+   * The exact events sent depend on the props of the TextInput (`editable`,
+   * `multiline`, value, defaultValue, etc) and passed options.
+   *
+   * @param element TextInput element to type on
+   * @param text Text to type
+   * @param options Options affecting typing behavior:
+   *  - `skipPress` - if true, `pressIn` and `pressOut` events will not be
+   *   triggered.
+   * - `submitEditing` - if true, `submitEditing` event will be triggered after
+   * typing the text.
+   */
+  type: (
+    element: ReactTestInstance,
+    text: string,
+    options?: TypeOptions
+  ) => Promise<void>;
+
+  /**
+   * Simulate user clearing the text of a given `TextInput` element.
+   *
+   * This method will simulate:
+   * 1. entering TextInput
+   * 2. selecting all text
+   * 3. pressing backspace to delete all text
+   * 4. leaving TextInput
+   *
+   * @param element TextInput element to clear
+   */
+  clear: (element: ReactTestInstance) => Promise<void>;
 }
 
 function createInstance(config: UserEventConfig): UserEventInstance {
@@ -86,6 +134,7 @@ function createInstance(config: UserEventConfig): UserEventInstance {
     press: press.bind(instance),
     longPress: longPress.bind(instance),
     type: type.bind(instance),
+    clear: clear.bind(instance),
   };
 
   Object.assign(instance, api);