diff --git a/website/docs/12.x/index.md b/website/docs/12.x/index.md index 86faefdda..85466e690 100644 --- a/website/docs/12.x/index.md +++ b/website/docs/12.x/index.md @@ -2,18 +2,17 @@ pageType: home hero: - name: 'React Native' - text: 'Testing Library' + name: 'React Native Testing Library' image: src: /img/owl.png tagline: Helps you to write better tests with less effort. actions: - theme: brand text: Quick Start - link: /docs/start/quick-start + link: /12.x/docs/start/quick-start - theme: alt text: Explore API - link: /docs/api + link: /12.x/docs/api features: - title: Maintainable details: Write maintainable tests for your React Native apps. diff --git a/website/docs/13.x/index.md b/website/docs/13.x/index.md index 86faefdda..c63bc712a 100644 --- a/website/docs/13.x/index.md +++ b/website/docs/13.x/index.md @@ -2,8 +2,7 @@ pageType: home hero: - name: 'React Native' - text: 'Testing Library' + name: 'React Native Testing Library' image: src: /img/owl.png tagline: Helps you to write better tests with less effort. diff --git a/website/docs/14.x/docs/_meta.json b/website/docs/14.x/docs/_meta.json index 4387b5b9a..6140a71b1 100644 --- a/website/docs/14.x/docs/_meta.json +++ b/website/docs/14.x/docs/_meta.json @@ -14,11 +14,5 @@ "type": "dir", "name": "advanced", "label": "Advanced Guides" - }, - { - "type": "dir", - "name": "migration", - "label": "Migration Guides", - "collapsed": true } ] diff --git a/website/docs/14.x/docs/api/jest-matchers.mdx b/website/docs/14.x/docs/api/jest-matchers.mdx index 9538194de..739785479 100644 --- a/website/docs/14.x/docs/api/jest-matchers.mdx +++ b/website/docs/14.x/docs/api/jest-matchers.mdx @@ -6,10 +6,6 @@ This guide describes built-in Jest matchers, we recommend using these matchers a There is no need to set up the built-in matchers; they are automatically available in your tests when you import anything from `@testing-library/react-native`, e.g., `render`. -## Migration from legacy Jest Native matchers. - -If you are already using legacy Jest Native matchers we have a [migration guide](/docs/migration/jest-matchers) for moving to the built-in matchers. - ## Checking element existence ### `toBeOnTheScreen()` diff --git a/website/docs/14.x/docs/migration/_meta.json b/website/docs/14.x/docs/migration/_meta.json deleted file mode 100644 index 2a769db78..000000000 --- a/website/docs/14.x/docs/migration/_meta.json +++ /dev/null @@ -1 +0,0 @@ -["v14", "jest-matchers", "v13", "v12", "v11", "v9", "v7", "v2"] diff --git a/website/docs/14.x/docs/migration/jest-matchers.mdx b/website/docs/14.x/docs/migration/jest-matchers.mdx deleted file mode 100644 index 9abefaae3..000000000 --- a/website/docs/14.x/docs/migration/jest-matchers.mdx +++ /dev/null @@ -1,70 +0,0 @@ -# Migration to built-in Jest matchers - -This guide describes the steps necessary to migrate from [legacy Jest Native matchers v5](https://github.com/testing-library/jest-native) to [built-in Jest matchers](/docs/api/jest-matchers). - -## General notes - -All of the built-in Jest matchers provided by the React Native Testing Library support only host elements. This should not be an issue, as all RNTL v12 queries already return only host elements. When this guide states that a given matcher should work the same it assumes behavior only host elements. If you need to assert the status of composite elements use Jest Native matchers in [legacy mode](#gradual-migration). - -## Usage - -There is no need to set up the built-in matchers; they are automatically available in your tests when you import anything from `@testing-library/react-native`, e.g., `render`. - -### Gradual migration - -You can use the built-in matchers alongside legacy Jest Native matchers by changing their import in your `jest-setup.ts` file: - -```ts -// Replace this: -// import '@testing-library/jest-native/extend-expect'; - -// With this: -import '@testing-library/jest-native/legacy-extend-expect'; -``` - -In this case legacy matchers will be available using the `legacy_` prefix, e.g.: - -```ts -expect(element).legacy_toHaveAccessibilityState({ busy: true }); -``` - -## Migration details - -### Matchers not requiring changes - -The following matchers should work the same: - -- [`toBeEmptyElement()`](/docs/api/jest-matchers#tobeemptyelement) -- [`toBeEnabled()` / `toBeDisabled()`](/docs/api/jest-matchers#tobeenabled) -- [`toBeOnTheScreen()`](/docs/api/jest-matchers#tobeonthescreen) -- [`toBeVisible()`](/docs/api/jest-matchers#tobevisible) -- [`toContainElement()`](/docs/api/jest-matchers#tocontainelement) -- [`toHaveAccessibilityValue()`](/docs/api/jest-matchers#tohaveaccessibilityvalue) -- [`toHaveDisplayValue()`](/docs/api/jest-matchers#tohavedisplayvalue) -- [`toHaveProp()`](/docs/api/jest-matchers#tohaveprop) -- [`toHaveStyle()`](/docs/api/jest-matchers#tohavestyle) -- [`toHaveTextContent()`](/docs/api/jest-matchers#tohavetextcontent) - -### Replaced matchers - -The `toHaveAccessibilityState()` matcher has been replaced by the following matchers: - -- enabled state: [`toBeEnabled()` / `toBeDisabled()`](/docs/api/jest-matchers#tobeenabled) -- checked state: [`toBeChecked()` / `toBePartiallyChecked()`](/docs/api/jest-matchers#tobechecked) -- selected state: [`toBeSelected()`](/docs/api/jest-matchers#tobeselected) -- expanded state: [`toBeExpanded()` / `toBeCollapsed()`](/docs/api/jest-matchers#tobeexpanded) -- busy state: [`toBeBusy()`](/docs/api/jest-matchers#tobebusy) - -The new matchers support both `accessibilityState` and `aria-*` props. - -### Added matchers - -New [`toHaveAccessibleName()`](/docs/api/jest-matchers#tohaveaccessiblename) has been added. - -### Noteworthy details - -You should be aware of the following details: - -- [`toBeEnabled()` / `toBeDisabled()`](/docs/api/jest-matchers#tobeenabled) matchers also check the disabled state for the element's ancestors and not only the element itself. This is the same as in legacy Jest Native matchers of the same name but differs from the removed `toHaveAccessibilityState()` matcher. -- [`toBeChecked()`](/docs/api/jest-matchers#tobechecked) matcher works only on `Switch` host elements or accessibility elements with `checkbox`, `radio` or `switch` role -- [`toBePartiallyChecked()`](/docs/api/jest-matchers#tobechecked) matcher supports only elements with `checkbox` role diff --git a/website/docs/14.x/docs/migration/v11.mdx b/website/docs/14.x/docs/migration/v11.mdx deleted file mode 100644 index c803bc2b1..000000000 --- a/website/docs/14.x/docs/migration/v11.mdx +++ /dev/null @@ -1,53 +0,0 @@ -# Migration to 11.x - -Migration to React Native Testing Library version 11 from version 9.x or 10.x should be a relatively easy task due small amount of breaking changes. - -## Breaking changes - -### Update to Jest 28 if you use fake timers - -If you use fake timers in any of your tests you should update your Jest dependencies to version 28. This is due to the fact that [`jest.useFakeTimers()` config structure](https://jestjs.io/docs/jest-object#jestusefaketimersfaketimersconfig) has changed. - -### Refactor legacy `waitForOptions` position - -In version 9 we introducted query `options` parameters for each query type. This affected all `findBy` and `findAllBy` queries because their signatures changed e.g. from: - -```ts -function findByText(text: TextMatch, waitForOptions?: WaitForOptions); -function findAllByText(text: TextMatch, waitForOptions?: WaitForOptions); -``` - -to - -```ts -function findByText(text: TextMatch, options?: TextMatchOptions, waitForOptions?: WaitForOptions); -function findAllByText( - text: TextMatch, - options?: TextMatchOptions, - waitForOptions?: WaitForOptions -); -``` - -In order to facilitate transition, in version 9 and 10, we provided a temporary possibility to pass `WaitForOptions` like `timeout`, `interval`, etc inside `options` argument. From this release we require passing these as the proper third parameter. - -This change is easy to implement: - -```ts -findByText(/Text/, { timeout: 1000 }); -``` - -should become - -```ts -findByText(/Text/, {}, { timeout: 1000 }); -``` - -### Triggering non-touch events on targets with `pointerEvents="box-none"` prop - -Up to version 10, RNTL disables all events for a target with `pointerEvents="box-none"`. This behavior is counter to how React Native itself functions. - -From version 11, RNTL continues to disable `press` event for these targets but allows triggering other events, e.g. `layout`. - -## Full Changelog - -https://github.com/callstack/react-native-testing-library/compare/v10.1.1...v11.0.0 diff --git a/website/docs/14.x/docs/migration/v12.mdx b/website/docs/14.x/docs/migration/v12.mdx deleted file mode 100644 index 7a5861910..000000000 --- a/website/docs/14.x/docs/migration/v12.mdx +++ /dev/null @@ -1,70 +0,0 @@ -# Migration to 12.x - -:::info - -If you are already using legacy `@testing-library/jest-native` Jest Matchers, we have a [migration guide](/docs/migration/jest-matchers) for moving to the built-in matchers. - -::: - -React Native Testing Library 12 introduces a handful of breaking changes compared to 11.x versions. We believe they were necessary to improve the experience using the library and help the users [fall into the pit of success](https://blog.codinghorror.com/falling-into-the-pit-of-success/) when writing meaningful tests. You will find migration instructions for each and every change described below. - -## Breaking changes - -### 1. All queries exclude elements hidden from accessibility by default - -Elements that are hidden from accessiblity, e.g. elements on non-active screen when using React Navigation, now will not be matched by default by all queries. This is the effect of switching the default value for global config option `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) to `false`. - -Previous behaviour of matching hidden elements can be enabled on query level using [includeHiddenElements](/docs/api/queries#includehiddenelements-option) query options or globally using `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) configuration option. - -### 2. `*ByRole` queries now return only accessibility elements - -`*ByRole` queries now return only accessibility elements, either explicitly marked with `accessible` prop or implicit ones where this status is derived from component type itself (e.g `Text`, `TextInput`, `Switch`, but not `View`). - -You may need to adjust relevant components under test to make sure they pass `isAccessibilityElement` check. - -#### Examples - -Let's assume we are using `getByRole("button")` query. - -Following elements will match: - -```tsx -// Explicit "accessible" prop for View - - -// No need to "accessible" prop for Text, as it is implicitly accessible element. -Button -``` - -While following elements will not match: - -```tsx -// Missing "accessible" prop for View - - -// Explicit "accessible={false}" prop for View - - -// Explicit "accessible={false}" for Text, which is implicitly accessible element -Button -``` - -### 3. `*ByText`, `*ByDisplayValue`, `*ByPlaceholderText` queries now return host elements - -`*ByText`, `*ByDisplayValue`, `*ByPlaceholderText` queries now return [host elements](/docs/advanced/testing-env#host-and-composite-components), which is consistent with other queries. - -While potentially breaking, this should not cause issues in tests if you are using recommended queries and Jest Matchers from Jest Native package. - -Problematic cases may include: directly checking some prop values (without using Jest Native matchers), referencing other nodes using `parent` or `children` props, examining `type` property of `HostElement`, etc. - -### 4. `container` API has been renamed to `UNSAFE_root`. - -Historically `container` was supposed to mimic the [RTL's container](https://testing-library.com/docs/react-testing-library/screen#container). However it turned out not so relevant in RNTL's environment, where we actually used it to return React Test Renderer's root instance. - -RNTL v12 introduces `root` API as an alternative that returns a root **host** element. The difference between `root` and `UNSAFE_root` properties is that that `root` will always represents a host element, while `UNSAFE_root` will typically represent a composite element. - -If you use `toBeOnTheScreen` matcher from [@testing-library/jest-native](https://github.com/testing-library/jest-native) your tests will fail because it uses the `container` api. To fix this, update `@testing-library/jest-native` to version 5.4.2. - -## Full Changelog - -https://github.com/callstack/react-native-testing-library/compare/v11.5.2...v12.0.0 diff --git a/website/docs/14.x/docs/migration/v13.mdx b/website/docs/14.x/docs/migration/v13.mdx deleted file mode 100644 index cf8c3abc3..000000000 --- a/website/docs/14.x/docs/migration/v13.mdx +++ /dev/null @@ -1,122 +0,0 @@ -# Migration to 13.x - -This guide describes the migration to React Native Testing Library version 13 from version 12.x. - -Overall, the v13 release is relatively small, focusing on removing deprecated queries and improving the developer experience. - -## Breaking changes - -### Supported React and React Native versions - -This version supports only React 18+ and corresponding React Native versions (0.71+). If you use React 16 or 17, please use the latest of v12 versions. - -Note: currently, stable React Native is unavailable for React 19, which is still in the RC phase, so we test against React Native nightly builds. - -### Concurrent rendering by default - -This version introduces concurrent rendering by default. This change should not affect regular tests, but it might affect your tests if you use React Suspense or similar. - -You can revert to legacy rendering by passing `concurrentRoot: false` to [render](/docs/api/render#concurrent-root) or [configure](/docs/api/misc/config#concurrent-root) methods. - -Note: in React 19, concurrent rendering is the only supported rendering mode. - -### Extend Jest matchers by default - -You can remove `import '@testing-library/react-native/extend-expect'` imports, as now Jest matchers are extended by default when you import anything from `@testing-library/react-native`. - -You can avoid the automatic extending of Jest matchers by importing `@testing-library/react-native/pure` instead. - -```tsx title=jest-setup.ts -// Remove this: -import '@testing-library/react-native/extend-expect'; -``` - -### Removed deprecated `*ByAccessibilityState` queries - -We have removed this deprecated query as it is typically too general to give meaningful results. Use one of the following options: - -- [\*ByRole](#by-role) query with relevant state options: `disabled`, `selected`, `checked`, `expanded` and `busy` -- use built-in Jest matchers to check the state of element found using some other query: - - enabled state: [toBeEnabled() / toBeDisabled()](/docs/api/jest-matchers#tobeenabled) - - checked state: [toBeChecked() / toBePartiallyChecked()](/docs/api/jest-matchers#tobechecked) - - selected state: [toBeSelected()](/docs/api/jest-matchers#tobeselected) - - expanded state: [toBeExpanded() / toBeCollapsed()](/docs/api/jest-matchers#tobeexpanded) - - busy state: [toBeBusy()](/docs/api/jest-matchers#tobebusy) - -```ts -// Replace this: -const view = screen.getByAccessibilityState({ disabled: true }); - -// with this (getByRole query): -const view = screen.getByRole('', { disabled: true }); - -// or this (Jest matcher): -const view = screen.getBy*(...); // Find the element using any query: *ByRole, *ByText, *ByTestId -expect(view).toBeDisabled(); // Assert its accessibility state -``` - -### Removed deprecated `*ByAccessibilityValue` queries - -We have removed this deprecated query as it is typically too general to give meaningful results. Use one of the following options: - -- [toHaveAccessibilityValue()](/docs/api/jest-matchers#tohaveaccessibilityvalue) Jest matcher to check the state of element found using some other query -- [\*ByRole](#by-role) query with `value` option - -```ts -// Replace this: -const view = screen.getByAccessibilityValue({ now: 50, min: 0, max: 50 }); - -// with this (getByRole query): -const view = screen.getByRole('', { value: { now: 50, min: 0, max: 50 } }); - -// or this (Jest matcher): -const view = screen.getBy*(...); // Find the element using any query: *ByRole, *ByText, *ByTestId -expect(view).toHaveAccessibilityValue({ now: 50, min: 0, max: 50 }); // Assert its accessibility value -``` - -### Removed Jest preset - -We have removed RNTL Jest preset, so you should change you `jest.config.js` accordingly. - -Replace: - -```ts title=jest.config.js -// replace this: -preset: '@testing-library/react-native'; - -// with this: -preset: 'react-native'; -``` - -### Removed `debug.shallow` - -We didn't support shallow rendering for the time being. Now, we are removing the last remains of it: `debug.shallow()`. If you are interested in shallow rendering see [here](/docs/migration/v2#removed-global-shallow-function). - -### Changes to accessibility label calculation - -Explicit labels: - -- `accessiblityLabelledBy` -- `accessiblityLabel` -- `aria-labelledby` -- `aria-label` - -now take strict priority over implicit labels derived from the element's text content. - -## Other changes - -### Removed host component names autodetection - -This change should not break any tests, it should also make RNTL tests run 10-20% faster. - -### Use React implementation of `act` instead of React Test Renderer one - -This change should not break any tests. - -### Updated `flushMicroTasks` internal method - -This change should not break any tests. - -## Full Changelog - -https://github.com/callstack/react-native-testing-library/compare/v12.8.1...v13.0.0 diff --git a/website/docs/14.x/docs/migration/v2.mdx b/website/docs/14.x/docs/migration/v2.mdx deleted file mode 100644 index 7870096ee..000000000 --- a/website/docs/14.x/docs/migration/v2.mdx +++ /dev/null @@ -1,123 +0,0 @@ -# Migration to 2.x - -This guide describes steps necessary to migrate from React Native Testing Library `v1.x` to `v2.x`. - -## Dropping Node 8 - -Node 8 reached its EOL more than 5 months ago, so it's about time to target the library to Node 10. If you used lower version, you'll have to upgrade to v10, but we recommend using the latest LTS version. - -## Auto Cleanup - -`cleanup()` function is now called automatically after every test if your testing framework supports `afterEach` hook (like Jest, Mocha, and Jasmine). - -You should be able to remove all `afterEach(cleanup)` calls in your code. - -This change might break your code, if you tests are not isolated, i.e. you call `render` outside `test` block. Generally, you should [keep your tests isolated](https://kentcdodds.com/blog/test-isolation-with-react). But if you can't or don't want to do this right away you can prevent this behavior using any of the following ways: - -- by importing `'react-native-testing-library/pure'` instead of `'react-native-testing-library'` -- by importing `'react-native-testing-library/dont-cleanup-after-each'` before importing `'react-native-testing-library'`. You can do it in a global way by using Jest's `setupFiles` like this: - - ```json - { - "setupFiles": ["react-native-testing-library/dont-cleanup-after-each"]; - } - ``` - -- by setting `RNTL_SKIP_AUTO_CLEANUP` env variable to `true`. You can do this with `cross-evn` like this: - - ```sh - cross-env RNTL_SKIP_AUTO_CLEANUP=true jest - ``` - -## WaitFor API changes - -We renamed `waitForElement` function to `waitFor` for consistency with React Testing Library. Additionally, the signature has slightly changed from: - -```jsx -export default function waitForElement( - expectation: () => T, - timeout?: number, - interval?: number -): Promise {} -``` - -to: - -```jsx -export default function waitFor( - expectation: () => T, - options: { - timeout?: number, - interval?: number, - } -): Promise {} -``` - -Both changes should improve code readibility. - -`waitFor` calls (and hence also `findBy` queries) are now wrapped in `act` by default, so that you should no longer need to use `act` directly in your tests. - -:::tip -You can usually avoid `waitFor` by a proper use of `findBy` asynchronous queries. It will result in more streamlined testing experience. -::: - -## Removed global `debug` function - -The `debug()` method returned from `render()` function is all you need. We removed the global export to avoid confusion. - -## Removed global `shallow` function - -Shallow rendering React component is usually not a good idea, so we decided to remove the API. But, if you find it useful or need to support legacy tests, feel free to use this implementation: - -```js -import ShallowRenderer from 'react-test-renderer/shallow'; - -export function shallow(instance: HostElement | React.Element) { - const renderer = new ShallowRenderer(); - renderer.render(React.createElement(instance.type, instance.props)); - - return { output: renderer.getRenderOutput() }; -} -``` - -## Removed functions - -Following query functions have been removed after being deprecated for more than a year now: - -- `getByName` -- `getAllByName` -- `queryByName` -- `queryAllByName` - -The `*ByType` and `*ByProps` queries has been prefixed with `UNSAFE_`. These `UNSAFE_` functions are not planned for removal in future versions but their usage is discouraged. You can rename them using global search/replace in your project: - -- `getByType` -> `UNSAFE_getByType` -- `getAllByType` -> `UNSAFE_getAllByType` -- `queryByType` -> `UNSAFE_queryByType` -- `queryAllByType` -> `UNSAFE_queryAllByType` -- `getByProps` -> `UNSAFE_getByProps` -- `getAllByProps` -> `UNSAFE_getAllByProps` -- `queryByProps` -> `UNSAFE_queryByProps` -- `queryAllByProps` -> `UNSAFE_queryAllByProps` - -## Some `ByTestId` queries behavior changes - -In version `1.x` the `getByTestId` and `queryByTestId` queries could return non-native instances. This was a serious bug. Other query functions like `getAllByTestId`, `queryAllByTestId`, `findByTestId` and `findAllByTestId` didn't have this issue. These correctly returned only native components instances (e.g. `View`, `Text`, etc) that got the `testID`. - -In v2 we fixed this inconsistency, which may result in failing tests, if you relied on this behavior. There are few ways to handle these failures: - -- pass the `testID` prop down so it can reach a native component, like `View` or `Text` -- replace `testID` with proper `accessibilityHint` or `accessibilityLabel` if it benefits the user -- use safe queries like `*ByText` or `*ByA11yHint` - -## Deprecated `flushMicrotasksQueue` - -We have deprecated `flushMicrotasksQueue` and plan to remove it in the next major. We have better alternatives available for helping you write async tests – `findBy` async queries and `waitFor` helper. - -If you can't or don't want to migrate your tests, don't worry. You can use the same implementation we have today: - -```js -function flushMicrotasksQueue() { - return new Promise((resolve) => setImmediate(resolve)); -} -``` diff --git a/website/docs/14.x/docs/migration/v7.mdx b/website/docs/14.x/docs/migration/v7.mdx deleted file mode 100644 index 60a6d7106..000000000 --- a/website/docs/14.x/docs/migration/v7.mdx +++ /dev/null @@ -1,115 +0,0 @@ -# Migration to 7.x - -:::info - -We renamed the `react-native-testing-library` npm package to `@testing-library/react-native`, officially joining the "Testing Library" family 🎉. - -::: - -As the version 7.0 involves merging two libraries together, there are two variants for migration guide, dependent on library you used previously: - -## Guide for `react-native-testing-library` users - -This guide describes steps necessary to migrate from React Native Testing Library `v2.x` or `v6.0` to `v7.0`. - -### Renaming the library - -1. Install `@testing-library/react-native`. -1. Uninstall `react-native-testing-library`. -1. Rename all references of `react-native-testing-library` to `@testing-library/react-native`. - -You may have noticed a strange v2 to v7 upgrade, skipping versions 3, 4, 5 and 6. This is because we renamed the `react-native-testing-library` npm package to `@testing-library/react-native`, officially joining the "Testing Library" family 🎉. We're merging existing two libraries into a single one. The [native-testing-library](https://github.com/testing-library/native-testing-library) repository, which had v6, will soon be archived and using `@testing-library/react-native` below v7, sourced from mentioned repository, is deprecated. - -For branding purposes we keep the "React Native Testing Library" name, similar to "React Testing Library". Only the npm published package is changing. The code repository also stays the same under Callstack governance. - -### New aliases - -To improve compatibility with React Testing Library, and ease the migration for `@testing-library/react-native` users using version below v7, we've introduced new aliases to our accessibility queries: - -- `ByLabelText` aliasing `ByA11yLabel` queries -- `ByHintText` aliasing `ByA11yHint` queries -- `ByRole` aliasing `ByA11yRole` queries - -We like the new names and consider removing the aliases in future releases. - -### Renaming `ByPlaceholder` queries - -To improve compatibility with React Testing Library, and to ease the migration for `@testing-library/react-native` users using version below v7, we've renamed following queries: - -- `ByPlaceholder` -> `ByPlaceholderText` - -Please replace all occurrences of these queries in your codebase. - -### `fireEvent` support for disabled components - -To improve compatibility with the real React Native environment `fireEvent` now performs checks whether the component is "disabled" before firing an event on it. It uses the Responder system to establish should the event fire, which resembles the actual React Native runtime closer than we used to. - -If your code contained any workarounds for preventing events firing on disabled events, you should now be able to remove them. - -## Guide for `@testing-library/react-native` users - -This guide describes steps necessary to migrate from `@testing-library/react-native` from `v6.0` to `v7.0`. Although the name stays the same, this is a different library, sourced at [Callstack GitHub repository](https://github.com/callstack/react-native-testing-library). We made sure the upgrade path is as easy for you as possible. - -### Renaming "wait" helpers - -The `wait` and `waitForElement` helpers are replaced by `waitFor`. Please rename all occurrences of these in your codebase. - -### Changes to `ByTestId` queries - -The `ByTestId` queries don't accept RegExps. Please use strings instead. We're happy to accept PRs adding this functionality :). - -### No `ByTitle` queries - -Our library doesn't implement `ByTitle` queries, which are targetting components with `title` prop, specifically `Button` and `RefreshControl`. If your tests only use `ByTitle` to target `Button` components, you can replace them with `ByText` queries, since React Native renders `Text` under the hood. - -If you need to query `RefreshControl` component and can't figure out other way around it, you can use e.g. `UNSAFE_getByProps({title})` query. - -### No custom Jest configuration - -Use the official React Native preset for Jest: - -```diff -{ - "jest": { -- "preset": "@testing-library/react-native" -+ "preset": "react-native" - } -} -``` - -We're told this also speeds up your tests startup on cold cache. Using official preset has another benefit – the library is compatible with any version of React Native without introducing breaking changes. - -### Cleanup is included by default - -Cleaning up (unmounting) components after each test is included by default in the same manner as in React Testing Library. Please remove this setup file from Jest config: - -```diff -{ - "jest": { -- "setupFilesAfterEnv": ["@testing-library/react-native/cleanup-after-each"] - } -} -``` - -You can opt-out of this behavior by running tests with `RNTL_SKIP_AUTO_CLEANUP=true` flag or importing from `@testing-library/react-native/pure`. We encourage you to keep the default though. - -### No [NativeTestInstance](https://www.native-testing-library.com/docs/api-test-instance) abstraction - -We don't provide any abstraction over `HostElement` returned by queries, but allow to use it directly to access queried component's `props` or `type` for that example. - -### No `container` nor `baseElement` returned from `render` - -There's no `container` returned from the `render` function. If you must, use `react-test-renderer` directly, although we advise against doing so. We also don't implement `baseElement` because of that, since there's no `document.documentElement` nor `container`. - -### Firing events changes - -There are slight differences in how `fireEvent` works in both libraries: - -1. Our library doesn't perform validation checks for events fired upon tested components. -1. Signature is different: - ```diff - -fireEvent[eventName](node: FiberRoot, eventProperties: NativeTestEvent) - +fireEvent(element: HostElement, eventName: string, ...data: Array) - ``` -1. There is no `NativeTestEvent` - second and rest arguments are used instead. -1. There are only 3 short-hand events: [`fireEvent.press`](/docs/api/events/fire-event#press), [`fireEvent.changeText`](/docs/api/events/fire-event#change-text) and [`fireEvent.scroll`](/docs/api/events/fire-event#scroll). For all other or custom events you can use the base signature. diff --git a/website/docs/14.x/docs/migration/v9.mdx b/website/docs/14.x/docs/migration/v9.mdx deleted file mode 100644 index 60557c566..000000000 --- a/website/docs/14.x/docs/migration/v9.mdx +++ /dev/null @@ -1,64 +0,0 @@ -# Migration to 9.x - -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. - -## Support for text match options a.k.a string precision API - -This is a backward compatible change. - -When querying text, it is now possible to pass a [`TextMatch`](/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 -``` - -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: - -```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 - -:::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' -import { render, within } from '@testing-library/react-native' - -const { getByText } = render(Hello world) - -within(getByText('Hello', {exact: false})).getByText('world') -``` - -## 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! diff --git a/website/docs/14.x/docs/start/_meta.json b/website/docs/14.x/docs/start/_meta.json index 13858aa42..44210bd93 100644 --- a/website/docs/14.x/docs/start/_meta.json +++ b/website/docs/14.x/docs/start/_meta.json @@ -1,9 +1 @@ -[ - "intro", - "quick-start", - { - "type": "custom-link", - "label": "v14 Migration", - "link": "/docs/migration/v14" - } -] +["intro", "quick-start", "migration-v14"] diff --git a/website/docs/14.x/docs/migration/v14.mdx b/website/docs/14.x/docs/start/migration-v14.mdx similarity index 100% rename from website/docs/14.x/docs/migration/v14.mdx rename to website/docs/14.x/docs/start/migration-v14.mdx diff --git a/website/docs/14.x/index.md b/website/docs/14.x/index.md index 86faefdda..fffa816ae 100644 --- a/website/docs/14.x/index.md +++ b/website/docs/14.x/index.md @@ -2,18 +2,17 @@ pageType: home hero: - name: 'React Native' - text: 'Testing Library' + name: 'React Native Testing Library' image: src: /img/owl.png tagline: Helps you to write better tests with less effort. actions: - theme: brand text: Quick Start - link: /docs/start/quick-start + link: /14.x/docs/start/quick-start - theme: alt text: Explore API - link: /docs/api + link: /14.x/docs/api features: - title: Maintainable details: Write maintainable tests for your React Native apps. diff --git a/website/docs/styles/index.css b/website/docs/styles/index.css index 53b50a7cc..c1eec7ec4 100644 --- a/website/docs/styles/index.css +++ b/website/docs/styles/index.css @@ -1,3 +1,47 @@ +/* Pre-Release Banner */ +.pre-release-banner { + background: linear-gradient(90deg, var(--rp-c-brand-darker) 0%, var(--rp-c-brand) 100%); + color: #ffffff; + text-align: center; + padding: 0.5rem 1rem; + font-size: 0.875rem; +} + +.pre-release-banner strong { + font-weight: 600; +} + +/* Old Version Banner */ +.old-version-banner { + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: center; + gap: 0.25rem 0.5rem; + padding: 0.5rem 1rem; + background: linear-gradient(90deg, var(--rp-c-brand-darker) 0%, var(--rp-c-brand) 100%); + color: #ffffff; + font-size: 0.875rem; + text-align: center; +} + +.old-version-banner strong { + font-weight: 600; +} + +.old-version-banner-link { + color: #ffffff !important; + font-weight: 500; + white-space: nowrap; + text-decoration: underline; + text-underline-offset: 2px; +} + +.old-version-banner-link:hover { + color: #ffffff !important; + opacity: 0.85; +} + :root { --rp-nav-height: 60px !important; --rp-sidebar-width: 320px !important; @@ -242,3 +286,47 @@ p.rspress-home-hero-text { font-size: 3rem; } } + +/* Hero Image (Owl Logo) Sizing */ +[class*='heroImage-'] { + width: 96px !important; + height: 96px !important; + min-width: 96px !important; + min-height: 96px !important; +} + +@media (min-width: 640px) { + [class*='heroImage-'] { + width: 120px !important; + height: 120px !important; + min-width: 120px !important; + min-height: 120px !important; + } +} + +@media (min-width: 768px) { + [class*='heroImage-'] { + width: 144px !important; + height: 144px !important; + min-width: 144px !important; + min-height: 144px !important; + } +} + +/* Feature Card Icons (Emojis) Sizing */ +[class*='featureIcon-'] { + font-size: 1.5rem !important; + line-height: 1 !important; +} + +@media (min-width: 640px) { + [class*='featureIcon-'] { + font-size: 1.75rem !important; + } +} + +@media (min-width: 768px) { + [class*='featureIcon-'] { + font-size: 2rem !important; + } +} diff --git a/website/rspress.config.ts b/website/rspress.config.ts index 55f9e7d7b..6f73dd90e 100644 --- a/website/rspress.config.ts +++ b/website/rspress.config.ts @@ -4,6 +4,8 @@ import { pluginCallstackTheme } from '@callstack/rspress-theme/plugin'; import { pluginOpenGraph } from 'rsbuild-plugin-open-graph'; import pluginVercelAnalytics from 'rspress-plugin-vercel-analytics'; +const __dirname = path.dirname(new URL(import.meta.url).pathname); + const sidebar12x = { '/12.x/docs/': [ { @@ -194,6 +196,7 @@ const sidebar14x = { items: [ { text: 'Introduction', link: '/14.x/docs/start/intro' }, { text: 'Quick Start', link: '/14.x/docs/start/quick-start' }, + { text: 'v14 Migration', link: '/14.x/docs/start/migration-v14' }, ], }, { @@ -239,20 +242,6 @@ const sidebar14x = { { text: 'Understanding Act', link: '/14.x/docs/advanced/understanding-act' }, ], }, - { - text: 'Migration Guides', - collapsed: true, - items: [ - { text: 'v14 Migration', link: '/14.x/docs/migration/v14' }, - { text: 'Jest Matchers', link: '/14.x/docs/migration/jest-matchers' }, - { text: 'v13', link: '/14.x/docs/migration/v13' }, - { text: 'v12', link: '/14.x/docs/migration/v12' }, - { text: 'v11', link: '/14.x/docs/migration/v11' }, - { text: 'v9', link: '/14.x/docs/migration/v9' }, - { text: 'v7', link: '/14.x/docs/migration/v7' }, - { text: 'v2', link: '/14.x/docs/migration/v2' }, - ], - }, ], '/14.x/cookbook/': [ { text: 'Cookbook', link: '/14.x/cookbook/' }, @@ -377,6 +366,7 @@ export default defineConfig({ logo: '/img/owl.png', logoText: 'React Native Testing Library', outDir: 'build', + globalStyles: path.join(__dirname, 'docs/styles/index.css'), markdown: { // checkDeadLinks is enabled by default in V2 // Shiki is now the default code highlighter diff --git a/website/theme/index.tsx b/website/theme/index.tsx new file mode 100644 index 000000000..ec1037621 --- /dev/null +++ b/website/theme/index.tsx @@ -0,0 +1,45 @@ +import { useLocation } from '@rspress/core/runtime'; +import { Link, Layout as RspressLayout } from '@rspress/core/theme-original'; + +const LATEST_VERSION = '13.x'; + +const PreReleaseBanner = () => ( +
+ + You are viewing documentation for v14 alpha. This version is under active + development and APIs may change. + +
+); + +const OldVersionBanner = ({ version }: { version: string }) => ( +
+ + You're viewing the documentation for {version}. Current latest version is{' '} + {LATEST_VERSION}. + + + View latest version here. + +
+); + +const AnnouncementBanner = () => { + const { pathname } = useLocation(); + + if (pathname.includes('/14.x/')) { + return ; + } + + if (pathname.includes('/12.x/')) { + return ; + } + + return null; +}; + +const Layout = () => } />; + +export { Layout }; + +export * from '@rspress/core/theme-original';