In React Native Testing Library 14, how do you give every rendered survey screen its providers, and what does the render wrapper option do that inline wrapping does not?

## The problem a wrapper solves A survey screen in a React Native app rarely renders on its own. It reads the current survey from a `SurveyProvider`, colours from a theme context, and perhaps a query client or a store. Rendering `<SurveyScreen />` bare in a test either throws ("useSurvey must be used within SurveyProvider") or renders a default, meaningless state. **React Native Testing Library (RNTL)** offers two ways to supply providers: wrap the element yourself, or pass a `wrapper` option to `render`. Both render the same tree the first time. They differ on every update after that. ## The `wrapper` option ```tsx await render(<SurveyScreen surveyId="s1" />, { wrapper: AppProviders }); ``` `wrapper` is a **component type**, not an element. RNTL renders `<AppProviders><SurveyScreen surveyId="s1" /></AppProviders>`. It keeps the wrapper and applies it again whenever the test calls `rerender`: ```tsx const { rerender } = await render(<SurveyScreen surveyId="s1" />, { wrapper: AppProviders }); await rerender(<SurveyScreen surveyId="s2" />); // still inside AppProviders ``` With inline wrapping, `rerender` receives only what you pass it. Writing `await rerender(<SurveyScreen surveyId="s2" />)` after an inline-wrapped `render` replaces the whole tree, so the providers disappear and the screen loses its context. You would have to repeat the providers on every `rerender`. ## A custom render function Most suites wrap this in one helper so tests stay short and consistent: 1. Define a providers component that accepts per-test options (initial survey, theme, logged-in user). 2. Create an `async` function that calls `render` with `wrapper` set. 3. `return await render(...)` so callers receive the same result as a normal `render`. 4. Export it from a test-utils module and use it instead of `render`. ```tsx export async function renderWithProviders( ui: React.ReactElement, { survey = sampleSurvey, theme = 'light' }: ProviderOptions = {}, ) { function Providers({ children }: { children: React.ReactNode }) { return ( <ThemeProvider value={theme}> <SurveyProvider initialSurvey={survey}>{children}</SurveyProvider> </ThemeProvider> ); } return await render(ui, { wrapper: Providers }); } ``` Since RNTL 14, `render` returns a Promise; a helper that forgets `async`/`await` hands tests an unresolved promise, and queries run before the screen mounts. ## Choosing between the approaches | Approach | Providers kept on `rerender` | Per-test options | Best for | |---|---|---|---| | Inline JSX in the test | no, unless repeated | yes, by editing JSX | one-off tests | | `wrapper` option | yes | via a closure or factory | tests that rerender | | Custom render helper using `wrapper` | yes | yes, as function arguments | whole suites | ## Several helpers, not one The RNTL cookbook suggests more than one custom render function when tests differ in scope: for example a `renderScreen` that mounts a single survey screen with its data providers, and a `renderNavigator` that mounts the navigation stack for flow tests such as "answer three questions, then see the summary". Each keeps its own wrapper, so a screen test does not pay for a navigator it does not use. The helpers can also accept a starting state, such as a half-completed survey, which keeps the setup of each test visible at the call site rather than hidden in a shared `beforeEach`. ## Migration notes - The `rntl-v14-async-functions` codemod only updates calls to helpers you list with `--param customRenderFunctions="renderWithProviders"`; otherwise call sites keep a missing `await`. - `render` now warns on unknown options, so a v13 helper still forwarding `concurrentRoot` or `createNodeMock` shows up in the output. - Keep the providers component stable where possible. Defining `Providers` inside the helper, as above, is fine because it is created once per `render` call and reused for that test's rerenders. ## Pitfalls - Passing an element instead of a component: `wrapper: <AppProviders />` is not a component type. - Putting a whole navigation container and every global provider into every test, which slows the suite and hides what a screen really depends on; give the helper options for what varies. - Relying on providers with global singletons (a store created at module load) without resetting them between tests, which leaks state from one survey test into the next.