refactor: make fireEvent async by default

Author: mdjastrzebski

.gemini/settings.json

@@ -1,5 +1,5 @@
 {
   "context": {
-    "contextFileName": "AGENTS.md"    
+    "contextFileName": "AGENTS.md"
   }
-}
+}

AGENTS.md

@@ -6,43 +6,43 @@ This document provides context for the Gemini code assistant to understand the `
 
 `@testing-library/react-native` (RNTL) provides a set of utilities for testing React Native components. It is designed to facilitate writing tests that resemble how users interact with the application, avoiding implementation details.
 
-*   **Core Principle:** "The more your tests resemble the way your software is used, the more confidence they can give you."
-*   **Tech Stack:** TypeScript, React Native, Jest.
-*   **Architecture:** The library simulates the React Native runtime on top of `universal-test-renderer`.
+- **Core Principle:** "The more your tests resemble the way your software is used, the more confidence they can give you."
+- **Tech Stack:** TypeScript, React Native, Jest.
+- **Architecture:** The library simulates the React Native runtime on top of `universal-test-renderer`.
 
 ## Building and Running
 
 The project uses `yarn` for dependency management and script execution.
 
-*   **Installation:** `yarn install`
-*   **Run Tests:** `yarn test` (Runs Jest)
-*   **Run Tests (CI):** `yarn test:ci` (Runs Jest with worker limits)
-*   **Lint Code:** `yarn lint` (Runs ESLint on `src`)
-*   **Type Check:** `yarn typecheck` (Runs TypeScript compiler)
-*   **Format Check:** `yarn prettier`
-*   **Validate All:** `yarn validate` (Runs Prettier, ESLint, Typecheck, and Tests in sequence)
-*   **Build Project:** `yarn build` (Cleans, builds JS with Babel, builds TS types, and copies Flow types)
+- **Installation:** `yarn install`
+- **Run Tests:** `yarn test` (Runs Jest)
+- **Run Tests (CI):** `yarn test:ci` (Runs Jest with worker limits)
+- **Lint Code:** `yarn lint` (Runs ESLint on `src`)
+- **Type Check:** `yarn typecheck` (Runs TypeScript compiler)
+- **Format Check:** `yarn prettier`
+- **Validate All:** `yarn validate` (Runs Prettier, ESLint, Typecheck, and Tests in sequence)
+- **Build Project:** `yarn build` (Cleans, builds JS with Babel, builds TS types, and copies Flow types)
 
 ## Development Conventions
 
-*   **Code Style:**
-    *   **Linting:** ESLint is configured with `@callstack/eslint-config` and `typescript-eslint`. It enforces strict rules, including `no-console` and consistent type imports.
-    *   **Formatting:** Prettier is used for code formatting (single quotes, trailing commas).
-    *   **Imports:** Sorted using `eslint-plugin-simple-import-sort`.
-
-*   **Testing:**
-    *   **Framework:** Jest with `react-native` preset.
-    *   **Location:** Tests are located within `src`, typically in `__tests__` directories or co-located.
-    *   **Setup:** `jest-setup.ts` configures the test environment. `src/index.ts` automatically configures cleanup after each test unless skipped.
-    *   **Coverage:** Collected from `src`, excluding tests.
-
-*   **Commits & Releases:**
-    *   **Commits:** Follow the **Conventional Commits** specification (e.g., `fix:`, `feat:`, `chore:`). This is enforced and used for changelog generation.
-    *   **Releases:** Managed via `release-it`.
-
-*   **File Structure:**
-    *   `src/`: Source code.
-    *   `src/pure.ts`: Core logic without side effects (no auto-cleanup).
-    *   `src/index.ts`: Main entry point, re-exports `pure` and adds side effects (auto-cleanup).
-    *   `examples/`: Example React Native applications using the library.
-    *   `website/`: Documentation website.
+- **Code Style:**
+  - **Linting:** ESLint is configured with `@callstack/eslint-config` and `typescript-eslint`. It enforces strict rules, including `no-console` and consistent type imports.
+  - **Formatting:** Prettier is used for code formatting (single quotes, trailing commas).
+  - **Imports:** Sorted using `eslint-plugin-simple-import-sort`.
+
+- **Testing:**
+  - **Framework:** Jest with `react-native` preset.
+  - **Location:** Tests are located within `src`, typically in `__tests__` directories or co-located.
+  - **Setup:** `jest-setup.ts` configures the test environment. `src/index.ts` automatically configures cleanup after each test unless skipped.
+  - **Coverage:** Collected from `src`, excluding tests.
+
+- **Commits & Releases:**
+  - **Commits:** Follow the **Conventional Commits** specification (e.g., `fix:`, `feat:`, `chore:`). This is enforced and used for changelog generation.
+  - **Releases:** Managed via `release-it`.
+
+- **File Structure:**
+  - `src/`: Source code.
+  - `src/pure.ts`: Core logic without side effects (no auto-cleanup).
+  - `src/index.ts`: Main entry point, re-exports `pure` and adds side effects (auto-cleanup).
+  - `examples/`: Example React Native applications using the library.
+  - `website/`: Documentation website.

src/__tests__/wait-for.test.tsx

@@ -40,7 +40,7 @@ afterEach(() => {
 test('waits for element until it stops throwing', async () => {
   render(<BananaContainer />);
 
-  fireEvent.press(screen.getByText('Change freshness!'));
+  await fireEvent.press(screen.getByText('Change freshness!'));
 
   expect(screen.queryByText('Fresh')).toBeNull();
 
@@ -52,7 +52,7 @@ test('waits for element until it stops throwing', async () => {
 test('waits for element until timeout is met', async () => {
   render(<BananaContainer />);
 
-  fireEvent.press(screen.getByText('Change freshness!'));
+  await fireEvent.press(screen.getByText('Change freshness!'));
 
   await expect(waitFor(() => screen.getByText('Fresh'), { timeout: 100 })).rejects.toThrow();
 
@@ -65,7 +65,7 @@ test('waitFor defaults to asyncWaitTimeout config option', async () => {
   configure({ asyncUtilTimeout: 100 });
   render(<BananaContainer />);
 
-  fireEvent.press(screen.getByText('Change freshness!'));
+  await fireEvent.press(screen.getByText('Change freshness!'));
   await expect(waitFor(() => screen.getByText('Fresh'))).rejects.toThrow();
 
   // Async action ends after 300ms and we only waited 100ms, so we need to wait
@@ -77,7 +77,7 @@ test('waitFor timeout option takes precendence over `asyncWaitTimeout` config op
   configure({ asyncUtilTimeout: 2000 });
   render(<BananaContainer />);
 
-  fireEvent.press(screen.getByText('Change freshness!'));
+  await fireEvent.press(screen.getByText('Change freshness!'));
   await expect(waitFor(() => screen.getByText('Fresh'), { timeout: 100 })).rejects.toThrow();
 
   // Async action ends after 300ms and we only waited 100ms, so we need to wait
@@ -127,7 +127,7 @@ test('waits for async event with fireEvent', async () => {
   const spy = jest.fn();
   render(<Comp onPress={spy} />);
 
-  fireEvent.press(screen.getByText('Trigger'));
+  await fireEvent.press(screen.getByText('Trigger'));
 
   await waitFor(() => {
     expect(spy).toHaveBeenCalled();
@@ -140,7 +140,7 @@ test.each([false, true])(
     jest.useFakeTimers({ legacyFakeTimers });
     render(<BananaContainer />);
 
-    fireEvent.press(screen.getByText('Change freshness!'));
+    await fireEvent.press(screen.getByText('Change freshness!'));
     expect(screen.queryByText('Fresh')).toBeNull();
 
     jest.advanceTimersByTime(300);
@@ -305,7 +305,7 @@ test.each([
     await waitFor(() => screen.getByText('red'));
 
     // Check that the `onPress` callback is called with the already-updated value of `syncedColor`.
-    fireEvent.press(screen.getByText('Trigger'));
+    await fireEvent.press(screen.getByText('Trigger'));
     expect(onPress).toHaveBeenCalledWith('red');
   },
 );

src/fire-event.ts

@@ -226,4 +226,4 @@ function tryGetContentOffset(event: unknown): Point | null {
   }
 
   return null;
-}
+}

typings/index.flow.js

@@ -286,9 +286,21 @@ type FireEventFunction = (
   element: ReactTestInstance,
   eventName: string,
   ...data: Array<any>
-) => any;
+) => Promise<any>;
 
 type FireEventAPI = FireEventFunction & {
+  press: (element: ReactTestInstance, ...data: Array<any>) => Promise<any>,
+  changeText: (element: ReactTestInstance, ...data: Array<any>) => Promise<any>,
+  scroll: (element: ReactTestInstance, ...data: Array<any>) => Promise<any>,
+};
+
+type DeprecatedFireEventSyncFunction = (
+  element: ReactTestInstance,
+  eventName: string,
+  ...data: Array<any>
+) => any;
+
+type DeprecatedFireEventSyncAPI = DeprecatedFireEventSyncFunction & {
   press: (element: ReactTestInstance, ...data: Array<any>) => any,
   changeText: (element: ReactTestInstance, ...data: Array<any>) => any,
   scroll: (element: ReactTestInstance, ...data: Array<any>) => any,
@@ -325,6 +337,7 @@ declare module '@testing-library/react-native' {
 
   declare export var cleanup: () => void;
   declare export var fireEvent: FireEventAPI;
+  declare export var deprecated_fireEventSync: DeprecatedFireEventSyncAPI;
 
   declare export var waitFor: WaitForFunction;
 

website/docs/14.x/docs/api/events/fire-event.mdx

@@ -10,7 +10,11 @@ Use Fire Event for cases not supported by User Event and for triggering event ha
 :::
 
 ```ts
-function fireEvent(element: ReactTestInstance, eventName: string, ...data: unknown[]): Promise<unknown>;
+function fireEvent(
+  element: ReactTestInstance,
+  eventName: string,
+  ...data: unknown[]
+): Promise<unknown>;
 ```
 
 The `fireEvent` API allows you to trigger all kinds 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.
@@ -171,7 +175,11 @@ await fireEvent.scroll(screen.getByText('scroll-view'), eventData);
 ## `deprecated_fireEventSync` {#deprecated-fire-event-sync}
 
 ```ts
-function deprecated_fireEventSync(element: ReactTestInstance, eventName: string, ...data: unknown[]): void;
+function deprecated_fireEventSync(
+  element: ReactTestInstance,
+  eventName: string,
+  ...data: unknown[]
+): void;
 ```
 
 Synchronous version of `fireEvent`. Deprecated and will be removed in future versions.