mirror of
https://github.com/callstack/react-native-testing-library.git
synced 2026-09-18 23:09:04 +08:00
github-actions[bot]
17 lines
48 KiB
HTML
17 lines
48 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-testing-env">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v2.3.1">
|
||
<title data-rh="true">Testing Environment | React Native Testing Library</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://callstack.github.io/react-native-testing-library/img/owl.png"><meta data-rh="true" name="twitter:image" content="https://callstack.github.io/react-native-testing-library/img/owl.png"><meta data-rh="true" property="og:url" content="https://callstack.github.io/react-native-testing-library/docs/testing-env"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Testing Environment | React Native Testing Library"><meta data-rh="true" name="description" content="This document is intended for more advanced audience. You should be able to write integration or component tests without reading this."><meta data-rh="true" property="og:description" content="This document is intended for more advanced audience. You should be able to write integration or component tests without reading this."><link data-rh="true" rel="icon" href="/react-native-testing-library/img/owl.png"><link data-rh="true" rel="canonical" href="https://callstack.github.io/react-native-testing-library/docs/testing-env"><link data-rh="true" rel="alternate" href="https://callstack.github.io/react-native-testing-library/docs/testing-env" hreflang="en"><link data-rh="true" rel="alternate" href="https://callstack.github.io/react-native-testing-library/docs/testing-env" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://6CJ0BV6AVN-dsn.algolia.net" crossorigin="anonymous"><link rel="search" type="application/opensearchdescription+xml" title="React Native Testing Library" href="/react-native-testing-library/opensearch.xml"><link rel="stylesheet" href="/react-native-testing-library/assets/css/styles.a2c05d0c.css">
|
||
<link rel="preload" href="/react-native-testing-library/assets/js/runtime~main.e63caa38.js" as="script">
|
||
<link rel="preload" href="/react-native-testing-library/assets/js/main.0d0265df.js" as="script">
|
||
</head>
|
||
<body class="navigation-with-keyboard">
|
||
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus">
|
||
<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/react-native-testing-library/"><div class="navbar__logo"><img src="/react-native-testing-library/img/owl.png" alt="React Native Testing Library" class="themedImage_ToTc themedImage--light_HNdA"><img src="/react-native-testing-library/img/owl.png" alt="React Native Testing Library" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">React Native Testing Library</b></a></div><div class="navbar__items navbar__items--right"><a class="navbar__item navbar__link" href="/react-native-testing-library/docs/getting-started">Docs</a><a href="https://github.com/callstack/react-native-testing-library" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebarViewport_Xe31"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link">Introduction</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/getting-started">Getting Started</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/faq">FAQ</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link">API Reference</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/api">API</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/api-queries">Queries</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/user-event">User Event</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link">Guides</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/troubleshooting">Troubleshooting</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/how-should-i-query">How Should I Query?</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/eslint-plugin-testing-library">ESLint Plugin Testing Library Compatibility</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--active">Advanced</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/react-native-testing-library/docs/testing-env">Testing Environment</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/understanding-act">Understanding Act function</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link">Migrations</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/migration-v12">Migration to 12.0</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/migration-v11">Migration to 11.0</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/migration-v9">Migration to 9.0</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/migration-v7">Migration to 7.0</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/migration-v2">Migration to 2.0</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link">Examples</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/react-navigation">React Navigation</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/react-native-testing-library/docs/redux-integration">Redux Integration</a></li></ul></li></ul></nav></div></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/react-native-testing-library/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Advanced</span><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Testing Environment</span><meta itemprop="position" content="2"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Testing Environment</h1></header><div class="theme-admonition theme-admonition-info alert alert--info admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>info</div><div class="admonitionContent_S0QG"><p>This document is intended for more advanced audience. You should be able to write integration or component tests without reading this.
|
||
It is intended for people who want to better understand internals of our testing environment, e.g. in order to contribute to the codebase.</p></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="testing-environment">Testing Environment<a href="#testing-environment" class="hash-link" aria-label="Direct link to Testing Environment" title="Direct link to Testing Environment"></a></h2><p>React Native Testing Library allows you to write integration and component tests for your React Native app or library. While the JSX code used in tests closely resembles your React Native app, the things are not quite as simple as they might appear. In this document we will describe the key elements of our testing environment and highlight things to be aware of when writing more advanced tests or diagnosing issues.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="react-renderers">React renderers<a href="#react-renderers" class="hash-link" aria-label="Direct link to React renderers" title="Direct link to React renderers"></a></h3><p>React allows you to write declarative code using JSX, write function or class components, or use hooks like <code>useState</code>. In order to output the results of your components it needs to work with a renderer. Every React app uses some type of renderer: React Native is a renderer for mobile apps, web apps use React DOM, and there are other more <a href="https://github.com/chentsulin/awesome-react-renderer" target="_blank" rel="noopener noreferrer">specialised renderers</a> that can e.g. render to console or HTML canvas.</p><p>When you run your tests in React Native Testing Library, somewhat contrary to what the name suggest, they are actually <strong>not</strong> using React Native renderer. This is because this renderer needs to be run on iOS or Android operating system, so it would need to run on device or simulator.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="react-test-renderer">React Test Renderer<a href="#react-test-renderer" class="hash-link" aria-label="Direct link to React Test Renderer" title="Direct link to React Test Renderer"></a></h3><p>Instead, RNTL uses React Test Renderer which is a specialised renderer that allows rendering to pure JavaScript objects without access to mobile OS, and that can run in a Node.js environment using Jest (or any other JavaScript test runner).</p><p>Using React Test Renderer has pros and cons.</p><p>Benefits:</p><ul><li>tests can run on most CIs (linux, etc) and do not require a mobile device or emulator</li><li>faster test execution</li><li>light runtime environment</li></ul><p>Disadvantages:</p><ul><li>Tests do not execute native code</li><li>Tests are not aware of view state that would be managed by native components, e.g. focus, unmanaged text boxes, etc.</li><li>Assertions do not operate on native view hierarchy</li><li>Runtime behaviours are simulated, sometimes imperfectly</li></ul><p>It’s worth noting that React Testing Library (web one), works a bit different. While RTL also runs in Jest, it also has access to simulated browser DOM environment from jsdom package, so it can use a regular React DOM renderer. Unfortunately, there is no similar React Native runtime environment package. This is probably due to to the fact that while browser environment is well defined and highly standardised, the React Native environment is in constant evolution, in sync with the evolution of underlying OS-es. Maintaining such environment would require duplicating countless React Native behaviours, and keeping that in sync as React Native evolves.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="element-tree">Element tree<a href="#element-tree" class="hash-link" aria-label="Direct link to Element tree" title="Direct link to Element tree"></a></h3><p>Invoking <code>render()</code> function results in creation of an element tree. This is done internally by invoking <code>TestRenderer.create()</code> method. The output tree represents your React Native component tree, each node of that tree is an “instance” of some React component (to be more precise: each node represents a React fiber, and only class components have instances, while function components store the hook state using fiber).</p><p>These tree elements are represented by <code>ReactTestInstance</code> type:</p><div class="language-tsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-tsx codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">interface</span><span class="token plain"> </span><span class="token class-name">ReactTestInstance</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> type</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token maybe-class-name">ElementType</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> props</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain">propName</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">string</span><span class="token punctuation" style="color:#393A34">]</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">any</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> parent</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token maybe-class-name">ReactTestInstance</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">|</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">null</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> children</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token known-class-name class-name">Array</span><span class="token operator" style="color:#393A34"><</span><span class="token maybe-class-name">ReactTestInstance</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">|</span><span class="token plain"> </span><span class="token builtin">string</span><span class="token operator" style="color:#393A34">></span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Other props and methods</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Based on: <a href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-test-renderer/index.d.ts" target="_blank" rel="noopener noreferrer">https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-test-renderer/index.d.ts</a></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="host-and-composite-components">Host and composite components<a href="#host-and-composite-components" class="hash-link" aria-label="Direct link to Host and composite components" title="Direct link to Host and composite components"></a></h3><p>One of the most important aspects of the element tree is that it is composed of both host and composite components:</p><ul><li><a href="https://reactnative.dev/architecture/glossary#react-host-components-or-host-components" target="_blank" rel="noopener noreferrer">Host components</a> are components that will have direct counterparts in the native view tree. Typical examples are <code><View></code>, <code><Text></code> , <code><TextInput></code>, and <code><Image></code> from React Native. You can think of these as analogue of <code><div></code>, <code><span></code> etc on the Web. You can also create your own host views as native modules or import them from 3rd party libraries, like React Navigation or React Native Gesture Handler.</li><li><a href="https://reactnative.dev/architecture/glossary#react-composite-components" target="_blank" rel="noopener noreferrer">Composite components</a> are React code organisation units that exist only on the JavaScript side of your app. Typical examples are components you create (both function and class components), components imported from React Native (<code>View</code>, <code>Text</code>, etc) or from 3rd party packages.</li></ul><p>That might sound a bit confusing at first, since we put React Native’s <code>View</code> in both categories. There are actually two <code>View</code> components: composite one and host one. The relation between them is as follows:</p><ul><li>composite <code>View</code> is the type imported from <code>react-native</code> package. It’s a JavaScript component, which renders host <code>View</code> as its only child in the element tree.</li><li>host <code>View</code> , which you do not render directly. React Native takes the props you pass to the composite <code>View</code>, does some processing on them and passes them to host <code>View</code>.</li></ul><p>The part of the tree looks as follows:</p><div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">View</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"> (composite)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> * </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">View</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"> (host)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> * children prop passed in JSX</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Similar relation exists between other composite and host pairs: e.g. <code>Text</code> , <code>TextInput</code> and <code>Image</code> components:</p><div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">Text</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"> (composite)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> * </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">Text</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"> (host)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> * string (or mixed) content</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Not all React Native components are organised this way, e.g. when you use <code>Pressable</code> (or <code>TouchableOpacity</code>) there is no host <code>Pressable</code>, but composite <code>Pressable</code> is rendering a host <code>View</code> with certain props being set:</p><div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">Pressable</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"> (composite)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> * </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">View</span><span class="token tag" style="color:#00009f"> </span><span class="token tag attr-name" style="color:#00a4db">accessible</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#393A34">=</span><span class="token tag script language-javascript punctuation" style="color:#393A34">{</span><span class="token tag script language-javascript boolean" style="color:#36acaa">true</span><span class="token tag script language-javascript punctuation" style="color:#393A34">}</span><span class="token tag" style="color:#00009f"> </span><span class="token tag spread punctuation" style="color:#393A34">{</span><span class="token tag spread operator" style="color:#393A34">...</span><span class="token tag spread punctuation" style="color:#393A34">}</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"> (host)</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> * children prop passed in JSX</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h4 class="anchor anchorWithStickyNavbar_LWe7" id="differentiating-between-host-and-composite-elements">Differentiating between host and composite elements<a href="#differentiating-between-host-and-composite-elements" class="hash-link" aria-label="Direct link to Differentiating between host and composite elements" title="Direct link to Differentiating between host and composite elements"></a></h4><p>Any easy way to differentiate between host and composite elements is the <code>type</code> prop of <code>ReactTestInstance</code>:</p><ul><li>for host components it’s always a string value representing component name, e.g. <code>"View"</code></li><li>for composite components it’s a function or class corresponding to the component</li></ul><p>You can use the following code to check if given element is a host one:</p><div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">function</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">isHostElement</span><span class="token punctuation" style="color:#393A34">(</span><span class="token parameter literal-property property" style="color:#36acaa">element</span><span class="token parameter operator" style="color:#393A34">:</span><span class="token parameter"> </span><span class="token parameter maybe-class-name">ReactTestInstance</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword control-flow" style="color:#00009f">return</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">typeof</span><span class="token plain"> element</span><span class="token punctuation" style="color:#393A34">.</span><span class="token property-access">type</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">===</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">'string'</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="tree-nodes">Tree nodes<a href="#tree-nodes" class="hash-link" aria-label="Direct link to Tree nodes" title="Direct link to Tree nodes"></a></h3><p>We encourage you to only assert values on host views in your tests, because they represent the user interface view and controls that the user will be able to see and interact with. Users cannot see, or interact with, composite views as they exist purely in JavaScript domain and do not generate any visible UI.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="asserting-props">Asserting props<a href="#asserting-props" class="hash-link" aria-label="Direct link to Asserting props" title="Direct link to Asserting props"></a></h4><p>As an example, if you make assertions on a <code>style</code> prop of a composite element, there is no guarantee that the style will be visible to the user, as the component author can forget to pass this prop to some underlying <code>View</code> or other host component. Similarly <code>onPress</code> event handler on a composite prop can be unreachable by the user.</p><div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#d73a49">ForgotToPassPropsButton</span><span class="token punctuation" style="color:#393A34">(</span><span class="token parameter punctuation" style="color:#393A34">{</span><span class="token parameter"> title</span><span class="token parameter punctuation" style="color:#393A34">,</span><span class="token parameter"> onPress</span><span class="token parameter punctuation" style="color:#393A34">,</span><span class="token parameter"> style </span><span class="token parameter punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword control-flow" style="color:#00009f">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">Pressable</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag class-name" style="color:#00009f">Text</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain">title</span><span class="token punctuation" style="color:#393A34">}</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag class-name" style="color:#00009f">Text</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain-text"> </span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag class-name" style="color:#00009f">Pressable</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>In the above example user defined components accepts both <code>onPress</code> and <code>style</code> props but does not pass it (through <code>Pressable</code>) to host views, so these props will not affect the user interface. Additionally, React Native and other libraries might pass some of the props under different names or transform their values between composite and host components.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="tree-navigation">Tree navigation<a href="#tree-navigation" class="hash-link" aria-label="Direct link to Tree navigation" title="Direct link to Tree navigation"></a></h3><div class="theme-admonition theme-admonition-caution alert alert--warning admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>caution</div><div class="admonitionContent_S0QG"><p>You should avoid navigating over element tree, as this makes your testing code fragile and may result in false positives. This section is more relevant for people how want to contribute to our codebase.</p></div></div><p>When navigating a tree of react elements using <code>parent</code> or <code>children</code> props of a <code>ReactTestInstance</code> element, you will encounter both host and composite elements. You should be careful when navigating the element tree, as the tree structure for 3rd party components and change independently from your code and cause unexpected test failures.</p><p>Inside RNTL we have various tree navigation helpers: <code>getHostParent</code>, <code>getHostChildren</code>, etc. These are intentionally not exported as using them is not a recommended practice.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="queries">Queries<a href="#queries" class="hash-link" aria-label="Direct link to Queries" title="Direct link to Queries"></a></h3><p>Most of the Testing Library queries return host components, in order to encourage best practices described above.</p><p>At this stage, there are some noteworthy exceptions:</p><ul><li><code>*ByText</code> queries returns composite <code>Text</code> element</li><li><code>*ByDisplayValue</code> queries returns composite <code>TextInput</code> element</li><li><code>*ByPlaceholderText</code> queries returns composite <code>TextInput</code> element</li></ul><p>This will change in the near future, as we make efforts for all queries to return host components. Meanwhile it shouldn't be a huge issue, as composite <code>Text</code> and <code>TextInput</code>generally pass their props down to host counterparts.</p><p>Additionally, <code>UNSAFE_*ByType</code> and <code>UNSAFE_*ByProps</code> queries can return both host and composite components depending on used predicates. They are marked as unsafe precisely because testing composite components makes your test more fragile.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/callstack/react-native-testing-library/blob/main/website/docs/TestingEnvironment.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--prev" href="/react-native-testing-library/docs/eslint-plugin-testing-library"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">ESLint Plugin Testing Library Compatibility</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/react-native-testing-library/docs/understanding-act"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Understanding Act function</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#testing-environment" class="table-of-contents__link toc-highlight">Testing Environment</a><ul><li><a href="#react-renderers" class="table-of-contents__link toc-highlight">React renderers</a></li><li><a href="#react-test-renderer" class="table-of-contents__link toc-highlight">React Test Renderer</a></li><li><a href="#element-tree" class="table-of-contents__link toc-highlight">Element tree</a></li><li><a href="#host-and-composite-components" class="table-of-contents__link toc-highlight">Host and composite components</a></li><li><a href="#tree-nodes" class="table-of-contents__link toc-highlight">Tree nodes</a></li><li><a href="#tree-navigation" class="table-of-contents__link toc-highlight">Tree navigation</a></li><li><a href="#queries" class="table-of-contents__link toc-highlight">Queries</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/react-native-testing-library/docs/getting-started">Getting started</a></li><li class="footer__item"><a class="footer__link-item" href="/react-native-testing-library/docs/api">API</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="http://stackoverflow.com/questions/tagged/react-native-testing-library" target="_blank" rel="noopener noreferrer" class="footer__link-item">Stack Overflow<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://discord.gg/QbGezWe" target="_blank" rel="noopener noreferrer" class="footer__link-item">Discord Channel<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/callstack/react-native-testing-library" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://github.com/callstack/react-native-testing-library" target="_blank" rel="noopener noreferrer" class="footer__link-item">Star<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2023 Callstack Open Source</div></div></div></footer></div>
|
||
<script src="/react-native-testing-library/assets/js/runtime~main.e63caa38.js"></script>
|
||
<script src="/react-native-testing-library/assets/js/main.0d0265df.js"></script>
|
||
</body>
|
||
</html> |