From ee4d3d8b6d47c2ad075956424b9d190e47197a4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 8 Jan 2026 23:01:45 +0100 Subject: [PATCH 1/3] remove `update` alias to `rerender` --- .../__tests__/to-be-on-the-screen.test.tsx | 4 +- src/matchers/__tests__/to-be-visible.test.tsx | 6 +-- src/render.tsx | 1 - src/screen.ts | 1 - .../14.x/docs/advanced/understanding-act.mdx | 4 +- website/docs/14.x/docs/api/misc/other.mdx | 4 +- website/docs/14.x/docs/api/render.mdx | 2 +- website/docs/14.x/docs/api/screen.mdx | 2 - website/docs/14.x/docs/migration/v14.mdx | 52 ++++++++++++++++++- 9 files changed, 60 insertions(+), 16 deletions(-) diff --git a/src/matchers/__tests__/to-be-on-the-screen.test.tsx b/src/matchers/__tests__/to-be-on-the-screen.test.tsx index cc125c77e..dd044a178 100644 --- a/src/matchers/__tests__/to-be-on-the-screen.test.tsx +++ b/src/matchers/__tests__/to-be-on-the-screen.test.tsx @@ -13,7 +13,7 @@ test('toBeOnTheScreen() example test', async () => { const child = screen.getByTestId('child'); expect(child).toBeOnTheScreen(); - await screen.update(); + await screen.rerender(); expect(child).not.toBeOnTheScreen(); }); @@ -47,7 +47,7 @@ test('toBeOnTheScreen() on detached element', async () => { const element = screen.getByTestId('text'); // Next line will unmount the element, yet `element` variable will still hold reference to it. - await screen.update(); + await screen.rerender(); expect(element).toBeTruthy(); expect(element).not.toBeOnTheScreen(); diff --git a/src/matchers/__tests__/to-be-visible.test.tsx b/src/matchers/__tests__/to-be-visible.test.tsx index fc39e855f..93d8848a5 100644 --- a/src/matchers/__tests__/to-be-visible.test.tsx +++ b/src/matchers/__tests__/to-be-visible.test.tsx @@ -169,7 +169,7 @@ test('toBeVisible() on inaccessible view', async () => { const test = screen.getByTestId('test', { includeHiddenElements: true }); expect(test).not.toBeVisible(); - await screen.update(); + await screen.rerender(); expect(test).toBeVisible(); }); @@ -190,7 +190,7 @@ test('toBeVisible() on inaccessible view (iOS)', async () => { const test = screen.getByTestId('test', { includeHiddenElements: true }); expect(test).not.toBeVisible(); - await screen.update(); + await screen.rerender(); expect(test).toBeVisible(); }); @@ -211,7 +211,7 @@ test('toBeVisible() on inaccessible view (Android)', async () => { const test = screen.getByTestId('test', { includeHiddenElements: true }); expect(test).not.toBeVisible(); - await screen.update(); + await screen.rerender(); expect(test).toBeVisible(); }); diff --git a/src/render.tsx b/src/render.tsx index fefc00058..aa726172e 100644 --- a/src/render.tsx +++ b/src/render.tsx @@ -81,7 +81,6 @@ export async function render(element: React.ReactElement, options: RenderO const result = { ...getQueriesForElement(renderer.container), rerender, - update: rerender, // alias for `rerender` unmount, toJSON, debug: makeDebug(renderer), diff --git a/src/screen.ts b/src/screen.ts index 9a389acde..8b39601b8 100644 --- a/src/screen.ts +++ b/src/screen.ts @@ -22,7 +22,6 @@ const defaultScreen: Screen = { }, debug: notImplemented, rerender: notImplemented, - update: notImplemented, unmount: notImplemented, toJSON: notImplemented, getByLabelText: notImplemented, diff --git a/website/docs/14.x/docs/advanced/understanding-act.mdx b/website/docs/14.x/docs/advanced/understanding-act.mdx index 3fd346fe4..c1ae6f422 100644 --- a/website/docs/14.x/docs/advanced/understanding-act.mdx +++ b/website/docs/14.x/docs/advanced/understanding-act.mdx @@ -86,10 +86,10 @@ So far we learned that `act` function allows tests to wait for all pending React Therefore, we should use `act` whenever there is some action that causes element tree to render, particularly: - initial render call - `ReactTestRenderer.create` call -- re-rendering of component -`renderer.update` call +- re-rendering of component -`renderer.rerender` call - triggering any event handlers that cause component tree render -Thankfully, for these basic cases RNTL has got you covered as our `render`, `update` and `fireEvent` methods already wrap their calls in `act` so that you do not have to do it explicitly. +Thankfully, for these basic cases RNTL has got you covered as our `render`, `rerender` and `fireEvent` methods already wrap their calls in `act` so that you do not have to do it explicitly. Note that `act` calls can be safely nested and internally form a stack of calls. However, overlapping `act` calls, which can be achieved using async version of `act`, [are not supported](https://github.com/facebook/react/blob/main/packages/react/src/ReactAct.js#L161). diff --git a/website/docs/14.x/docs/api/misc/other.mdx b/website/docs/14.x/docs/api/misc/other.mdx index 24c808049..c08dd0777 100644 --- a/website/docs/14.x/docs/api/misc/other.mdx +++ b/website/docs/14.x/docs/api/misc/other.mdx @@ -11,7 +11,7 @@ function getQueriesForElement(element: HostElement): Queries {} `within` (also available as `getQueriesForElement` alias) performs [queries](docs/api/queries) scoped to given element. :::note -Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included. +Please note that additional `render` specific operations like `rerender`, `unmount`, `debug`, `toJSON` are _not_ included. ::: ```jsx @@ -33,7 +33,7 @@ Use cases for scoped queries include: function act(callback: () => T | Promise): Promise; ``` -Useful function to help testing components that use hooks API. By default any `render`, `update`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. +Useful function to help testing components that use hooks API. By default any `render`, `rerender`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. **In v14, `act` is now async by default and always returns a Promise**, making it compatible with React 19, React Suspense, and `React.use()`. This ensures all pending React updates are executed before the Promise resolves. diff --git a/website/docs/14.x/docs/api/render.mdx b/website/docs/14.x/docs/api/render.mdx index 5dd514c3e..9f7fa232e 100644 --- a/website/docs/14.x/docs/api/render.mdx +++ b/website/docs/14.x/docs/api/render.mdx @@ -63,6 +63,6 @@ See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testin :::warning Async lifecycle methods -When using `render`, the lifecycle methods `rerender`, `update`, and `unmount` are async and must be awaited. +When using `render`, the lifecycle methods `rerender` and `unmount` are async and must be awaited. ::: diff --git a/website/docs/14.x/docs/api/screen.mdx b/website/docs/14.x/docs/api/screen.mdx index 62dca9972..5a419f715 100644 --- a/website/docs/14.x/docs/api/screen.mdx +++ b/website/docs/14.x/docs/api/screen.mdx @@ -35,8 +35,6 @@ test('example', async () => { ### `rerender` -_Also available under `update` alias_ - ```ts function rerender(element: React.Element): Promise; ``` diff --git a/website/docs/14.x/docs/migration/v14.mdx b/website/docs/14.x/docs/migration/v14.mdx index 71aef82c6..758c6e3e3 100644 --- a/website/docs/14.x/docs/migration/v14.mdx +++ b/website/docs/14.x/docs/migration/v14.mdx @@ -163,7 +163,25 @@ screen.rerender(); await screen.rerender(); ``` -##### 4. Update `unmount` calls to await +##### 4. Replace `update` alias with `rerender` + +The `update` alias for `rerender` has been removed in v14. If you were using `screen.update()` or `renderer.update()`, replace it with `rerender()`: + +```ts +// Before (v13) +screen.update(); +// or +const { update } = render(); +update(); + +// After (v14) +await screen.rerender(); +// or +const { rerender } = await render(); +await rerender(); +``` + +##### 5. Update `unmount` calls to await ```ts // Before @@ -216,6 +234,36 @@ it('should update component', async () => { For more details, see the [`render` API documentation](/docs/api/render). +### `update` alias removed + +In v14, the `update` alias for `rerender` has been removed. You must use `rerender` instead. + +**What changed:** + +- `screen.update()` has been removed +- `renderer.update()` has been removed +- Only `rerender` is now available + +**Migration:** + +Replace all `update` calls with `rerender`: + +```ts +// Before (v13) +screen.update(); +// or +const { update } = render(); +update(); + +// After (v14) +await screen.rerender(); +// or +const { rerender } = await render(); +await rerender(); +``` + +**Note:** This change is included in the step-by-step migration guide for async `render` above. + ### `renderHook` is now async by default In v14, `renderHook` is now async by default and returns a Promise. This change makes it compatible with React 19, React Suspense, and `React.use()`. @@ -290,7 +338,7 @@ unmount(); await unmount(); ``` -##### 5. Update `act` calls to use async `act` +##### 6. Update `act` calls to use async `act` ```ts // Before From 082e75b8efa7d587704a6dfa141caee45ac360b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 8 Jan 2026 23:03:54 +0100 Subject: [PATCH 2/3] refactor: remove `getQueriesForElement` alias --- src/__tests__/within.test.tsx | 5 +--- src/pure.ts | 2 +- website/docs/14.x/docs/api/misc/other.mdx | 6 ++--- website/docs/14.x/docs/migration/v14.mdx | 28 +++++++++++++++++++++++ 4 files changed, 32 insertions(+), 9 deletions(-) diff --git a/src/__tests__/within.test.tsx b/src/__tests__/within.test.tsx index bd6889d99..8ad2ac386 100644 --- a/src/__tests__/within.test.tsx +++ b/src/__tests__/within.test.tsx @@ -1,7 +1,7 @@ import * as React from 'react'; import { Text, TextInput, View } from 'react-native'; -import { getQueriesForElement, render, within } from '..'; +import { render, within } from '..'; test('within() exposes basic queries', async () => { const rootQueries = await render( @@ -80,6 +80,3 @@ test('within() exposes a11y queries', async () => { await expect(secondQueries.findAllByA11yHint('Same Hint')).resolves.toHaveLength(1); }); -test('getQueriesForElement is alias to within', () => { - expect(getQueriesForElement).toBe(within); -}); diff --git a/src/pure.ts b/src/pure.ts index cdc62704c..f74996bc7 100644 --- a/src/pure.ts +++ b/src/pure.ts @@ -4,7 +4,7 @@ export { fireEvent } from './fire-event'; export { render } from './render'; export { waitFor } from './wait-for'; export { waitForElementToBeRemoved } from './wait-for-element-to-be-removed'; -export { within, getQueriesForElement } from './within'; +export { within } from './within'; export { configure, resetToDefaults } from './config'; export { isHiddenFromAccessibility, isInaccessible } from './helpers/accessibility'; diff --git a/website/docs/14.x/docs/api/misc/other.mdx b/website/docs/14.x/docs/api/misc/other.mdx index c08dd0777..b16dd1ff0 100644 --- a/website/docs/14.x/docs/api/misc/other.mdx +++ b/website/docs/14.x/docs/api/misc/other.mdx @@ -1,14 +1,12 @@ # Other helpers -## `within`, `getQueriesForElement` {#within} +## `within` {#within} ```jsx function within(element: HostElement): Queries {} - -function getQueriesForElement(element: HostElement): Queries {} ``` -`within` (also available as `getQueriesForElement` alias) performs [queries](docs/api/queries) scoped to given element. +`within` performs [queries](docs/api/queries) scoped to given element. :::note Please note that additional `render` specific operations like `rerender`, `unmount`, `debug`, `toJSON` are _not_ included. diff --git a/website/docs/14.x/docs/migration/v14.mdx b/website/docs/14.x/docs/migration/v14.mdx index 758c6e3e3..470da3b2a 100644 --- a/website/docs/14.x/docs/migration/v14.mdx +++ b/website/docs/14.x/docs/migration/v14.mdx @@ -264,6 +264,34 @@ await rerender(); **Note:** This change is included in the step-by-step migration guide for async `render` above. +### `getQueriesForElement` export removed + +In v14, the `getQueriesForElement` export alias for `within` has been removed. You must use `within` instead. + +**What changed:** + +- `getQueriesForElement` is no longer exported from the main package +- `within` is the only exported function for scoped queries +- `getQueriesForElement` remains available internally but is not part of the public API + +**Migration:** + +Replace all `getQueriesForElement` imports and usage with `within`: + +```ts +// Before (v13) +import { getQueriesForElement } from '@testing-library/react-native'; + +const queries = getQueriesForElement(element); + +// After (v14) +import { within } from '@testing-library/react-native'; + +const queries = within(element); +``` + +**Note:** `getQueriesForElement` was just an alias for `within`, so the functionality is identical - only the import needs to change. + ### `renderHook` is now async by default In v14, `renderHook` is now async by default and returns a Promise. This change makes it compatible with React 19, React Suspense, and `React.use()`. From bba54219a89fd8991257eaf6429ef420675b9638 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= Date: Thu, 8 Jan 2026 23:09:23 +0100 Subject: [PATCH 3/3] . --- src/__tests__/within.test.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/__tests__/within.test.tsx b/src/__tests__/within.test.tsx index 8ad2ac386..e2fffc11d 100644 --- a/src/__tests__/within.test.tsx +++ b/src/__tests__/within.test.tsx @@ -79,4 +79,3 @@ test('within() exposes a11y queries', async () => { await expect(secondQueries.findAllByLabelText('Same Label')).resolves.toHaveLength(1); await expect(secondQueries.findAllByA11yHint('Same Hint')).resolves.toHaveLength(1); }); -