rest of the docs

Author: mdjastrzebski

README-v13.md

@@ -14,11 +14,11 @@
 
 ## The problem
 
-You want to write maintainable tests for your React Native components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your tests to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.
+You want to write maintainable tests for your React Native components. Your tests should avoid implementation details and focus on giving you confidence. They should remain maintainable so refactors (changes to implementation but not functionality) don't break your tests and slow you and your team down.
 
 ## This solution
 
-The React Native Testing Library (RNTL) is a comprehensive solution for testing React Native components. It provides React Native runtime simulation on top of `react-test-renderer`, in a way that encourages better testing practices. Its primary guiding principle is:
+The React Native Testing Library (RNTL) tests React Native components. It simulates the React Native runtime on top of `react-test-renderer` and encourages better testing practices. Its primary guiding principle is:
 
 > The more your tests resemble the way your software is used, the more confidence they can give you.
 
@@ -48,8 +48,8 @@ You can use the built-in Jest matchers automatically by having any import from `
 import { render, screen, userEvent } from '@testing-library/react-native';
 import { QuestionsBoard } from '../QuestionsBoard';
 
-// It is recommended to use userEvent with fake timers
-// Some events involve duration so your tests may take a long time to run.
+// Use userEvent with fake timers
+// Some events involve duration, so tests may take a long time to run.
 jest.useFakeTimers();
 
 test('form submits two answers', async () => {
@@ -87,8 +87,8 @@ React Native Testing Library consists of following APIs:
   - Lifecycle methods: [`rerender`](https://callstack.github.io/react-native-testing-library/docs/api/screen#rerender), [`unmount`](https://callstack.github.io/react-native-testing-library/docs/api/screen#unmount)
   - Helpers: [`debug`](https://callstack.github.io/react-native-testing-library/docs/api/screen#debug), [`toJSON`](https://callstack.github.io/react-native-testing-library/docs/api/screen#tojson), [`root`](https://callstack.github.io/react-native-testing-library/docs/api/screen#root)
 - [Jest matchers](https://callstack.github.io/react-native-testing-library/docs/api/jest-matchers) - validate assumptions about your UI
-- [User Event](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event) - simulate common user interactions like [`press`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#press) or [`type`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#type) in a realistic way
-- [Fire Event](https://callstack.github.io/react-native-testing-library/docs/api/events/fire-event) - simulate any component event in a simplified way
+- [User Event](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event) - simulate common user interactions like [`press`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#press) or [`type`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#type)
+- [Fire Event](https://callstack.github.io/react-native-testing-library/docs/api/events/fire-event) - simulate any component event
 - [`renderHook` function](https://callstack.github.io/react-native-testing-library/docs/api/misc/render-hook) - render hooks for testing purposes
 - Miscellaneous APIs:
   - [Async utils](https://callstack.github.io/react-native-testing-library/docs/api/misc/async): `findBy*` queries, `waitFor`, `waitForElementToBeRemoved`

README.md

@@ -19,11 +19,11 @@
 
 ## The problem
 
-You want to write maintainable tests for your React Native components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your tests to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.
+You want to write maintainable tests for your React Native components. Your tests should avoid implementation details and focus on giving you confidence. They should remain maintainable so refactors (changes to implementation but not functionality) don't break your tests and slow you and your team down.
 
 ## This solution
 
-The React Native Testing Library (RNTL) is a comprehensive solution for testing React Native components. It provides React Native runtime simulation on top of `test-renderer`, in a way that encourages better testing practices. Its primary guiding principle is:
+The React Native Testing Library (RNTL) tests React Native components. It simulates the React Native runtime on top of [Test Renderer](https://github.com/mdjastrzebski/test-renderer) and encourages better testing practices. Its primary guiding principle is:
 
 > The more your tests resemble the way your software is used, the more confidence they can give you.
 
@@ -34,20 +34,12 @@ This project is inspired by [React Testing Library](https://github.com/testing-l
 Open a Terminal in your project's folder and run:
 
 ```sh
