@testing-library/react-native 12.1.3 → 12.2.0

package/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,7 +45,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 +53,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 +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 {

package/src/user-event/type/__tests__/__snapshots__/type-managed.test.tsx.snap

@@ -0,0 +1,339 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`type() for managed TextInput supports basic case: input: "Wow" 1`] = `
+[
+  {
+    "name": "pressIn",
+    "payload": {
+      "currentTarget": {
+        "measure": [MockFunction],
+      },
+      "nativeEvent": {
+        "changedTouches": [],
+        "identifier": 0,
+        "locationX": 0,
+        "locationY": 0,
+        "pageX": 0,
+        "pageY": 0,
+        "target": 0,
+        "timestamp": 100100100100,
+        "touches": [],
+      },
+      "persist": [MockFunction],
+    },
+  },
+  {
+    "name": "focus",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+      },
+    },
+  },
+  {
+    "name": "pressOut",
+    "payload": {
+      "currentTarget": {
+        "measure": [MockFunction],
+      },
+      "nativeEvent": {
+        "changedTouches": [],
+        "identifier": 0,
+        "locationX": 0,
+        "locationY": 0,
+        "pageX": 0,
+        "pageY": 0,
+        "target": 0,
+        "timestamp": 100100100100,
+        "touches": [],
+      },
+      "persist": [MockFunction],
+    },
+  },
+  {
+    "name": "keyPress",
+    "payload": {
+      "nativeEvent": {
+        "key": "W",
+      },
+    },
+  },
+  {
+    "name": "change",
+    "payload": {
+      "nativeEvent": {
+        "eventCount": 0,
+        "target": 0,
+        "text": "W",
+      },
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "W",
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "nativeEvent": {
+        "selection": {
+          "end": 1,
+          "start": 1,
+        },
+      },
+    },
+  },
+  {
+    "name": "keyPress",
+    "payload": {
+      "nativeEvent": {
+        "key": "o",
+      },
+    },
+  },
+  {
+    "name": "change",
+    "payload": {
+      "nativeEvent": {
+        "eventCount": 0,
+        "target": 0,
+        "text": "Wo",
+      },
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "Wo",
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "nativeEvent": {
+        "selection": {
+          "end": 2,
+          "start": 2,
+        },
+      },
+    },
+  },
+  {
+    "name": "keyPress",
+    "payload": {
+      "nativeEvent": {
+        "key": "w",
+      },
+    },
+  },
+  {
+    "name": "change",
+    "payload": {
+      "nativeEvent": {
+        "eventCount": 0,
+        "target": 0,
+        "text": "Wow",
+      },
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "Wow",
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "nativeEvent": {
+        "selection": {
+          "end": 3,
+          "start": 3,
+        },
+      },
+    },
+  },
+  {
+    "name": "endEditing",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+        "text": "Wow",
+      },
+    },
+  },
+  {
+    "name": "blur",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+      },
+    },
+  },
+]
+`;
+
+exports[`type() for managed TextInput supports rejecting TextInput: input: "ABC", value: "XXX" 1`] = `
+[
+  {
+    "name": "pressIn",
+    "payload": {
+      "currentTarget": {
+        "measure": [MockFunction],
+      },
+      "nativeEvent": {
+        "changedTouches": [],
+        "identifier": 0,
+        "locationX": 0,
+        "locationY": 0,
+        "pageX": 0,
+        "pageY": 0,
+        "target": 0,
+        "timestamp": 100100100100,
+        "touches": [],
+      },
+      "persist": [MockFunction],
+    },
+  },
+  {
+    "name": "focus",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+      },
+    },
+  },
+  {
+    "name": "pressOut",
+    "payload": {
+      "currentTarget": {
+        "measure": [MockFunction],
+      },
+      "nativeEvent": {
+        "changedTouches": [],
+        "identifier": 0,
+        "locationX": 0,
+        "locationY": 0,
+        "pageX": 0,
+        "pageY": 0,
+        "target": 0,
+        "timestamp": 100100100100,
+        "touches": [],
+      },
+      "persist": [MockFunction],
+    },
+  },
+  {
+    "name": "keyPress",
+    "payload": {
+      "nativeEvent": {
+        "key": "A",
+      },
+    },
+  },
+  {
+    "name": "change",
+    "payload": {
+      "nativeEvent": {
+        "eventCount": 0,
+        "target": 0,
+        "text": "XXXA",
+      },
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "XXXA",
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "nativeEvent": {
+        "selection": {
+          "end": 4,
+          "start": 4,
+        },
+      },
+    },
+  },
+  {
+    "name": "keyPress",
+    "payload": {
+      "nativeEvent": {
+        "key": "B",
+      },
+    },
+  },
+  {
+    "name": "change",
+    "payload": {
+      "nativeEvent": {
+        "eventCount": 0,
+        "target": 0,
+        "text": "XXXB",
+      },
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "XXXB",
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "nativeEvent": {
+        "selection": {
+          "end": 4,
+          "start": 4,
+        },
+      },
+    },
+  },
+  {
+    "name": "keyPress",
+    "payload": {
+      "nativeEvent": {
+        "key": "C",
+      },
+    },
+  },
+  {
+    "name": "change",
+    "payload": {
+      "nativeEvent": {
+        "eventCount": 0,
+        "target": 0,
+        "text": "XXXC",
+      },
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "XXXC",
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "nativeEvent": {
+        "selection": {
+          "end": 4,
+          "start": 4,
+        },
+      },
+    },
+  },
+  {
+    "name": "endEditing",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+        "text": "XXX",
+      },
+    },
+  },
+  {
+    "name": "blur",
+    "payload": {
+      "nativeEvent": {
+        "target": 0,
+      },
+    },
+  },
+]
+`;