feat: User Event pullToRefresh()

Author: mdjastrzebski

docs/api/user-event.md

@@ -294,6 +294,30 @@ The sequence of events depends on whether the scroll includes an optional moment
 - `scroll` (multiple events)
 - `momentumScrollEnd`
 
+## `pullToRefresh()`
+
+> [!NOTE]
+> Available since React Native Testing Library 14.1.0.
+
+```ts
+pullToRefresh(
+  instance: TestInstance,
+): Promise<void>
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+await user.pullToRefresh(scrollView);
+```
+
+Simulates a user performing the pull-to-refresh gesture on a host `ScrollView` element, invoking the `onRefresh` handler of its `refreshControl` prop.
+
+This function supports only host `ScrollView` elements, passing other element types will result in an error. Note that `FlatList` and `SectionList` are accepted as they render to a host `ScrollView` element.
+
+If the element has no `refreshControl` prop, or its `RefreshControl` has no `onRefresh` handler, the call resolves without doing anything.
+
 ## `accessibilityAction()`
 
 > [!NOTE]

src/user-event/index.ts

@@ -21,6 +21,7 @@ export const userEvent = {
   paste: (instance: TestInstance, text: string) => setup().paste(instance, text),
   scrollTo: (instance: TestInstance, options: ScrollToOptions) =>
     setup().scrollTo(instance, options),
+  pullToRefresh: (instance: TestInstance) => setup().pullToRefresh(instance),
   accessibilityAction: (instance: TestInstance, actionName: AccessibilityActionName) =>
     setup().accessibilityAction(instance, actionName),
 };

src/user-event/scroll/__tests__/pull-to-refresh.test.tsx

@@ -0,0 +1,80 @@
+import * as React from 'react';
+import { FlatList, RefreshControl, ScrollView, SectionList, Text, View } from 'react-native';
+
+import { render, screen, userEvent } from '../../..';
+
+describe('pullToRefresh()', () => {
+  it('supports ScrollView', async () => {
+    const onRefreshMock = jest.fn();
+    await render(
+      <ScrollView
+        testID="view"
+        refreshControl={<RefreshControl refreshing={false} onRefresh={onRefreshMock} />}
+      />,
+    );
+    const user = userEvent.setup();
+
+    await user.pullToRefresh(screen.getByTestId('view'));
+    expect(onRefreshMock).toHaveBeenCalled();
+  });
+
+  it('supports FlatList', async () => {
+    const onRefreshMock = jest.fn();
+    await render(
+      <FlatList
+        testID="view"
+        data={['A', 'B', 'C']}
+        renderItem={({ item }) => <Text>{item}</Text>}
+        refreshControl={<RefreshControl refreshing={false} onRefresh={onRefreshMock} />}
+      />,
+    );
+    const user = userEvent.setup();
+
+    await user.pullToRefresh(screen.getByTestId('view'));
+    expect(onRefreshMock).toHaveBeenCalled();
+  });
+
+  it('supports SectionList', async () => {
+    const onRefreshMock = jest.fn();
+    await render(
+      <SectionList
+        testID="view"
+        sections={[
+          { title: 'Section 1', data: ['A', 'B', 'C'] },
+          { title: 'Section 2', data: ['D', 'E', 'F'] },
+        ]}
+        renderItem={({ item }) => <Text>{item}</Text>}
+        refreshControl={<RefreshControl refreshing={false} onRefresh={onRefreshMock} />}
+      />,
+    );
+    const user = userEvent.setup();
+
+    await user.pullToRefresh(screen.getByTestId('view'));
+    expect(onRefreshMock).toHaveBeenCalled();
+  });
+
+  it('does not throw when RefreshControl is not set', async () => {
+    await render(<ScrollView testID="view" />);
+    const user = userEvent.setup();
+
+    await expect(user.pullToRefresh(screen.getByTestId('view'))).resolves.toBeUndefined();
+  });
+
+  it('does not throw when RefreshControl onRefresh is not set', async () => {
+    await render(
+      <ScrollView testID="view" refreshControl={<RefreshControl refreshing={false} />} />,
+    );
+    const user = userEvent.setup();
+
+    await expect(user.pullToRefresh(screen.getByTestId('view'))).resolves.toBeUndefined();
+  });
+
+  it('throws when passed a non-ScrollView element', async () => {
+    await render(<View testID="view" />);
+    const user = userEvent.setup();
+
+    await expect(user.pullToRefresh(screen.getByTestId('view'))).rejects.toThrow(
+      /pullToRefresh\(\) works only with host "ScrollView" elements/,
+    );
+  });
+});

src/user-event/scroll/pull-to-refresh.ts

@@ -0,0 +1,28 @@
+import type { TestInstance } from 'test-renderer';
+
+import { act } from '../../act';
+import { ErrorWithStack } from '../../helpers/errors';
+import { isHostScrollView } from '../../helpers/host-component-names';
+import type { UserEventInstance } from '../setup';
+
+export async function pullToRefresh(
+  this: UserEventInstance,
+  instance: TestInstance,
+): Promise<void> {
+  if (!isHostScrollView(instance)) {
+    throw new ErrorWithStack(
+      `pullToRefresh() works only with host "ScrollView" elements. Passed element has type "${instance.type}".`,
+      pullToRefresh,
+    );
+  }
+
+  const refreshControl = instance.props.refreshControl;
+  if (refreshControl == null || typeof refreshControl.props.onRefresh !== 'function') {
+    return;
+  }
+
+  // eslint-disable-next-line require-await
+  await act(async () => {
+    refreshControl.props.onRefresh();
+  });
+}

src/user-event/setup/setup.ts

@@ -11,6 +11,7 @@ import type { PressOptions } from '../press';
 import { longPress, press } from '../press';
 import type { ScrollToOptions } from '../scroll';
 import { scrollTo } from '../scroll';
+import { pullToRefresh } from '../scroll/pull-to-refresh';
 import type { TypeOptions } from '../type';
 import { type } from '../type';
 import { wait } from '../utils';
@@ -149,13 +150,25 @@ export interface UserEventInstance {
   paste: (instance: TestInstance, text: string) => Promise<void>;
 
   /**
-   * Simlate user scorlling a ScrollView element.
+   * Simlate user scorlling a given `ScrollView`-like element.
    *
-   * @param instance ScrollView instance
+   * Supported components: ScrollView, FlatList, SectionList
+   *
+   * @param instance ScrollView-like instance
    * @returns
    */
   scrollTo: (instance: TestInstance, options: ScrollToOptions) => Promise<void>;
 
+  /**
+   * Simulate using pull-to-refresh gesture on a given `ScrollView`-like element.
+   *
+   * Supported components: ScrollView, FlatList, SectionList
+   *
+   * @param instance ScrollView-like instance
+   * @returns
+   */
+  pullToRefresh: (instance: TestInstance) => Promise<void>;
+
   /**
    * Simulate an assistive technology (e.g. screen reader) triggering an
    * accessibility action on a given element.
@@ -185,6 +198,7 @@ function createInstance(config: UserEventConfig): UserEventInstance {
     clear: wrapAndBindImpl(instance, clear),
     paste: wrapAndBindImpl(instance, paste),
     scrollTo: wrapAndBindImpl(instance, scrollTo),
+    pullToRefresh: wrapAndBindImpl(instance, pullToRefresh),
     accessibilityAction: wrapAndBindImpl(instance, accessibilityAction),
   };