-# Yarn install:
-yarn add --dev @testing-library/react-native@alpha
-
-# NPM install
 npm install --save-dev @testing-library/react-native@alpha
 ```
 
 This library has a `peerDependencies` listing for [Test Renderer](https://github.com/mdjastrzebski/test-renderer). Make sure to install it as a dev dependency:
 
 ```sh
-# Yarn install:
-yarn add --dev test-renderer
-
-# NPM install
 npm install --save-dev test-renderer
 ```
 
@@ -61,10 +53,6 @@ You can use the built-in Jest matchers automatically by having any import from `
 import { render, screen, userEvent } from '@testing-library/react-native';
 import { QuestionsBoard } from '../QuestionsBoard';
 
-// It is recommended to use userEvent with fake timers
-// Some events involve duration so your tests may take a long time to run.
-jest.useFakeTimers();
-
 test('form submits two answers', async () => {
   const questions = ['q1', 'q2'];
   const onSubmit = jest.fn();
@@ -100,8 +88,8 @@ React Native Testing Library consists of following APIs:
   - Lifecycle methods: [`rerender`](https://callstack.github.io/react-native-testing-library/docs/api/screen#rerender), [`unmount`](https://callstack.github.io/react-native-testing-library/docs/api/screen#unmount)
   - Helpers: [`debug`](https://callstack.github.io/react-native-testing-library/docs/api/screen#debug), [`toJSON`](https://callstack.github.io/react-native-testing-library/docs/api/screen#tojson), [`root`](https://callstack.github.io/react-native-testing-library/docs/api/screen#root), [`container`](https://callstack.github.io/react-native-testing-library/docs/api/screen#container)
 - [Jest matchers](https://callstack.github.io/react-native-testing-library/docs/api/jest-matchers) - validate assumptions about your UI
-- [User Event](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event) - simulate common user interactions like [`press`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#press) or [`type`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#type) in a realistic way
-- [Fire Event](https://callstack.github.io/react-native-testing-library/docs/api/events/fire-event) - simulate any component event in a simplified way
+- [User Event](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event) - simulate common user interactions like [`press`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#press) or [`type`](https://callstack.github.io/react-native-testing-library/docs/api/events/user-event#type)
+- [Fire Event](https://callstack.github.io/react-native-testing-library/docs/api/events/fire-event) - simulate any component event
 - [`renderHook` function](https://callstack.github.io/react-native-testing-library/docs/api/misc/render-hook) - render hooks for testing purposes
 - Miscellaneous APIs:
   - [Async utils](https://callstack.github.io/react-native-testing-library/docs/api/misc/async): `findBy*` queries, `waitFor`, `waitForElementToBeRemoved`
@@ -112,8 +100,6 @@ React Native Testing Library consists of following APIs:
 ## Migration Guides
 
 - **[Migration to 14.0](https://callstack.github.io/react-native-testing-library/docs/migration/v14)** - Drops React 18, async APIs by default
-- [Migration to 13.0](https://callstack.github.io/react-native-testing-library/docs/migration/v13)
-- [Migration to built-in Jest Matchers](https://callstack.github.io/react-native-testing-library/docs/migration/jest-matchers)
 
 ## Troubleshooting
 

website/docs/14.x/docs/advanced/testing-env.mdx

@@ -6,7 +6,7 @@ This document is intended for a more advanced audience who want to understand th
 
 :::
 
-React Native Testing Library allows you to write integration and component tests for your React Native app or library. While the JSX code used in tests closely resembles your React Native app, things are not as simple as they might appear. This document will describe the key elements of our testing environment and highlight things to be aware of when writing more advanced tests or diagnosing issues.
+React Native Testing Library lets you write integration and component tests for your React Native app or library. While the JSX code in tests closely resembles your React Native app, the underlying environment differs. This document describes the key elements of our testing environment and highlights things to be aware of when writing advanced tests or diagnosing issues.
 
 ## React renderers
 
@@ -20,21 +20,19 @@ When you run your tests in the React Native Testing Library, somewhat contrary t
 
 ## Test Renderer
 
-Instead, RNTL uses [Test Renderer](https://github.com/mdjastrzebski/test-renderer), a modern, actively maintained renderer that allows rendering to pure JavaScript objects without access to mobile OS and can run in a Node.js environment using Jest (or any other JavaScript test runner). Test Renderer replaces the deprecated `react-test-renderer` package and provides better compatibility with React 19 and improved type safety.
+Instead, RNTL uses [Test Renderer](https://github.com/mdjastrzebski/test-renderer), a modern, actively maintained renderer that renders to pure JavaScript objects without access to mobile OS and runs in a Node.js environment using Jest (or any other JavaScript test runner). Test Renderer replaces the deprecated `react-test-renderer` package and has better compatibility with React 19 and improved type safety.
 
-Using Test Renderer has pros and cons.
+Using Test Renderer has trade-offs:
 
 Benefits:
-
-- tests can run on most CIs (Linux, etc) and do not require a mobile device or emulator
-- faster test execution
-- light runtime environment
-
-Disadvantages:
-
-- Tests do not execute native code
-- Tests are unaware of the view state that would be managed by native components, e.g., focus, unmanaged text boxes, etc.
-- Assertions do not operate on native view hierarchy
+- Tests run on most CIs (Linux, etc) without a mobile device or emulator
+- Faster test execution
+- Light runtime environment
+
+Limitations:
+- Tests don't execute native code
+- Tests are unaware of view state managed by native components, e.g., focus, unmanaged text boxes, etc.
+- Assertions don't operate on native view hierarchy
 - Runtime behaviors are simulated, sometimes imperfectly
 
 It's worth noting that the React Testing Library (web one) works a bit differently. While RTL also runs in Jest, it has access to a simulated browser DOM environment from the `jsdom` package, which allows it to use a regular React DOM renderer. Unfortunately, there is no similar React Native runtime environment package. This is probably because while the browser environment is well-defined and highly standardized, the React Native environment constantly evolves in sync with the evolution of underlying OS-es. Maintaining such an environment would require duplicating countless React Native behaviors and keeping them in sync as React Native develops.
@@ -90,13 +88,13 @@ Not all React Native components are organized this way, e.g., when you use `Pres
 
 ### Host-only element tree
 
-In RNTL v14, [Test Renderer](https://github.com/mdjastrzebski/test-renderer) only exposes host elements in the element tree. Composite components are not visible in the tree - you only see their host element output. This is an intentional design choice that aligns with Testing Library's philosophy: tests should focus on what users can see and interact with (host elements), not on implementation details (composite components).
+In RNTL v14, [Test Renderer](https://github.com/mdjastrzebski/test-renderer) only exposes host elements in the element tree. Composite components aren't visible in the tree—you only see their host element output. This aligns with Testing Library's philosophy: tests should focus on what users can see and interact with (host elements), not implementation details (composite components).
 
 For a `HostElement`, the `type` prop is always a string value representing the host component name, e.g., `"View"`, `"Text"`, `"TextInput"`.
 
 ## Tree nodes
 
-RNTL v14 queries and the element tree only expose host elements. This aligns with Testing Library's philosophy: tests should assert on what users can see and interact with. Host elements represent the actual UI controls that users interact with, while composite components exist purely in the JavaScript domain.
+RNTL v14 queries and the element tree only expose host elements. Tests assert on what users can see and interact with. Host elements represent the actual UI controls users interact with, while composite components exist purely in the JavaScript domain.
 
 ### Understanding props
 

website/docs/14.x/docs/advanced/understanding-act.mdx

@@ -1,6 +1,6 @@
 # Understanding `act` function
 
-When writing RNTL tests one of the things that confuses developers the most are cryptic [`act()`](https://react.dev/link/wrap-tests-with-act) function errors logged into console. In this article I will try to build an understanding of the purpose and behaviour of `act()` so you can build your tests with more confidence.
+When writing RNTL tests, cryptic [`act()`](https://react.dev/link/wrap-tests-with-act) function errors logged to console often confuse developers. This article explains the purpose and behavior of `act()` so you can write tests with more confidence.
 
 ## `act` warning
 
@@ -28,7 +28,7 @@ This function is intended only for using in automated tests and works only in de
 
 The responsibility for `act` function is to make React renders and updates work in tests in a similar way they work in real application by grouping and executing related units of interaction (e.g. renders, effects, etc) together.
 
-To showcase that behaviour let make a small experiment. First we define a function component that uses `useEffect` hook in a trivial way.
+Let's demonstrate this with a small experiment. First, define a function component that uses `useEffect`:
 
 ```jsx
 function TestComponent() {
@@ -57,7 +57,7 @@ test('render without act', () => {
 });
 ```
 
-When testing without `act` call wrapping rendering call, we see that the assertion runs just after the rendering but before `useEffect` hooks effects are applied. Which is not what we expected in our tests.
+When testing without `act` wrapping the render call, the assertion runs just after rendering but before `useEffect` effects are applied. This isn't what we expected.
 
 ```jsx
 import { createRoot } from 'test-renderer';
@@ -99,7 +99,7 @@ Note that `act` calls can be safely nested and internally form a stack of calls.
 
 The `act` implementation is defined in the [ReactAct.js source file](https://github.com/facebook/react/blob/main/packages/react/src/ReactAct.js) inside React repository. RNTL v14 requires React 19+, which provides the `act` function directly via `React.act`.
 
-RNTL exports `act` for convenience of the users as defined in the [act.ts source file](https://github.com/callstack/react-native-testing-library/blob/main/src/act.ts). In v14, `act` is now async by default and always returns a Promise, making it compatible with async React features like `Suspense` boundary or `use()` hook. The underlying implementation wraps React's `act` function to ensure consistent async behavior.
+RNTL exports `act` for convenience as defined in the [act.ts source file](https://github.com/callstack/react-native-testing-library/blob/main/src/act.ts). In v14, `act` is async by default and always returns a Promise. This works with async React features like `Suspense` boundaries and the `use()` hook. The underlying implementation wraps React's `act` function to ensure consistent async behavior.
 
 **Important**: You should always use `act` exported from `@testing-library/react-native` rather than the one from `react`. The RNTL version automatically ensures async behavior, whereas using `React.act` directly could still trigger synchronous act behavior if used improperly, leading to subtle test issues.
 
@@ -111,7 +111,7 @@ In v14, `act` is always async and returns a Promise. While the callback you pass
 
 When the callback passed to `act` contains asynchronous operations, the Promise returned by `act` will resolve only after those operations complete.
 
-Lets look at a simple example with component using `setTimeout` call to simulate asynchronous behaviour:
+Here's a simple example with a component using `setTimeout` to simulate asynchronous behavior:
 
 ```jsx
 function TestAsyncComponent() {
@@ -139,7 +139,7 @@ If we test our component in a native way without handling its asynchronous behav
 
 ### Solution with fake timers
 
-First solution is to use Jest's fake timers inside out tests:
+Use Jest's fake timers:
 
 ```jsx
 test('render with fake timers', async () => {
@@ -159,7 +159,7 @@ That way we can wrap `jest.runAllTimers()` call which triggers the `setTimeout`
 
 ### Solution with real timers
 
-If we wanted to stick with real timers then things get a bit more complex. Let's start by applying a crude solution of opening async `act()` call for the expected duration of components updates:
+With real timers, things get more complex. Start with a simple solution: wrap an async `act()` call for the expected duration of component updates:
 
 ```jsx
 test('render with real timers - sleep', async () => {
@@ -174,7 +174,7 @@ test('render with real timers - sleep', async () => {
 
 This works correctly as we use an explicit async `act()` call that resolves the console error. However, it relies on our knowledge of exact implementation details which is a bad practice.
 
-Let's try more elegant solution using `waitFor` that will wait for our desired state:
+A better solution uses `waitFor` to wait for the desired state:
 
 ```jsx
 test('render with real timers - waitFor', async () => {