From f5be15f77c46589ae015fcefe80e41a7ac340824 Mon Sep 17 00:00:00 2001 From: Your Name Date: Fri, 3 Dec 2021 10:59:36 +0100 Subject: [PATCH 1/3] Add v9 release docs --- website/docs/MigrationV9.md | 40 +++++++++++++++++++++++++++++++++++++ website/sidebars.js | 7 ++++++- 2 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 website/docs/MigrationV9.md diff --git a/website/docs/MigrationV9.md b/website/docs/MigrationV9.md new file mode 100644 index 000000000..0f3393273 --- /dev/null +++ b/website/docs/MigrationV9.md @@ -0,0 +1,40 @@ +--- +id: migration-v9 +title: Migration to 9.0 +--- + +Version 7.0 brought this package as the standard `react-native` implementation in the `@testing-library`. However it has been implemented independently from its web counterpart, therefore there were some differences in API an behaviour. Version 9.0 solves several of these problems. + +# API changes + +## Support for text match options a.k.a string precision API (backward compatible change) + +When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/api-queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case. + +```jsx +const { getByText } = render(Hello World); + +getByText('Hello World'); // Matches +getByText('Hello'); // Doesn't match +getByText('hello', { exact: false }); // ignore case-sensitivity and does partial matching +``` + +`findBy*` queries used to take a `waitForOptions` parameter (e.g. `findByText('Hello world', {timeout: 3000})`), that parameter has been moved to the third place: `findByText('Hello world', {exact: true}, {timeout: 3000})`. For backward compatibility, `@testing-library/react-native@9.0` still reads `waitForOptions` from the second parameter but will print a deprecation warning: `findByText('Hello world', {timeout: 3000, exact: false})`. + +## Stop matching across several nodes (breaking change) + +When text is spread across several nodes `Hello world`, `@testing-library/react-native` used to allow matching the full string `getByText('Hello world')`. However this behaviour was different than the web one, and wouldn't always be straightforward to reason about (it could match text nodes far from each other on the screen). From v9, this type of match will not work. A work around is to use `within`: + +```tsx +import {Text} from 'react-native' +import {render, within} from '@testing-library/react-native' + +const {getByText} = render(Hello world) + +// exact: false +within(getByText('Hello', {exact: false})).getByText('world') +``` + +# Future plans + +This release changes a lot of internal logic in `@testing-library/react-native`, paving the way for more more improvements to bring us closer from our web counterpart, with for instance a better support for accessibility queries. diff --git a/website/sidebars.js b/website/sidebars.js index 3c69cbe7e..63f1cb6aa 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -2,7 +2,12 @@ module.exports = { docs: { Introduction: ['getting-started'], 'API Reference': ['api', 'api-queries'], - Guides: ['migration-v7', 'migration-v2', 'how-should-i-query'], + Guides: [ + 'migration-v9', + 'migration-v7', + 'migration-v2', + 'how-should-i-query', + ], Examples: ['react-navigation', 'redux-integration'], }, }; From 14206f830e79e7cd1aae04a7c0364bff22e369d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 3 Dec 2021 23:13:28 +0100 Subject: [PATCH 2/3] Apply suggestions from code review --- website/docs/MigrationV9.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/website/docs/MigrationV9.md b/website/docs/MigrationV9.md index 0f3393273..8c82662d0 100644 --- a/website/docs/MigrationV9.md +++ b/website/docs/MigrationV9.md @@ -19,11 +19,11 @@ getByText('Hello'); // Doesn't match getByText('hello', { exact: false }); // ignore case-sensitivity and does partial matching ``` -`findBy*` queries used to take a `waitForOptions` parameter (e.g. `findByText('Hello world', {timeout: 3000})`), that parameter has been moved to the third place: `findByText('Hello world', {exact: true}, {timeout: 3000})`. For backward compatibility, `@testing-library/react-native@9.0` still reads `waitForOptions` from the second parameter but will print a deprecation warning: `findByText('Hello world', {timeout: 3000, exact: false})`. +The `findBy*` queries used to take a `waitForOptions` parameter as a second argument, e.g. `findByText('Hello world', {timeout: 3000})`. It has now been moved to the third argument: `findByText('Hello world', {exact: true}, {timeout: 3000})`. For backward compatibility, `@testing-library/react-native@9.0` can still read `waitForOptions` from the second argument but will print a deprecation warning. ## Stop matching across several nodes (breaking change) -When text is spread across several nodes `Hello world`, `@testing-library/react-native` used to allow matching the full string `getByText('Hello world')`. However this behaviour was different than the web one, and wouldn't always be straightforward to reason about (it could match text nodes far from each other on the screen). From v9, this type of match will not work. A work around is to use `within`: +When text is spread across several nodes, like: `Hello world`, React Native Testing Library used to allow matching the full string using `getByText('Hello world')`. However this behaviour was different than the web one, and wouldn't always be straightforward to reason about. For instance it could match text nodes far from each other on the screen. From v9, this type of match will not work. A work around is to use `within`: ```tsx import {Text} from 'react-native' @@ -31,10 +31,9 @@ import {render, within} from '@testing-library/react-native' const {getByText} = render(Hello world) -// exact: false within(getByText('Hello', {exact: false})).getByText('world') ``` # Future plans -This release changes a lot of internal logic in `@testing-library/react-native`, paving the way for more more improvements to bring us closer from our web counterpart, with for instance a better support for accessibility queries. +This release changes a lot of internal logic in the library, paving the way for more improvements to bring us closer to our web counterpart, with a possibly better story for accessibility queries. From c794412ffdcb95ad170de9f9747e226ddc08b526 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 3 Dec 2021 23:36:21 +0100 Subject: [PATCH 3/3] chore: text adjustments --- website/docs/MigrationV9.md | 44 ++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/website/docs/MigrationV9.md b/website/docs/MigrationV9.md index 8c82662d0..3da587dc6 100644 --- a/website/docs/MigrationV9.md +++ b/website/docs/MigrationV9.md @@ -3,13 +3,13 @@ id: migration-v9 title: Migration to 9.0 --- -Version 7.0 brought this package as the standard `react-native` implementation in the `@testing-library`. However it has been implemented independently from its web counterpart, therefore there were some differences in API an behaviour. Version 9.0 solves several of these problems. +Version 7.0 brought React Native Testing Library into the `@testing-library` family. Since it has been implemented independently from its web counterpart – the React Testing Library – there are some differences in the API and behavior. Version 9.0 solves several of these problems. -# API changes +## Support for text match options a.k.a string precision API -## Support for text match options a.k.a string precision API (backward compatible change) +This is a backward compatible change. -When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/api-queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case. +When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/api-queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case: ```jsx const { getByText } = render(Hello World); @@ -19,11 +19,35 @@ getByText('Hello'); // Doesn't match getByText('hello', { exact: false }); // ignore case-sensitivity and does partial matching ``` -The `findBy*` queries used to take a `waitForOptions` parameter as a second argument, e.g. `findByText('Hello world', {timeout: 3000})`. It has now been moved to the third argument: `findByText('Hello world', {exact: true}, {timeout: 3000})`. For backward compatibility, `@testing-library/react-native@9.0` can still read `waitForOptions` from the second argument but will print a deprecation warning. +Please note that the `findBy*` queries used to take a `waitForOptions` parameter as a second argument, which has now been moved to the third argument: -## Stop matching across several nodes (breaking change) +```diff +-findByText('Hello world', { timeout: 3000 }); // old findBy* API ++findByText('Hello world', {}, { timeout: 3000 }); // new findBy* API +``` + +For backward compatibility RNTL v9 can still read `waitForOptions` from the second argument but will print a deprecation warning. + +## Reverted matching text across several nodes -When text is spread across several nodes, like: `Hello world`, React Native Testing Library used to allow matching the full string using `getByText('Hello world')`. However this behaviour was different than the web one, and wouldn't always be straightforward to reason about. For instance it could match text nodes far from each other on the screen. From v9, this type of match will not work. A work around is to use `within`: +:::caution +This is a breaking change. +::: + +In v1.14 we've introduced a feature allowing to match text when it's spread across several nodes: + +```tsx +const { getByText } = render( + + Hello world + +); +getByText('Hello world'); // matches +``` + +However this behavior was different than the web one, and wouldn't always be straightforward to reason about. For instance it could match text nodes far from each other on the screen. It also prevented us from implementing the string precision API. From v9, this type of match will not work. + +A work around is to use `within`: ```tsx import {Text} from 'react-native' @@ -34,6 +58,10 @@ const {getByText} = render(Hello world) within(getByText('Hello', {exact: false})).getByText('world') ``` -# Future plans +## Future plans This release changes a lot of internal logic in the library, paving the way for more improvements to bring us closer to our web counterpart, with a possibly better story for accessibility queries. + +We're also [migrating the codebase to TypeScript](https://github.com/callstack/react-native-testing-library/issues/877). Please let us know if you're interested in helping us with this effort. + +Stay safe!