chore: expose User Event in the exports and website

src/pure.ts

@@ -14,6 +14,7 @@ export {
 export { getDefaultNormalizer } from './matches';
 export { renderHook } from './renderHook';
 export { screen } from './screen';
+export { userEvent } from './user-event';
 
 export type {
   RenderOptions,
@@ -23,3 +24,4 @@ export type {
 } from './render';
 export type { RenderHookOptions, RenderHookResult } from './renderHook';
 export type { Config } from './config';
+export type { UserEventConfig } from './user-event';

src/user-event/index.ts

@@ -3,6 +3,8 @@ import { setup } from './setup';
 import { PressOptions } from './press';
 import { TypeOptions } from './type';
 
+export { UserEventConfig } from './setup';
+
 export const userEvent = {
   setup,
 

website/docs/API.md

@@ -7,31 +7,22 @@ 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)
 - [`fireEvent[eventName]`](#fireeventeventname)
   - [`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 
+much more realistic event simulation by emitting a sequence of events with proper event objects that mimic React Native runtime behavior.
+
+Use `fireEvent()` 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 API](UserEvent.md#press) 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 API](UserEvent.md#type) instead as it offers more realistic simulation of text change interaction.
+::
+
 Invokes `changeText` event handler on the element or parent element in the tree.
 
 ```jsx

website/docs/UserEvent.md

@@ -9,10 +9,18 @@ title: User Event
   - [Options](#options)
 - [`press()`](#press)
 - [`longPress()`](#longpress)
+  - [Options](#options-1)
 - [`type()`](#type)
-  - [Options:](#options-1)
+  - [Options](#options-2)
   - [Sequence of events](#sequence-of-events)
 
+:::caution
+User Event API is in beta stage.
+
+This means that we intend for the public API signatures to remain stable,
+but we might introduce breaking behavioural changes, e.g. concerning ordering or timing of emitted events, without a major version update. Hopefully, well written
+test code should not rely on such specific details.
+:::
 
 ## `userEvent.setup`
 
@@ -68,6 +76,9 @@ 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. 
 
+### Options
+- `duration` - duration of the press in miliseconds. Default value is 500 ms.
+
 ## `type()`
 
 ```ts
@@ -90,7 +101,7 @@ This helper simulates user focusing on `TextInput` element, typing `text` one ch
 
 This function supports only host `TextInput` elements. Passing other element type will result in throwing error.
 
-### Options:
+### Options
  - `skipPress` - if true, `pressIn` and `pressOut` events will not be triggered.
  - `submitEditing` - if true, `submitEditing` event will be triggered after typing the text.
 
@@ -122,3 +133,4 @@ Leaving the element:
 - `blur`
 
 The `submitEditing` event is skipped by default. It can sent by setting `submitEditing: true` option.
+

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',