feat: userEvent type()

chore: restore tests

chore: more tests

chore: improve coverage

chore: moar tests

docs: improve the docs

chore: fix lint

refactor: code review changes

chore: fix lint

chore: tweak return type

refactor: flush microtasks after event

refactor: re-organize waits

refactor: improve dispatch event functions

refactor: remove flushMicroTasks calls

Author: mdjastrzebski

experiments-app/src/screens/TextInputEvents.tsx

@@ -7,7 +7,12 @@ const handlePressOut = buildEventLogger('pressOut');
 const handleFocus = buildEventLogger('focus');
 const handleBlur = buildEventLogger('blur');
 const handleChange = buildEventLogger('change');
+const handleEndEditing = buildEventLogger('endEditing');
 const handleSubmitEditing = buildEventLogger('submitEditing');
+const handleKeyPress = buildEventLogger('keyPress');
+const handleTextInput = buildEventLogger('textInput');
+const handleSelectionChange = buildEventLogger('selectionChange');
+const handleContentSizeChange = buildEventLogger('contentSizeChange');
 
 export function TextInputEvents() {
   const [value, setValue] = React.useState('');
@@ -29,7 +34,12 @@ export function TextInputEvents() {
         onFocus={handleFocus}
         onBlur={handleBlur}
         onChange={handleChange}
+        onEndEditing={handleEndEditing}
         onSubmitEditing={handleSubmitEditing}
+        onKeyPress={handleKeyPress}
+        onTextInput={handleTextInput}
+        onSelectionChange={handleSelectionChange}
+        onContentSizeChange={handleContentSizeChange}
       />
     </SafeAreaView>
   );

src/__tests__/act.test.tsx

@@ -50,3 +50,7 @@ test('should be able to await act', async () => {
   const result = await act(async () => {});
   expect(result).toBe(undefined);
 });
+
+test('should be able to await act when promise rejects', async () => {
+  await expect(act(async () => Promise.reject('error'))).rejects.toBe('error');
+});

src/fireEvent.ts

@@ -1,15 +1,11 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import act from './act';
-import { isHostElement } from './helpers/component-tree';
-import { getHostComponentNames } from './helpers/host-component-names';
 import { isPointerEventEnabled } from './helpers/pointer-events';
+import { isHostElement } from './helpers/component-tree';
+import { isHostTextInput } from './helpers/host-component-names';
 
 type EventHandler = (...args: unknown[]) => unknown;
 
-const isHostTextInput = (element?: ReactTestInstance) => {
-  return element?.type === getHostComponentNames().textInput;
-};
-
 export function isTouchResponder(element: ReactTestInstance) {
   if (!isHostElement(element)) {
     return false;

src/helpers/accessiblity.ts

@@ -4,8 +4,8 @@ import {
   StyleSheet,
 } from 'react-native';
 import { ReactTestInstance } from 'react-test-renderer';
-import { getConfig } from '../config';
 import { getHostSiblings } from './component-tree';
+import { getHostComponentNames } from './host-component-names';
 
 type IsInaccessibleOptions = {
   cache?: WeakMap<ReactTestInstance, boolean>;
@@ -99,8 +99,7 @@ export function isAccessibilityElement(
     return element.props.accessible;
   }
 
-  const hostComponentNames = getConfig().hostComponentNames;
-
+  const hostComponentNames = getHostComponentNames();
   return (
     element?.type === hostComponentNames?.text ||
     element?.type === hostComponentNames?.textInput ||

src/helpers/deprecation.ts

@@ -37,7 +37,7 @@ function deprecateQuery<QueryFn extends (...args: any) => any>(
 
 const warned: { [functionName: string]: boolean } = {};
 
-// istambul ignore next: Occasionally used
+/* istanbul ignore next: occasionally used */
 export function printDeprecationWarning(functionName: string) {
   if (warned[functionName]) {
     return;

src/helpers/host-component-names.tsx

@@ -65,3 +65,7 @@ function getByTestId(instance: ReactTestInstance, testID: string) {
 
   return nodes[0];
 }
+
+export function isHostTextInput(element?: ReactTestInstance) {
+  return element?.type === getHostComponentNames().textInput;
+}

src/user-event/event-builder/index.ts

@@ -1,5 +1,7 @@
 import { CommonEventBuilder } from './common';
+import { TextInputEventBuilder } from './text-input';
 
 export const EventBuilder = {
   Common: CommonEventBuilder,
+  TextInput: TextInputEventBuilder,
 };

src/user-event/event-builder/text-input.ts

@@ -0,0 +1,86 @@
+import { ContentSize } from '../utils/content-size';
+import { TextRange } from '../utils/text-range';
+
+export const TextInputEventBuilder = {
+  /**
+   * Experimental values:
+   * - iOS: `{"eventCount": 4, "target": 75, "text": "Test"}`
+   * - Android: `{"eventCount": 6, "target": 53, "text": "Tes"}`
+   */
+  change: (text: string) => {
+    return {
+      nativeEvent: { text, target: 0, eventCount: 0 },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"eventCount": 3, "key": "a", "target": 75}`
+   * - Android: `{"key": "a"}`
+   */
+  keyPress: (key: string) => {
+    return {
+      nativeEvent: { key },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"eventCount": 4, "target": 75, "text": "Test"}`
+   * - Android: `{"target": 53, "text": "Test"}`
+   */
+  submitEditing: (text: string) => {
+    return {
+      nativeEvent: { text, target: 0 },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"eventCount": 4, "target": 75, "text": "Test"}`
+   * - Android: `{"target": 53, "text": "Test"}`
+   */
+  endEditing: (text: string) => {
+    return {
+      nativeEvent: { text, target: 0 },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"selection": {"end": 4, "start": 4}, "target": 75}`
+   * - Android: `{"selection": {"end": 4, "start": 4}}`
+   */
+  selectionChange: ({ start, end }: TextRange) => {
+    return {
+      nativeEvent: { selection: { start, end } },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"eventCount": 2, "previousText": "Te", "range": {"end": 2, "start": 2}, "target": 75, "text": "s"}`
+   * - Android: `{"previousText": "Te", "range": {"end": 2, "start": 0}, "target": 53, "text": "Tes"}`
+   */
+  textInput: (text: string, previousText: string) => {
+    return {
+      nativeEvent: {
+        text,
+        previousText,
+        range: { start: text.length, end: text.length },
+        target: 0,
+      },
+    };
+  },
+
+  /**
+   * Experimental values:
+   * - iOS: `{"contentSize": {"height": 21.666666666666668, "width": 11.666666666666666}, "target": 75}`
+   * - Android: `{"contentSize": {"height": 61.45454406738281, "width": 352.7272644042969}, "target": 53}`
+   */
+  contentSizeChange: ({ width, height }: ContentSize) => {
+    return {
+      nativeEvent: { contentSize: { width, height }, target: 0 },
+    };
+  },
+};

src/user-event/index.ts

@@ -1,6 +1,7 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { setup } from './setup';
-import { PressOptions } from './press/press';
+import { PressOptions } from './press';
+import { TypeOptions } from './type';
 
 export const userEvent = {
   setup,
@@ -9,6 +10,6 @@ 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),
 };

src/user-event/press/index.ts

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

src/user-event/setup/setup.ts

@@ -1,8 +1,7 @@
 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';
 
 export interface UserEventSetupOptions {
   /**
@@ -46,14 +45,20 @@ 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);
   const instance = createInstance(config);
   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 +71,43 @@ 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 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 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>;
 }
 
 function createInstance(config: UserEventConfig): UserEventInstance {