@testing-library/react-native 12.1.3 → 12.2.1

package/src/user-event/utils/__tests__/dispatch-event.test.tsx

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import { Text } from 'react-native';
+import render from '../../../render';
+import { dispatchEvent } from '../dispatch-event';
+import { EventBuilder } from '../../event-builder';
+
+const TOUCH_EVENT = EventBuilder.Common.touch();
+
+describe('dispatchEvent', () => {
+  it('does dispatch event', () => {
+    const onPress = jest.fn();
+    const screen = render(<Text testID="text" onPress={onPress} />);
+
+    dispatchEvent(screen.getByTestId('text'), 'press', TOUCH_EVENT);
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not dispatch event to parent host component', () => {
+    const onPressParent = jest.fn();
+    const screen = render(
+      <Text onPress={onPressParent}>
+        <Text testID="text" />
+      </Text>
+    );
+
+    dispatchEvent(screen.getByTestId('text'), 'press', TOUCH_EVENT);
+    expect(onPressParent).not.toHaveBeenCalled();
+  });
+
+  it('does NOT throw if no handler found', () => {
+    const screen = render(
+      <Text>
+        <Text testID="text" />
+      </Text>
+    );
+
+    expect(() =>
+      dispatchEvent(screen.getByTestId('text'), 'press', TOUCH_EVENT)
+    ).not.toThrow();
+  });
+});

package/src/user-event/utils/__tests__/wait.test.ts

