feat: add options to clear text before typing and to clear text without blurring

Author: levibuzolic

src/user-event/__tests__/__snapshots__/clear.test.tsx.snap

@@ -1,5 +1,107 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
+exports[`clear() skips blur and endEditing events when \`skipBlur: true\`: value: "Hello!" skipBlur: true 1`] = `
+[
+  {
+    "name": "focus",
+    "payload": {
+      "currentTarget": {},
+      "isDefaultPrevented": [Function],
+      "isPersistent": [Function],
+      "isPropagationStopped": [Function],
+      "nativeEvent": {
+        "target": 0,
+      },
+      "persist": [Function],
+      "preventDefault": [Function],
+      "stopPropagation": [Function],
+      "target": {},
+      "timeStamp": 0,
+    },
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "currentTarget": {},
+      "isDefaultPrevented": [Function],
+      "isPersistent": [Function],
+      "isPropagationStopped": [Function],
+      "nativeEvent": {
+        "selection": {
+          "end": 6,
+          "start": 0,
+        },
+      },
+      "persist": [Function],
+      "preventDefault": [Function],
+      "stopPropagation": [Function],
+      "target": {},
+      "timeStamp": 0,
+    },
+  },
+  {
+    "name": "keyPress",
+    "payload": {
+      "currentTarget": {},
+      "isDefaultPrevented": [Function],
+      "isPersistent": [Function],
+      "isPropagationStopped": [Function],
+      "nativeEvent": {
+        "key": "Backspace",
+      },
+      "persist": [Function],
+      "preventDefault": [Function],
+      "stopPropagation": [Function],
+      "target": {},
+      "timeStamp": 0,
+    },
+  },
+  {
+    "name": "change",
+    "payload": {
+      "currentTarget": {},
+      "isDefaultPrevented": [Function],
+      "isPersistent": [Function],
+      "isPropagationStopped": [Function],
+      "nativeEvent": {
+        "eventCount": 0,
+        "target": 0,
+        "text": "",
+      },
+      "persist": [Function],
+      "preventDefault": [Function],
+      "stopPropagation": [Function],
+      "target": {},
+      "timeStamp": 0,
+    },
+  },
+  {
+    "name": "changeText",
+    "payload": "",
+  },
+  {
+    "name": "selectionChange",
+    "payload": {
+      "currentTarget": {},
+      "isDefaultPrevented": [Function],
+      "isPersistent": [Function],
+      "isPropagationStopped": [Function],
+      "nativeEvent": {
+        "selection": {
+          "end": 0,
+          "start": 0,
+        },
+      },
+      "persist": [Function],
+      "preventDefault": [Function],
+      "stopPropagation": [Function],
+      "target": {},
+      "timeStamp": 0,
+    },
+  },
+]
+`;
+
 exports[`clear() supports basic case: value: "Hello! 1`] = `
 [
   {

src/user-event/__tests__/clear.test.tsx

@@ -219,4 +219,45 @@ describe('clear()', () => {
     await user.clear(input);
     expect(input).toHaveDisplayValue('');
   });
+
+  it('skips blur and endEditing events when `skipBlur: true`', async () => {
+    const { textInput, events } = renderTextInputWithToolkit({
+      value: 'Hello!',
+    });
+
+    const user = userEvent.setup();
+    await user.clear(textInput, {
+      skipBlur: true,
+    });
+
+    const eventNames = getEventsNames(events);
+
+    // Ensure 'endEditing' and 'blur' are not present
+    expect(eventNames).not.toContain('endEditing');
+    expect(eventNames).not.toContain('blur');
+
+    // Verify the exact events that should be present
+    expect(eventNames).toEqual([
+      'focus',
+      'selectionChange',
+      'keyPress',
+      'change',
+      'changeText',
+      'selectionChange',
+    ]);
+
+    expect(events).toMatchSnapshot('value: "Hello!" skipBlur: true');
+  });
+
+  it('sets native state value for unmanaged text inputs when `skipBlur: true`', async () => {
+    render(<TextInput testID="input" />);
+
+    const user = userEvent.setup();
+    const input = screen.getByTestId('input');
+    await user.type(input, 'abc');
+    expect(input).toHaveDisplayValue('abc');
+
+    await user.clear(input, { skipBlur: true });
+    expect(input).toHaveDisplayValue('');
+  });
 });

src/user-event/clear.ts

@@ -9,7 +9,15 @@ import type { UserEventInstance } from './setup';
 import { emitTypingEvents } from './type/type';
 import { dispatchEvent, wait } from './utils';
 
-export async function clear(this: UserEventInstance, element: ReactTestInstance): Promise<void> {
+export interface BlurOptions {
+  skipBlur?: boolean;
+}
+
+export async function clear(
+  this: UserEventInstance,
+  element: ReactTestInstance,
+  options?: BlurOptions,
+): Promise<void> {
   if (!isHostTextInput(element)) {
     throw new ErrorWithStack(
       `clear() only supports host "TextInput" elements. Passed element has type: "${element.type}".`,
@@ -45,7 +53,9 @@ export async function clear(this: UserEventInstance, element: ReactTestInstance)
   });
 
   // 4. Exit element
-  await wait(this.config);
-  await dispatchEvent(element, 'endEditing', EventBuilder.TextInput.endEditing(emptyText));
-  await dispatchEvent(element, 'blur', EventBuilder.Common.blur());
+  if (!options?.skipBlur) {
+    await wait(this.config);
+    await dispatchEvent(element, 'endEditing', EventBuilder.TextInput.endEditing(emptyText));
+    await dispatchEvent(element, 'blur', EventBuilder.Common.blur());
+  }
 }

src/user-event/index.ts

@@ -1,5 +1,6 @@
 import type { ReactTestInstance } from 'react-test-renderer';
 
+import type { BlurOptions } from './clear';
 import type { PressOptions } from './press';
 import type { ScrollToOptions } from './scroll';
 import { setup } from './setup';
@@ -16,7 +17,7 @@ export const userEvent = {
     setup().longPress(element, options),
   type: (element: ReactTestInstance, text: string, options?: TypeOptions) =>
     setup().type(element, text, options),
-  clear: (element: ReactTestInstance) => setup().clear(element),
+  clear: (element: ReactTestInstance, options?: BlurOptions) => setup().clear(element, options),
   paste: (element: ReactTestInstance, text: string) => setup().paste(element, text),
   scrollTo: (element: ReactTestInstance, options: ScrollToOptions) =>
     setup().scrollTo(element, options),

src/user-event/setup/setup.ts

@@ -2,6 +2,7 @@ import type { ReactTestInstance } from 'react-test-renderer';
 
 import { jestFakeTimersAreEnabled } from '../../helpers/timers';
 import { wrapAsync } from '../../helpers/wrap-async';
+import type { BlurOptions } from '../clear';
 import { clear } from '../clear';
 import { paste } from '../paste';
 import type { PressOptions } from '../press';
@@ -122,7 +123,7 @@ export interface UserEventInstance {
    *
    * @param element TextInput element to clear
    */
-  clear: (element: ReactTestInstance) => Promise<void>;
+  clear: (element: ReactTestInstance, options?: BlurOptions) => Promise<void>;
 
   /**
    * Simulate user pasting the text to a given `TextInput` element.