Merge of React Native Testing Libraries

Today we’re happy to announce that the days of having two (yes, two) React Native Testing Libraries are finally over. We’re merging these libraries together and we couldn’t be happier about what’s next!

We renamed the <rte-code>react-native-testing-library<rte-code> npm package to <rte-code>@testing-library/react-native<rte-code>, joining the “Testing Library” family but keeping the source code and documentation.

What's the story behind that merge?

As part of The React Native Show, we released a podcast fully dedicated to future of React Native Testing Library. 

Historical background

The idea of a generic testing library for React Native dates back to September 2018, when we were working on improving the test suite for one of Callstack’s clients. Our team was fed up with how developers used Enzyme, and how it rendered native components into a web-like environment with lots of custom mocks if you needed to render components deeply. And we wanted to do it badly, avoiding shallow rendering and mocking when possible.

Around that time we also came across React Testing Library by Kent C. Dodds. It struck us with the simplicity and ergonomics of its API. And most of the “guiding principles” behind the library were also resonating with our experiences. So we went ahead and started creating testing helpers around React Test Renderer with an API familiar from React Testing Library.

It turned out not only possible but quite convenient to use and easy to maintain. Next month we were able to convert them to a proper library and open-source it for our clients and others to use as well.

A few months later, to our surprise, another library named “Native Testing Library” was released. Advertised as “following the guiding principles of a testing library”, while our solution was quite liberal in this manner, it got attention from Kent and soon became the “official” testing library for React Native. We had discussed the topic broadly with the “Native Testing Library” maintainers and unfortunately couldn’t find a solution that would satisfy both parties. We maintained the status quo. And the React Native community ended up with two libraries doing almost the same, with a near-identical interface.

Since then we realized how important for some users it was to follow these principles and to be as close to the React Testing Library as possible. It was not a priority for us when designing the library – instead, we wanted to focus on ergonomics, maintainability, and familiarity with the library we were inspired by. After all, it was about making writing good tests easier, and bad tests harder.

In early versions of the library, we’ve introduced some unsafe helpers which made it easier for us to migrate our client’s old tests, but harder to refactor some of the code we were testing. Our library already got some traction in the React Native community and we couldn’t “just” remove the APIs that made us sad.

We had to figure out a plan that slowly and steadily got us closer to our ideal interface, which happened to also be aligned with Testing Library principles.

That’s how we ended up with v2 of the library, bringing us pretty close to what we eventually wanted. It took us roughly a year to achieve it. Quite some time, but it was necessary to give our users time to adopt all the deprecation messages. Soon after this release, I was approached personally by Kent, sharing that our library made a leap forward the direction he likes and the “official” library has maintenance issues.

Merger

It was a good time to think about getting back to the negotiations table and hopefully joining efforts and merging the two libraries. We’ve all learned our lessons since the last time we talked. The time also validated our assumptions, approaches to develop and maintain our libraries, and pushed us to figure out the best solution for the community.

After all, it’s the developers that use the library, and being constantly asked: “why there are 2 libraries” was pretty tiring already :).

Thankfully, this time we agreed on our visions and decided to merge the two libraries in a way that we feel is the best for both the community and the library itself. The <rte-code>react-native-testing-library<rte-code> will be renamed to the official <rte-code>@testing-library/react-native<rte-code>, versioned as 7.0, keeping the source code, documentation, and Callstack’s governance, while filling the gaps with the second library.

The current @testing-library/react-native source code will be archived. Both libraries released v6.0 whose sole purpose is to be deprecated so that users can keep using previous versions without annoying deprecation warnings. And when the time comes for them to upgrade, the warning will link them to the migration guide.

Migration guide

As always, we pulled a great effort to make sure the migration steps are as easy as possible. In the process, we fixed some shortcomings, decreased the differences between the libraries, provided extra aliases, and documented everything so that you can all spend less time upgrading and more time testing.

Version 7.0 involves merging two libraries together, so there are two variants of the migration guide, dependent on the library you’ve used previously:

• guide for react-native-testing-library users
• guide for @testing-library/react-native users

Thank you for all the time you’ve been with us. Here’s to the new chapter of being single, official, React Native Testing Library 🥂

Also, special thanks to Maciej Jastrzębski and Kent C. Dodds for helping out with the migration effort.

More about React Native Testing Library

If you want to know more about React Native Testing Library and its future, check out the first episode of our The React Native Show podcast – Look into the future of React Native Testing Library!

‍