@@ -2,7 +2,6 @@ import { wait } from '../wait';
 
 beforeEach(() => {
   jest.useRealTimers();
-  jest.clearAllMocks();
 });
 
 describe('wait()', () => {

package/src/user-event/utils/content-size.ts

@@ -0,0 +1,25 @@
+export interface ContentSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Simple function for getting mock the size of given text.
+ *
+ * It works by calculating height based on number of lines and width based on
+ * the longest line length. It does not take into account font size, font
+ * family, as well as different letter sizes.
+ *
+ * @param text text to be measure
+ * @returns width and height of the text
+ */
+
+export function getTextContentSize(text: string): ContentSize {
+  const lines = text.split('\n');
+  const maxLineLength = Math.max(...lines.map((line) => line.length));
+
+  return {
+    width: maxLineLength * 5,
+    height: lines.length * 16,
+  };
+}

package/src/user-event/utils/dispatch-event.ts

@@ -0,0 +1,38 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import act from '../../act';
+
+/**
+ * Basic dispatch event function used by User Event module.
+ *
+ * @param element element trigger event on
+ * @param eventName name of the event
+ * @param event event payload
+ */
+export function dispatchEvent(
+  element: ReactTestInstance,
+  eventName: string,
+  event: unknown
+) {
+  const handler = getEventHandler(element, eventName);
+  if (!handler) {
+    return;
+  }
+
+  act(() => {
+    handler(event);
+  });
+}
+
+function getEventHandler(element: ReactTestInstance, eventName: string) {
+  const handleName = getEventHandlerName(eventName);
+  const handle = element.props[handleName] as unknown;
+  if (typeof handle !== 'function') {
+    return undefined;
+  }
+
+  return handle;
+}
+
+function getEventHandlerName(eventName: string) {
+  return `on${eventName.charAt(0).toUpperCase()}${eventName.slice(1)}`;
+}

package/src/user-event/utils/host-components.ts

@@ -0,0 +1,6 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { isHostTextInput } from '../../helpers/host-component-names';
+
+export function isEditableTextInput(element: ReactTestInstance) {
+  return isHostTextInput(element) && element.props.editable !== false;
+}

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

@@ -1,2 +1,6 @@
-export * from './events';
+export * from './content-size';
+export * from './dispatch-event';
+export * from './host-components';
+export * from './text-range';
 export * from './wait';
+export * from './warn-about-real-timers';

package/src/user-event/utils/text-range.ts

@@ -0,0 +1,4 @@
+export interface TextRange {
+  start: number;
+  end: number;
+}

package/src/user-event/{press/utils/warnAboutRealTimers.ts → utils/warn-about-real-timers.ts}

@@ -1,4 +1,11 @@
-export const warnAboutRealTimers = () => {
+import { jestFakeTimersAreEnabled } from '../../helpers/timers';
+
+export const warnAboutRealTimersIfNeeded = () => {
+  const areFakeTimersEnabled = jestFakeTimersAreEnabled();
+  if (areFakeTimersEnabled) {
+    return;
+  }
+
   // eslint-disable-next-line no-console
   console.warn(`It is recommended to use userEvent with fake timers
 Some events involve duration so your tests may take a long time to run.

package/website/docs/API.md

@@ -7,20 +7,13 @@ title: API
 
 - [`render`](#render)
   - [`render` options](#render-options)
-    - [`wrapper` option](#wrapper-option)
-    - [`createNodeMock` option](#createnodemock-option)
-    - [`unstable_validateStringsRenderedWithinText` option](#unstable_validatestringsrenderedwithintext-option)
   - [`...queries`](#queries)
-    - [Example](#example)
   - [`update`](#update)
   - [`unmount`](#unmount)
   - [`debug`](#debug)
-    - [`message` option](#message-option)
-    - [`mapProps` option](#mapprops-option)
-    - [`debug.shallow`](#debugshallow)
   - [`toJSON`](#tojson)
   - [`root`](#root)
-  - [`UNSAFE_root`](#unsafe_root)
+  - [`UNSAFE_root`](#unsaferoot)
 - [`screen`](#screen)
 - [`cleanup`](#cleanup)
 - [`fireEvent`](#fireevent)
@@ -28,10 +21,8 @@ title: API
   - [`fireEvent.press`](#fireeventpress)
   - [`fireEvent.changeText`](#fireeventchangetext)
   - [`fireEvent.scroll`](#fireeventscroll)
-    - [On a `ScrollView`](#on-a-scrollview)
-    - [On a `FlatList`](#on-a-flatlist)
 - [`waitFor`](#waitfor)
-  - [Using Jest fake timers](#using-jest-fake-timers)
+  - [Using a React Native version \< 0.71 with Jest fake timers](#using-a-react-native-version--071-with-jest-fake-timers)
 - [`waitForElementToBeRemoved`](#waitforelementtoberemoved)
 - [`within`, `getQueriesForElement`](#within-getqueriesforelement)
 - [`queryBy*` APIs](#queryby-apis)
@@ -40,24 +31,12 @@ title: API
 - [`renderHook`](#renderhook)
   - [`callback`](#callback)
   - [`options` (Optional)](#options-optional)
-    - [`initialProps`](#initialprops)
-    - [`wrapper`](#wrapper)
   - [`RenderHookResult` object](#renderhookresult-object)
-    - [`result`](#result)
-    - [`rerender`](#rerender)
-    - [`unmount`](#unmount-1)
   - [Examples](#examples)
-    - [With `initialProps`](#with-initialprops)
-    - [With `wrapper`](#with-wrapper)
 - [Configuration](#configuration)
   - [`configure`](#configure)
-    - [`asyncUtilTimeout` option](#asyncutiltimeout-option)
-    - [`defaultIncludeHiddenElements` option](#defaultincludehiddenelements-option)
-    - [`defaultDebugOptions` option](#defaultdebugoptions-option)
   - [`resetToDefaults()`](#resettodefaults)
   - [Environment variables](#environment-variables)
-    - [`RNTL_SKIP_AUTO_CLEANUP`](#rntl_skip_auto_cleanup)
-    - [`RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS`](#rntl_skip_auto_detect_fake_timers)
 - [Accessibility](#accessibility)
   - [`isHiddenFromAccessibility`](#ishiddenfromaccessibility)
 
@@ -346,9 +325,16 @@ function fireEvent(
 ): void {}
 ```
 
-Fires native-like event with data.
+:::note
+For common events like `press` or `type` it's recommended to use [User Event API](UserEvent.md) as it offers 
+more realistic event simulation by emitting a sequence of events with proper event objects that mimic React Native runtime behavior.
+
+Use Fire Event for cases not supported by User Event and for triggering event handlers on composite components.
+:::
 
-Invokes a given event handler (whether native or custom) on the element, bubbling to the root of the rendered tree.
+`fireEvent` API allows you to trigger all kind of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed.
+
+Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object.
 
 ```jsx
 import { render, screen, fireEvent } from '@testing-library/react-native';
@@ -402,6 +388,10 @@ Convenience methods for common events like: `press`, `changeText`, `scroll`.
 fireEvent.press: (element: ReactTestInstance, ...data: Array<any>) => void
 ```
 
+:::note
+It is recommended to use the User Event [`press()`](UserEvent.md#press) helper instead as it offers more realistic simulation of press interaction, including pressable support.
+:::
+
 Invokes `press` event handler on the element or parent element in the tree.
 
 ```jsx
@@ -434,6 +424,10 @@ expect(onPressMock).toHaveBeenCalledWith(eventData);
 fireEvent.changeText: (element: ReactTestInstance, ...data: Array<any>) => void
 ```
 
+:::note
+It is recommended to use the User Event [`type()`](UserEvent.md#type) helper instead as it offers more realistic simulation of text change interaction, including key-by-key typing, element focus, and other editing events.
+:::
+
 Invokes `changeText` event handler on the element or parent element in the tree.
 
 ```jsx

package/website/docs/Queries.md

@@ -14,17 +14,14 @@ title: Queries
   - [findAllBy](#findallby)
 - [Queries](#queries)
   - [Options](#options)
+  - [`ByRole`](#byrole)
   - [`ByText`](#bytext)
   - [`ByPlaceholderText`](#byplaceholdertext)
   - [`ByDisplayValue`](#bydisplayvalue)
   - [`ByTestId`](#bytestid)
   - [`ByLabelText`](#bylabeltext)
   - [`ByHintText`, `ByA11yHint`, `ByAccessibilityHint`](#byhinttext-bya11yhint-byaccessibilityhint)
-  - [`ByRole`](#byrole)
-    - [Options](#options-1)
   - [`ByA11yState`, `ByAccessibilityState` (deprecated)](#bya11ystate-byaccessibilitystate-deprecated)
-    - [Default state for: `disabled`, `selected`, and `busy` keys](#default-state-for-disabled-selected-and-busy-keys)
-    - [Default state for: `checked` and `expanded` keys](#default-state-for-checked-and-expanded-keys)
   - [`ByA11yValue`, `ByAccessibilityValue` (deprecated)](#bya11yvalue-byaccessibilityvalue-deprecated)
 - [Common options](#common-options)
   - [`includeHiddenElements` option](#includehiddenelements-option)
@@ -32,7 +29,6 @@ title: Queries
   - [Examples](#examples)
   - [Precision](#precision)
   - [Normalization](#normalization)
-    - [Normalization Examples](#normalization-examples)
 - [Unit testing helpers](#unit-testing-helpers)
   - [`UNSAFE_ByType`](#unsafe_bytype)
   - [`UNSAFE_ByProps`](#unsafe_byprops)
@@ -95,6 +91,69 @@ type ReactTestInstance = {
 
 Usually query first argument can be a **string** or a **regex**. All queries take at least the [`hidden`](#hidden-option) option as an optionnal second argument and some queries accept more options which change string matching behaviour. See [TextMatch](#textmatch) for more info.
 
+### `ByRole`
+
+> getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole
+
+```ts
+getByRole(
+  role: TextMatch,
+  options?: {
+    name?: TextMatch
+    disabled?: boolean,
+    selected?: boolean,
+    checked?: boolean | 'mixed',
+    busy?: boolean,
+    expanded?: boolean,
+    value: {
+      min?: number;
+      max?: number;
+      now?: number;
+      text?: TextMatch;
+    },
+    includeHiddenElements?: boolean;
+  }
+): ReactTestInstance;
+```
+
+Returns a `ReactTestInstance` with matching `accessibilityRole` prop.
+
+:::info
+In order for `*ByRole` queries to match an element it needs to be considered an accessibility element:
+1. `Text`, `TextInput` and `Switch` host elements are these by default.
+2. `View` host elements need an explicit [`accessible`](https://reactnative.dev/docs/accessibility#accessible) prop set to `true`
+3. Some React Native composite components like `Pressable` & `TouchableOpacity` render host `View` element with `accessible` prop already set.
+:::
+
+```jsx
+import { render, screen } from '@testing-library/react-native';
+
+render(
+  <Pressable accessibilityRole="button" disabled>
+    <Text>Hello</Text>
+  </Pressable>
+);
+const element = screen.getByRole('button');
+const element2 = screen.getByRole('button', { name: 'Hello' });
+const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });
+```
+
+#### Options
+
+`name`: Finds an element with given `accessibilityRole` and an accessible name (equivalent to `byText` or `byLabelText` query).
+
+`disabled`: You can filter elements by their disabled state. The possible values are `true` or `false`. Querying `disabled: false` will also match elements with `disabled: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `disabled` state.
+
+`selected`: You can filter elements by their selected state. The possible values are `true` or `false`. Querying `selected: false` will also match elements with `selected: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `selected` state.
+
+`checked`: You can filter elements by their checked state. The possible values are `true`, `false`, or `"mixed"`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `checked` state.
+
+`busy`: You can filter elements by their busy state. The possible values are `true` or `false`. Querying `busy: false` will also match elements with `busy: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `busy` state.
+
+`expanded`: You can filter elements by their expanded state. The possible values are `true` or `false`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `expanded` state.
+
+`value`: Filter elements by their accessibility, available value entries include numeric `min`, `max` & `now`, as well as string or regex `text` key. See React Native [accessibilityValue](https://reactnative.dev/docs/accessibility#accessibilityvalue) docs to learn more about this prop.
+
 ### `ByText`
 
 > getByText, getAllByText, queryByText, queryAllByText, findByText, findAllByText
@@ -253,61 +312,7 @@ const element = screen.getByHintText('Plays a song');
 Please consult [Apple guidelines on how `accessibilityHint` should be used](https://developer.apple.com/documentation/objectivec/nsobject/1615093-accessibilityhint).
 :::
 
-### `ByRole`
-
-> getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole
-
-```ts
-getByRole(
-  role: TextMatch,
-  options?: {
-    name?: TextMatch
-    disabled?: boolean,
-    selected?: boolean,
-    checked?: boolean | 'mixed',
-    busy?: boolean,
-    expanded?: boolean,
-    value: {
-      min?: number;
-      max?: number;
-      now?: number;
-      text?: TextMatch;
-    },
-    includeHiddenElements?: boolean;
-  }
-): ReactTestInstance;
-```
-
-Returns a `ReactTestInstance` with matching `accessibilityRole` prop.
 
-```jsx
-import { render, screen } from '@testing-library/react-native';
-
-render(
-  <Pressable accessibilityRole="button" disabled>
-    <Text>Hello</Text>
-  </Pressable>
-);
-const element = screen.getByRole('button');
-const element2 = screen.getByRole('button', { name: 'Hello' });
-const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });
-```
-
-#### Options
-
-`name`: Finds an element with given `accessibilityRole` and an accessible name (equivalent to `byText` or `byLabelText` query).
-
-`disabled`: You can filter elements by their disabled state. The possible values are `true` or `false`. Querying `disabled: false` will also match elements with `disabled: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `disabled` state.
-
-`selected`: You can filter elements by their selected state. The possible values are `true` or `false`. Querying `selected: false` will also match elements with `selected: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `selected` state.
-
-`checked`: You can filter elements by their checked state. The possible values are `true`, `false`, or `"mixed"`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `checked` state.
-
-`busy`: You can filter elements by their busy state. The possible values are `true` or `false`. Querying `busy: false` will also match elements with `busy: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `busy` state.
-
-`expanded`: You can filter elements by their expanded state. The possible values are `true` or `false`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `expanded` state.
-
-`value`: Filter elements by their accessibility, available value entries include numeric `min`, `max` & `now`, as well as string or regex `text` key. See React Native [accessibilityValue](https://reactnative.dev/docs/accessibility#accessibilityvalue) docs to learn more about this prop.
 
 ### `ByA11yState`, `ByAccessibilityState` (deprecated)
 

package/website/docs/UserEvent.md

@@ -5,11 +5,33 @@ title: User Event
 
 ### Table of contents
 
-- [`userEvent.setup`](#usereventsetup)
+- [Comparison with Fire Event API](#comparison-with-fire-event-api)
+- [`setup()`](#setup)
   - [Options](#options)
+- [`press()`](#press)
+- [`longPress()`](#longpress)
+  - [Options](#options-1)
+- [`type()`](#type)
+  - [Options](#options-2)
+  - [Sequence of events](#sequence-of-events)
+- [`clear()`](#clear)
+  - [Sequence of events](#sequence-of-events-1)
 
+:::caution
+User Event API is in beta stage.
 
-## `userEvent.setup`
+This means that we plan to keep the public API signatures to remain stable, but we might introduce breaking behavioural changes, e.g. changing the ordering or timing of emitted events, without a major version update. Hopefully, well written code should not rely on such specific details.
+:::
+
+## Comparison with Fire Event API
+
+Fire Event is our original event simulation API. It offers ability to invoke **any event handler** declared on **either host or composite elements**. If the element does not have `onEventName` event handler for passed `eventName` event, or the element is disabled, Fire Event will traverse up the component tree, looking for event handler on both host and composite elements along the way. By default it will **not pass any event data**, but the user might provide it in the last argument.
+
+In contrast, User Event provides realistic event simulation for main user interactions like `press` or `type`. Each of the interactions will trigger a **sequence of events** corresponding to React Native runtime behavior. These events will be invoked **only on host elements**, and **will automatically receive event data** corresponding to each event.
+
+If User Event supports given interaction you should always prefer it over Fire Event counterpart, as it will make your tests much more realistic and hence reliable. In other cases, e.g. when event is not supported by User Event, or when invoking event handlers on composite elements, you have to use Fire Event as the only available option.
+
+## `setup()`
 
 ```ts
 userEvent.setup(options?: {
@@ -23,11 +45,11 @@ Example
 const user = userEvent.setup();
 ```
 
-Creates User Event instances which can be used to trigger events.
+Creates an User Event object instance which can be used to trigger events.
 
 ### Options
-- `delay` - controls the default delay between subsequent events, e.g. keystrokes, etc.
-- `advanceTimers` - time advancement utility function that should be used for fake timers. The default setup handles both real and Jest fake timers.
+- `delay` - controls the default delay between subsequent events, e.g. keystrokes.
+- `advanceTimers` - time advancement utility function that should be used for fake timers. The default setup handles both real timers and Jest fake timers.
 
 
 ## `press()`
@@ -41,11 +63,10 @@ press(
 Example
 ```ts
 const user = userEvent.setup();
-
 await user.press(element);
 ```
 
-This helper simulates a press on any pressable element, e.g. `Pressable`, `TouchableOpacity`, `Text`, `TextInput`, etc. Unlike `fireEvent.press()` which is a simpler API that will only call the `onPress` prop, this simulates the entire press event in a more realistic way by reproducing what really happens when a user presses an interface view. This will trigger additional events like `pressIn` and `pressOut`. 
+This helper simulates a press on any pressable element, e.g. `Pressable`, `TouchableOpacity`, `Text`, `TextInput`, etc. Unlike `fireEvent.press()` which is a simpler API that will only call the `onPress` prop, this function simulates the entire press interaction in a more realistic way by reproducing event sequence emitted by React Native runtime. This helper will trigger additional events like `pressIn` and `pressOut`. 
 
 ## `longPress()`
 
@@ -59,8 +80,112 @@ longPress(
 Example
 ```ts
 const user = userEvent.setup();
-
 await user.longPress(element);
 ```
 
-Simulates a long press user interaction. In React Native the `longPress` event is emitted when the press duration exceeds long press threshold (by default 500 ms). In other aspects this actions behaves similar to regular `press` action, e.g. by emitting `pressIn` and `pressOut` events. The press duration is customisable through the options. This should be useful if you use the `delayLongPress` prop. When using real timers this will take 500 ms so it is highly recommended to use that API with fake timers to prevent test taking a long time to run. 
+Simulates a long press user interaction. In React Native the `longPress` event is emitted when the press duration exceeds long press threshold (by default 500 ms). In other aspects this actions behaves similar to regular `press` action, e.g. by emitting `pressIn` and `pressOut` events. The press duration is customisable through the options. This should be useful if you use the `delayLongPress` prop. When using real timers this will take 500 ms so it is highly recommended to use that API with fake timers to prevent test taking a long time to run. 
+
+### Options
+- `duration` - duration of the press in miliseconds. Default value is 500 ms.
+
+## `type()`
+
+```ts
+type(
+  element: ReactTestInstance,
+  text: string,
+  options?: {
+    skipPress?: boolean
+    submitEditing?: boolean
+  }
+```
+
+Example
+```ts
+const user = userEvent.setup();
+await user.type(textInput, "Hello world!");
+```
+
+This helper simulates user focusing on `TextInput` element, typing `text` one character at a time, and leaving the element.
+
+This function supports only host `TextInput` elements. Passing other element type will result in throwing error.
+
+:::note
+This function will add text to the text already present in the text input (as specified by `value` or `defaultValue` props). In order to replace existing text, use [`clear()`](#clear) helper first.
+:::
+
+### Options
+ - `skipPress` - if true, `pressIn` and `pressOut` events will not be triggered.
+ - `submitEditing` - if true, `submitEditing` event will be triggered after typing the text.
+
+### Sequence of events
+
+The sequence of events depends on `multiline` prop, as well as passed options.
+
+Events will not be emitted if `editable` prop is set to `false`.
+
+**Entering the element**:
+- `pressIn` (optional)
+- `focus`
+- `pressOut` (optional)
+
+The `pressIn` and `pressOut` events are sent by default, but can be skipped by passing `skipPress: true` option.
+
+**Typing (for each character)**:
+- `keyPress`
+- `textInput` (optional)
+- `change`
+- `changeText`
+- `selectionChange`
+
+The `textInput` event is sent only for mutliline text inputs.
+
+**Leaving the element**:
+- `submitEditing` (optional)
+- `endEditing`
+- `blur`
+
+The `submitEditing` event is skipped by default. It can sent by setting `submitEditing: true` option.
+
+## `clear()`
+
+```ts
+clear(
+  element: ReactTestInstance,
+}
+```
+
+Example
+```ts
+const user = userEvent.setup();
+await user.clear(textInput);
+```
+
+This helper simulates user clearing content of `TextInput` element.
+
+This function supports only host `TextInput` elements. Passing other element type will result in throwing error.
+
+### Sequence of events
+
+The sequence of events depends on `multiline` prop, as well as passed options.
+
+Events will not be emitted if `editable` prop is set to `false`.
+
+**Entering the element**:
+- `focus`
+
+**Selecting all content**:
+- `selectionChange`
+
+**Pressing backspace**:
+- `keyPress`
+- `textInput` (optional)
+- `change`
+- `changeText`
+- `selectionChange`
+
+The `textInput` event is sent only for mutliline text inputs.
+
+**Leaving the element**:
+- `endEditing`
+- `blur`

package/website/sidebars.js

@@ -1,7 +1,7 @@
 module.exports = {
   docs: {
     Introduction: ['getting-started', 'faq'],
-    'API Reference': ['api', 'api-queries'],
+    'API Reference': ['api', 'api-queries', 'user-event'],
     Guides: [
       'troubleshooting',
       'how-should-i-query',

package/build/helpers/filterNodeByType.d.ts

@@ -1,3 +0,0 @@
-import type { ReactTestInstance } from 'react-test-renderer';
-import * as React from 'react';
-export declare const filterNodeByType: (node: ReactTestInstance | React.ReactElement, type: React.ElementType | string) => boolean;

package/build/helpers/filterNodeByType.js

@@ -1,9 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.filterNodeByType = void 0;
-const filterNodeByType = (node, type) => node.type === type;
-exports.filterNodeByType = filterNodeByType;
-//# sourceMappingURL=filterNodeByType.js.map

package/build/helpers/filterNodeByType.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"filterNodeByType.js","names":["filterNodeByType","node","type","exports"],"sources":["../../src/helpers/filterNodeByType.ts"],"sourcesContent":["import type { ReactTestInstance } from 'react-test-renderer';\nimport * as React from 'react';\n\nexport const filterNodeByType = (\n  node: ReactTestInstance | React.ReactElement,\n  type: React.ElementType | string\n) => node.type === type;\n"],"mappings":";;;;;;AAGO,MAAMA,gBAAgB,GAAGA,CAC9BC,IAA4C,EAC5CC,IAAgC,KAC7BD,IAAI,CAACC,IAAI,KAAKA,IAAI;AAACC,OAAA,CAAAH,gBAAA,GAAAA,gBAAA"}

package/build/user-event/press/utils/warnAboutRealTimers.d.ts

@@ -1 +0,0 @@
-export declare const warnAboutRealTimers: () => void;

package/build/user-event/press/utils/warnAboutRealTimers.js

@@ -1,14 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.warnAboutRealTimers = void 0;
-const warnAboutRealTimers = () => {
-  // eslint-disable-next-line no-console
-  console.warn(`It is recommended to use userEvent with fake timers
-Some events involve duration so your tests may take a long time to run.
-For instance calling userEvent.longPress with real timers will take 500 ms.`);
-};
-exports.warnAboutRealTimers = warnAboutRealTimers;
-//# sourceMappingURL=warnAboutRealTimers.js.map

package/build/user-event/press/utils/warnAboutRealTimers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"warnAboutRealTimers.js","names":["warnAboutRealTimers","console","warn","exports"],"sources":["../../../../src/user-event/press/utils/warnAboutRealTimers.ts"],"sourcesContent":["export const warnAboutRealTimers = () => {\n  // eslint-disable-next-line no-console\n  console.warn(`It is recommended to use userEvent with fake timers\nSome events involve duration so your tests may take a long time to run.\nFor instance calling userEvent.longPress with real timers will take 500 ms.`);\n};\n"],"mappings":";;;;;;AAAO,MAAMA,mBAAmB,GAAGA,CAAA,KAAM;EACvC;EACAC,OAAO,CAACC,IAAI,CAAE;AAChB;AACA,4EAA4E,CAAC;AAC7E,CAAC;AAACC,OAAA,CAAAH,mBAAA,GAAAA,mBAAA"}