RNTL v13 & v14 roadmap

[mdjastrzebski]

I wanted to share some details about future plans for the React Native Testing Library, especially in the context of the React Test Renderer (RTR) being deprecated. We plan to replace RTR with a new test renderer, for which I’ve already built a prototype that validated this approach.

Here is the RNTL major release roadmap:

• v12 (current version)
• Supports React 16, 17, & 18
• Might work with React 19 (not a goal)
• v13 (Q4 2024)
  • Supports React 18 & 19 only, drops support for 16 & 17
  • Uses React Test Renderer
  • Drops deprecated features (*ByA11State, *ByA11Queries, etc.)
  • Relatively smooth migration
• v14 (H1 2025)
  • Supports React 19+
  • Uses new test renderer
  • Changes around Fire Event API event handling that might break some code

There is no urgency in replacing RTR as it’s still present in React 19, although with some deprecation warnings.

The new test renderer will operate only on host components. In general, this is the desired state, as we already limit RNTL to this. One area where this will impact users is the ability to directly call event handlers on composite components using the Fire Event API. Current RNTL allows this for legacy test reasons, but it will no longer be possible with the new renderer. We will provide an easy migration to v14 for common events like press though.

[mdjastrzebski]

CC: @thymikee@pierrezimmermannbam@MattAgn@AugustinLF

[pierrezimmermannbam]

This sounds like a good plan!

Regarding V13, you already did pretty much everything right? Besides reviewing and merging #1607 and waiting for RN 0.77 there is nothing else to do, correct?

[pierrezimmermannbam]

Regarding the focus management it's not really clear to me what tracking focus with native state would enable, do you have some examples?

I very much agree that solving the issue with refs would be a very good improvement to RN and it should probably done no matter what we do on focus management

[mdjastrzebski]

@pierrezimmermannbam send more info on the failing tests, is it v13 or v14 failing? How does it compare to v12 with concurrentRoot option set to true?

[mdjastrzebski]

re focus tracking: that would be rather marginal update, and leveling-up how RTL/Jest DOM works. We could maintain WebAPI-like activeElement, probably as screen.activeElement or similar. That way we could track the current active element, whether change came with default event behavior or from user components calling ref.focus() in event handlers / effects. Then we could have reliably implement toHaveFocus() matcher and enable users testing focus state.

[pierrezimmermannbam]

I'm testing v13-alpha right now, the issues come from concurrentRoot option, if I disable it then it works fine. There are some subtle differences in how suspense works it seems. I managed to fix most of my issues but now I have flaky tests, I need to investigate more to understand what the problem is but it's not related to RNTL probably. I'll try the beta then

[mdjastrzebski]

@pierrezimmermannbam I've released v14-alpha using new test renderer that I've wrote (universal-test-renderer). It might be somewhat more difficult to check your tests against it. But I am curious about any feedback. This is not urgent, as v13 is still going to happen earlier.
Edit: currently it requires React 19, which might actually prevent you from testing it, util RN 0.77 comes which should use R19.

[ntucker]

Is this supposed to be compatible with react 19 and react-test-renderer@19? I'm using react-native@0.78.0-nightly-20250108-ec72af403, which is the first one that lists react 19 as a peerDep, and I'm getting an error when using renderHook:

Can't access .root on unmounted test renderer

This works when using RN@77 and react@18.3 and @testing-library/react-native@13

[mdjastrzebski]

@ntucker v13 should work with React 19. We have a PR for testing that RNTL works with React 19 + RN nightly: #1723

Could you provide a minimal reproduction repo so I could investigate your issue?

[edkimmel]

For v14, can we loosen the restrictions on text elements when running tests configured as web? e.g. using the jest-expo/web preset? Text is valid in span/div there, and libraries such as @expo/html-elements and react-strict-dom do so while being compatible with native.

[mdjastrzebski]

The RNTL codebase is not just about queries; it also contains a significant amount of logic that simulates iOS and Android runtime behaviors. When it comes to testing React Native Web apps, using the regular React Testing Library (RTL) is a better fit. It provides a much more realistic browser execution environment. Attempting to add React Native Web simulation to RNTL would result in a lower-quality experience compared to what RTL already offers.

The main downside of this approach is the need for test code duplication. Ultimately, the decision to test web separately or to rely solely on base iOS/Android testing is up to the users. They need to weigh the cost and benefits of such a decision.

One potential solution could be a wrapper library that bridges RNTL and RTL queries into a single API. I reached out to various RN community circles, including Expo, to gauge interest in such a library, but there was little interest.

[rafaelpadovanirain]

A big amount of tests started failing in our react native project after the upgrade. Tried v14.0.0-alpha.1 and even more tests started failing. The same project works perfectly fine with react v18.3.1.

[Noitham]

We're in the same situation here.
Did you find any solution @rafaelpadovanirain ?

[mdjastrzebski]

@rafaelpadovanirain, @Noitham RNTL 12 & 13 are pretty similar. The main difference is the default value for concurrentRoot, try setting it globally to false using configure({ concurrentRoot: false }) in your jest-setup.ts. Be aware that with React 19 this setting is mandatory, so you will have to review and fix your tests.

DO NOT USE RNTL v14 ALPHA, this will definitely not work and it's not supported.

BTW could you post more info about errors you are getting?

See also:

• this discussion
• v13 Migration Guide

[mdjastrzebski]

@rafaelpadovanirain, @Noitham I've just released RNTL v13.3 (beta) with React Suspense support. 🎉 It adds renderAsync, fireEventAsync, screen.rerenderAsync, etc variants that should work correctly with React Suspense.

Could you test it on your React Suspense code and report back if it works correctly?