@testing-library/react-native 12.2.0 → 12.2.1

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

@@ -3,13 +3,8 @@ import { isHostTextInput } from '../../helpers/host-component-names';
 import { EventBuilder } from '../event-builder';
 import { ErrorWithStack } from '../../helpers/errors';
 import { isPointerEventEnabled } from '../../helpers/pointer-events';
-import { UserEventInstance } from '../setup';
-import {
-  dispatchEvent,
-  wait,
-  getTextRange,
-  getTextContentSize,
-} from '../utils';
+import { UserEventConfig, UserEventInstance } from '../setup';
+import { dispatchEvent, wait, getTextContentSize } from '../utils';
 
 import { parseKeys } from './parseKeys';
 
@@ -54,12 +49,16 @@ export async function type(
     const previousText = element.props.value ?? currentText;
     currentText = applyKey(previousText, key);
 
-    await wait(this.config);
-    emitTypingEvents(element, key, currentText, previousText);
+    await emitTypingEvents(
+      this.config,
+      element,
+      key,
+      currentText,
+      previousText
+    );
   }
 
   const finalText = element.props.value ?? currentText;
-
   await wait(this.config);
 
   if (options?.submitEditing) {
@@ -79,7 +78,8 @@ export async function type(
   dispatchEvent(element, 'blur', EventBuilder.Common.blur());
 }
 
-async function emitTypingEvents(
+export async function emitTypingEvents(
+  config: UserEventConfig,
   element: ReactTestInstance,
   key: string,
   currentText: string,
@@ -87,6 +87,7 @@ async function emitTypingEvents(
 ) {
   const isMultiline = element.props.multiline === true;
 
+  await wait(config);
   dispatchEvent(element, 'keyPress', EventBuilder.TextInput.keyPress(key));
 
   // According to the docs only multiline TextInput emits textInput event
@@ -100,10 +101,12 @@ async function emitTypingEvents(
   }
 
   dispatchEvent(element, 'change', EventBuilder.TextInput.change(currentText));
-
   dispatchEvent(element, 'changeText', currentText);
 
-  const selectionRange = getTextRange(currentText);
+  const selectionRange = {
+    start: currentText.length,
+    end: currentText.length,
+  };
   dispatchEvent(
     element,
     'selectionChange',

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/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,5 +1,6 @@
 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

@@ -2,10 +2,3 @@ export interface TextRange {
   start: number;
   end: number;
 }
-
-export function getTextRange(text: string): TextRange {
-  return {
-    start: text.length,
-    end: text.length,
-  };
-}

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

@@ -14,6 +14,8 @@ title: User Event
 - [`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.
@@ -108,6 +110,10 @@ 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.
 
+:::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.
@@ -141,3 +147,45 @@ The `textInput` event is sent only for mutliline text inputs.
 
 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/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"}