skills/callstack__react-native-testing-library
1
0
Fork 0
mirror of https://github.com/callstack/react-native-testing-library.git synced 2026-09-18 23:09:04 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
06e109a8e4aa50e7331e7ee9cafafa8a844f65ea
callstack__react-native-tes…/docs/api/queries.html
T
github-actions[bot] 06e109a8e4 deploy: b409485cd2
2026-01-16 13:01:34 +00:00

400 lines
160 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en">
<head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Queries - React Native Testing Library</title>
<script>{;const saved = localStorage.getItem('rspress-theme-appearance');const preferDark = window.matchMedia('(prefers-color-scheme: dark)').matches;const isDark = !saved || saved === 'auto' ? preferDark : saved === 'dark';document.documentElement.classList.toggle('dark', isDark);document.documentElement.classList.toggle('rp-dark', isDark);document.documentElement.style.colorScheme = isDark ? 'dark' : 'light';}</script>
<link href="/react-native-testing-library/static/css/styles.73041e5c.css" rel="stylesheet">
<script defer src="/react-native-testing-library/static/js/styles.60254868.js"></script>
<script defer src="/react-native-testing-library/static/js/lib-react.c776e48d.js"></script>
<script defer src="/react-native-testing-library/static/js/lib-router.0998d45d.js"></script>
<script defer src="/react-native-testing-library/static/js/8712.b675ec06.js"></script>
<script defer src="/react-native-testing-library/static/js/index.6c2873da.js"></script>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="generator" content="Rspress v2.0.0-rc.5">
<meta property="og:url" content="https://callstack.github.io/react-native-testing-library/">
<meta property="og:type" content="website">
<meta property="og:title" content="Queries - React Native Testing Library">
<meta property="og:description" content="Helps you to write better tests with less effort.">
<link rel="icon" href="/react-native-testing-library/logo-light.png">
<meta name="description" content="Helps you to write better tests with less effort."></head>
<body>
<div id="__rspress_root"><link rel="preload" as="image" href="/react-native-testing-library/img/logo-light.svg"/><link rel="preload" as="image" href="/react-native-testing-library/img/logo-dark.svg"/><link rel="preload" as="image" href="/react-native-testing-library/static/image/abstract-atom.4eca0300.avif"/><header class="rp-nav"><div class="rp-nav__left"><div class="rp-nav__title"><a href="/react-native-testing-library/" class="rp-nav__title__link rp-link"><div class="rp-nav__title__logo"><img src="/react-native-testing-library/img/logo-light.svg" alt="logo" id="logo" class="rspress-logo rp-nav__title__logo-image rp-nav__title__logo-image--light"/><img src="/react-native-testing-library/img/logo-dark.svg" alt="logo" id="logo" class="rspress-logo rp-nav__title__logo-image rp-nav__title__logo-image--dark"/></div></a></div></div><div class="rp-nav__right"><button class="rp-search-button"><div class="rp-search-button__content"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTE0LjY2NjUgMTQuNjY2NEgxMy4zMzM1VjEzLjMzMzNIMTQuNjY2NVYxNC42NjY0Wk0xMy4zMzM1IDEzLjMzMzNIMTIuMDAwNVYxMi4wMDAzSDEzLjMzMzVWMTMuMzMzM1pNOS4zMzM1IDEyLjAwMDNINC4wMDA0OVYxMC42NjY0SDkuMzMzNVYxMi4wMDAzWk0xMi4wMDA1IDEyLjAwMDNIMTAuNjY2NVYxMC42NjY0SDEyLjAwMDVWMTIuMDAwM1pNNC4wMDA0OSAxMC42NjY0SDIuNjY2NVY5LjMzMzM0SDQuMDAwNDlWMTAuNjY2NFpNMTAuNjY2NSAxMC42NjY0SDkuMzMzNVY5LjMzMzM0SDEwLjY2NjVWMTAuNjY2NFpNMi42NjY1IDkuMzMzMzRIMS4zMzM1VjQuMDAwMzRIMi42NjY1VjkuMzMzMzRaTTEyLjAwMDUgOS4zMzMzNEgxMC42NjY1VjQuMDAwMzRIMTIuMDAwNVY5LjMzMzM0Wk00LjAwMDQ5IDQuMDAwMzRIMi42NjY1VjIuNjY2MzVINC4wMDA0OVY0LjAwMDM0Wk0xMC42NjY1IDQuMDAwMzRIOS4zMzM1VjIuNjY2MzVIMTAuNjY2NVY0LjAwMDM0Wk05LjMzMzUgMi42NjYzNUg0LjAwMDQ5VjEuMzMzMzRIOS4zMzM1VjIuNjY2MzVaIiBmaWxsPSIjODM4Mjg5Ii8+Cjwvc3ZnPgo=" alt="" class="rp-search-button__icon"/><span class="rp-search-button__word">Search</span></div><div class="rp-search-button__hotkey" style="opacity:0"><span></span><span>K</span></div></button><div class="rp-search-button--mobile"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTE0LjY2NjUgMTQuNjY2NEgxMy4zMzM1VjEzLjMzMzNIMTQuNjY2NVYxNC42NjY0Wk0xMy4zMzM1IDEzLjMzMzNIMTIuMDAwNVYxMi4wMDAzSDEzLjMzMzVWMTMuMzMzM1pNOS4zMzM1IDEyLjAwMDNINC4wMDA0OVYxMC42NjY0SDkuMzMzNVYxMi4wMDAzWk0xMi4wMDA1IDEyLjAwMDNIMTAuNjY2NVYxMC42NjY0SDEyLjAwMDVWMTIuMDAwM1pNNC4wMDA0OSAxMC42NjY0SDIuNjY2NVY5LjMzMzM0SDQuMDAwNDlWMTAuNjY2NFpNMTAuNjY2NSAxMC42NjY0SDkuMzMzNVY5LjMzMzM0SDEwLjY2NjVWMTAuNjY2NFpNMi42NjY1IDkuMzMzMzRIMS4zMzM1VjQuMDAwMzRIMi42NjY1VjkuMzMzMzRaTTEyLjAwMDUgOS4zMzMzNEgxMC42NjY1VjQuMDAwMzRIMTIuMDAwNVY5LjMzMzM0Wk00LjAwMDQ5IDQuMDAwMzRIMi42NjY1VjIuNjY2MzVINC4wMDA0OVY0LjAwMDM0Wk0xMC42NjY1IDQuMDAwMzRIOS4zMzM1VjIuNjY2MzVIMTAuNjY2NVY0LjAwMDM0Wk05LjMzMzUgMi42NjYzNUg0LjAwMDQ5VjEuMzMzMzRIOS4zMzM1VjIuNjY2MzVaIiBmaWxsPSIjODM4Mjg5Ii8+Cjwvc3ZnPgo=" alt=""/></div><ul class="rp-nav-menu rp-nav-menu--right"><li class="rp-nav-menu__item rp-nav-menu__item--active rspress-nav-menu-item rspress-nav-menu-item-active"><a href="/react-native-testing-library/docs/start/intro" class="rp-nav-menu__item__container rp-link">Docs</a></li><li class="rp-nav-menu__item rspress-nav-menu-item"><a href="/react-native-testing-library/cookbook/" class="rp-nav-menu__item__container rp-link">Cookbook</a></li><li class="rp-nav-menu__item rspress-nav-menu-item"><a href="https://github.com/callstack/react-native-testing-library/tree/main/examples" target="_blank" rel="noopener noreferrer" class="rp-nav-menu__item__container rp-link">Examples</a></li></ul><div class="rp-nav__others"><div class="rp-nav-menu__divider"></div><li class="rp-nav-menu__item"><div class="rp-nav-menu__item__container">13.x<img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA4LjVINy41VjkuNUg2LjVWMTAuNUg1LjVWOS41SDQuNVY4LjVINS41VjIuNUg2LjVWOC41Wk00LjUgOC41SDMuNVY3LjVINC41VjguNVpNOC41IDguNUg3LjVWNy41SDguNVY4LjVaTTMuNSA2LjVWNy41SDIuNVY2LjVIMy41Wk05LjUgNy41SDguNVY2LjVIOS41VjcuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt="" class="rp-nav-menu__item__icon"/></div><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--center"><li class="rp-hover-group__item" style="padding-left:8px" data-depth="0"><a href="/react-native-testing-library/12.x/docs/api/queries" class="rp-hover-group__item__link rp-link" aria-label="12.x">12.x</a></li><li class="rp-hover-group__item rp-hover-group__item--active" style="padding-left:8px" data-depth="0"><a href="/react-native-testing-library/api/queries" class="rp-hover-group__item__link rp-link" aria-label="13.x">13.x</a></li><li class="rp-hover-group__item" style="padding-left:8px" data-depth="0"><a href="/react-native-testing-library/14.x/docs/api/queries" class="rp-hover-group__item__link rp-link" aria-label="14.x">14.x</a></li></ul></li><div class="rspress-nav-appearance"><div class="rp-p-1 rp-border rp-border-solid rp-border-gray-300 rp-text-gray-400 rp-cursor-pointer rp-rounded-md rp-transition-all rp-duration-300 rp-w-7 rp-h-7"><svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" viewBox="0 0 24 24"><path fill="currentColor" d="M18 22H8v-2h10zM8 20H6v-2h2zm12 0h-2v-2h2zM6 18H4v-2h2zm16 0h-2v-4h-2v-2h2v-2h2zM4 16H2V6h2zm14 0h-6v-2h6zm-6-2h-2v-2h2zm-2-2H8V6h2zM6 6H4V4h2zm8-2h-2v2h-2V4H6V2h8z"></path></svg></div></div><div class="rp-social-links"><a href="https://github.com/callstack/react-native-testing-library" target="_blank" rel="noopener noreferrer" class="rp-social-links__item"><div class="rp-social-links__icon"><div class="rp-social-links__icon"><svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg></div></div></a><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--right"></ul></div></div><button aria-label="mobile hamburger" class="rp-nav-hamburger rp-nav-hamburger__sm"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xIDlIN1YxNUgxVjlaTTMgMTFWMTNINVYxMUgzWk05IDlIMTVWMTVIOVY5Wk0xMSAxMVYxM0gxM1YxMUgxMVpNMTcgOUgyM1YxNUgxN1Y5Wk0xOSAxMVYxM0gyMVYxMUgxOVoiIGZpbGw9IiM4MzgyODkiLz4KPC9zdmc+Cg==" alt=""/></button><button aria-label="mobile hamburger" class="rp-nav-hamburger rp-nav-hamburger__md"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xIDlIN1YxNUgxVjlaTTMgMTFWMTNINVYxMUgzWk05IDlIMTVWMTVIOVY5Wk0xMSAxMVYxM0gxM1YxMUgxMVpNMTcgOUgyM1YxNUgxN1Y5Wk0xOSAxMVYxM0gyMVYxMUgxOVoiIGZpbGw9IiM4MzgyODkiLz4KPC9zdmc+Cg==" alt=""/><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--right"><div class="rp-nav-menu__others-mobile__container"><div class="rp-nav-hamburger__md__hover-group"><div class="rp-nav-screen-appearance"><div class="rp-nav-screen-appearance__left">Theme</div><div class="rp-nav-screen-appearance__right"></div></div><li class="rp-nav-menu__item"><div class="rp-nav-menu__item__container">13.x<img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA4LjVINy41VjkuNUg2LjVWMTAuNUg1LjVWOS41SDQuNVY4LjVINS41VjIuNUg2LjVWOC41Wk00LjUgOC41SDMuNVY3LjVINC41VjguNVpNOC41IDguNUg3LjVWNy41SDguNVY4LjVaTTMuNSA2LjVWNy41SDIuNVY2LjVIMy41Wk05LjUgNy41SDguNVY2LjVIOS41VjcuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt="" class="rp-nav-menu__item__icon"/></div><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--center"><li class="rp-hover-group__item" style="padding-left:8px" data-depth="0"><a href="/react-native-testing-library/12.x/docs/api/queries" class="rp-hover-group__item__link rp-link" aria-label="12.x">12.x</a></li><li class="rp-hover-group__item rp-hover-group__item--active" style="padding-left:8px" data-depth="0"><a href="/react-native-testing-library/api/queries" class="rp-hover-group__item__link rp-link" aria-label="13.x">13.x</a></li><li class="rp-hover-group__item" style="padding-left:8px" data-depth="0"><a href="/react-native-testing-library/14.x/docs/api/queries" class="rp-hover-group__item__link rp-link" aria-label="14.x">14.x</a></li></ul></li><div class="rp-nav-screen-divider"></div><div class="rp-social-links"><a href="https://github.com/callstack/react-native-testing-library" target="_blank" rel="noopener noreferrer" class="rp-social-links__item"><div class="rp-social-links__icon"><div class="rp-social-links__icon"><svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg></div></div></a><ul class="rp-hover-group rp-hover-group--hidden rp-hover-group--right"></ul></div></div></div></ul></button></div></header><div class="rp-doc-layout__menu"><div class="rp-sidebar-menu"><button type="button" class="rp-sidebar-menu__left"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTIwIDE4SDRWMTZIMjBWMThaTTIwIDEzSDRWMTFIMjBWMTNaTTIwIDhINFY2SDIwVjhaIiBmaWxsPSIjODM4Mjg5Ii8+Cjwvc3ZnPgo=" alt=""/><span>Menu</span></button><button type="button" disabled="" class="rp-sidebar-menu__right"><span>Contents</span><svg width="14" height="14" class="rp-progress-circle"><circle cx="7" cy="7" r="6" stroke-linecap="round" fill="none" stroke="var(--rp-c-divider-light)" stroke-width="2"></circle><circle cx="7" cy="7" r="6" stroke-linecap="round" fill="none" stroke="var(--rp-c-brand)" stroke-width="2" stroke-dasharray="37.69911184307752" stroke-dashoffset="37.69911184307752" transform="rotate(-90 7 7)" style="transition:stroke-dashoffset 0.3s"></circle></svg></button></div></div><div class="rp-doc-layout__container"><aside class="rp-doc-layout__sidebar rp-scrollbar"><div class="rp-sidebar-item rp-sidebar-group" style="padding-left:12px" data-depth="0"><div class="rp-sidebar-item__left"><span>Getting started</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(90deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:1fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/start/intro" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Introduction</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/start/quick-start" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Quick Start</span></div><div class="rp-sidebar-item__right"></div></a></div></div><div class="rp-sidebar-item rp-sidebar-group" style="padding-left:12px" data-depth="0"><div class="rp-sidebar-item__left"><span>API reference</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(90deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:1fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/api/render" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Render function</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/screen" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Screen object</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/queries" class="rp-sidebar-item rp-sidebar-item--active rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Queries</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/jest-matchers" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Jest Matchers</span></div><div class="rp-sidebar-item__right"></div></a><div class="rp-sidebar-item rp-sidebar-group rp-sidebar-item--group-item" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Triggering events</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(90deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:1fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/api/events/fire-event" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>Fire Event</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/events/user-event" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>User Event</span></div><div class="rp-sidebar-item__right"></div></a></div></div><div class="rp-sidebar-item rp-sidebar-group rp-sidebar-item--group-item" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Miscellaneous</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(90deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:1fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/api/misc/accessibility" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>Accessibility</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/misc/async" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>Async utilities</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/misc/config" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>Config</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/misc/other" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>Other</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/api/misc/render-hook" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>Render Hook</span></div><div class="rp-sidebar-item__right"></div></a></div></div></div></div><div class="rp-sidebar-item rp-sidebar-group" style="padding-left:12px" data-depth="0"><div class="rp-sidebar-item__left"><span>Guides</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(90deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:1fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/guides/how-to-query" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>How to Query</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/guides/react-19" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>React 19</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/guides/troubleshooting" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Troubleshooting</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/guides/faq" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>FAQ</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/guides/community-resources" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Community Resources</span></div><div class="rp-sidebar-item__right"></div></a></div></div><div class="rp-sidebar-item rp-sidebar-group" style="padding-left:12px" data-depth="0"><div class="rp-sidebar-item__left"><span>Advanced Guides</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(90deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:1fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/advanced/testing-env" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Testing Environment</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/advanced/third-party-integration" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Third-party Integration</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/advanced/understanding-act" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Understanding Act</span></div><div class="rp-sidebar-item__right"></div></a></div></div><div class="rp-sidebar-item rp-sidebar-group" style="padding-left:12px" data-depth="0"><div class="rp-sidebar-item__left"><span>Migration Guides</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(0deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:0fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/migration/v13" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>v13 Migration</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/migration/jest-matchers" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Jest Matchers</span></div><div class="rp-sidebar-item__right"></div></a><div class="rp-sidebar-item rp-sidebar-group rp-sidebar-item--group-item" style="padding-left:calc(12px * 1 + 12px)" data-depth="1"><div class="rp-sidebar-item__left"><span>Previous versions</span></div><div class="rp-sidebar-item__right"><div style="cursor:pointer;transition:transform 0.2s ease-out;transform:rotate(0deg)"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt=""/></div></div></div><div style="display:grid;grid-template-rows:0fr;transition:grid-template-rows 0.2s ease-out"><div style="overflow:hidden"><a href="/react-native-testing-library/docs/migration/previous/v12" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>v12</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/migration/previous/v11" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>v11</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/migration/previous/v9" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>v9</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/migration/previous/v7" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>v7</span></div><div class="rp-sidebar-item__right"></div></a><a href="/react-native-testing-library/docs/migration/previous/v2" class="rp-sidebar-item rp-sidebar-item--group-item rp-link" style="padding-left:calc(12px * 2 + 12px)" data-depth="2"><div class="rp-sidebar-item__left"><span>v2</span></div><div class="rp-sidebar-item__right"></div></a></div></div></div></div></aside><div class="rp-doc-layout__doc"><main class="rp-doc-layout__doc-container"><div class="rp-doc rspress-doc"><!--$--><h1 class="rp-toc-include" id="queries"><a href="#queries" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Queries</h1>
<p>Queries are one of the main building blocks for the React Native Testing Library. They enable you to find relevant elements in the element tree, which represents your application&#x27;s user interface when running under tests.</p>
<h2 class="rp-toc-include" id="accessing-queries"><a href="#accessing-queries" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Accessing queries</h2>
<p>All queries described below are accessible in two main ways: through the <code>screen</code> object or by capturing the <code>render</code> function call result.</p>
<h3 class="rp-toc-include" id="using-screen-object"><a href="#using-screen-object" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Using <code>screen</code> object</h3>
<div class="rp-codeblock language-tsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="tsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">test</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;accessing queries using &quot;screen&quot; object&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> () </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-token-function)"> render</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-keyword)">...</span><span style="color:var(--shiki-foreground)">);</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByRole</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&quot;button&quot;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> { name</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-string-expression)"> &quot;Start&quot;</span><span style="color:var(--shiki-foreground)"> });</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">})</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>The modern and recommended way of accessing queries is to use the <code>screen</code> object exported by the <code>@testing-library/react-native</code> package. This object will contain methods of all available queries bound to the most recently rendered UI.</p>
<h3 class="rp-toc-include" id="using-render-result"><a href="#using-render-result" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Using <code>render</code> result</h3>
<div class="rp-codeblock language-tsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="tsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">test</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;accessing queries using &quot;render&quot; result&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> () </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)"> const</span><span style="color:var(--shiki-foreground)"> { </span><span style="color:var(--shiki-token-constant)">getByRole</span><span style="color:var(--shiki-foreground)"> } </span><span style="color:var(--shiki-token-keyword)">=</span><span style="color:var(--shiki-token-function)"> render</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-keyword)">...</span><span style="color:var(--shiki-foreground)">);</span></span>
<span class="line"><span style="color:var(--shiki-token-function)"> getByRole</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&quot;button&quot;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> { name</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-string-expression)"> &quot;Start&quot;</span><span style="color:var(--shiki-foreground)"> });</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">})</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>The classic way is to capture query functions, as they are returned from the <code>render</code> function call. This provides access to the same functions as in the case of the <code>screen</code> object.</p>
<h2 class="rp-toc-include" id="query-parts"><a href="#query-parts" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Query parts</h2>
<p>Each query is composed of two parts: variant and predicate, which are separated by the <code>by</code> word in the middle of the name.</p>
<p>Consider the following query:</p>
<div class="rp-codeblock language-txt"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="txt"><code><span class="line"><span>getByRole()</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>For this query, <code>getBy*</code> is the query variant, and <code>*ByRole</code> is the predicate.</p>
<h2 class="rp-toc-include" id="query-variant"><a href="#query-variant" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Query variant</h2>
<p>The query variants describe the expected number (and timing) of matching elements, so they differ in their return type.</p>
<div class="rp-table-scroll-container rp-scrollbar"><table><thead><tr><th>Variant</th><th>Assertion</th><th>Return type</th><th>Is Async?</th></tr></thead><tbody><tr><td><a href="/react-native-testing-library/docs/api/queries#get-by" class="rp-link"><code>getBy*</code></a></td><td>Exactly one matching element</td><td><code>ReactTestInstance</code></td><td>No</td></tr><tr><td><a href="/react-native-testing-library/docs/api/queries#get-all-by" class="rp-link"><code>getAllBy*</code></a></td><td>At least one matching element</td><td><code>Array&lt;ReactTestInstance&gt;</code></td><td>No</td></tr><tr><td><a href="/react-native-testing-library/docs/api/queries#query-by" class="rp-link"><code>queryBy*</code></a></td><td>Zero or one matching element</td><td><code>ReactTestInstance | null</code></td><td>No</td></tr><tr><td><a href="/react-native-testing-library/docs/api/queries#query-all-by" class="rp-link"><code>queryAllBy*</code></a></td><td>No assertion</td><td><code>Array&lt;ReactTestInstance&gt;</code></td><td>No</td></tr><tr><td><a href="/react-native-testing-library/docs/api/queries#find-by" class="rp-link"><code>findBy*</code></a></td><td>Exactly one matching element</td><td><code>Promise&lt;ReactTestInstance&gt;</code></td><td>Yes</td></tr><tr><td><a href="/react-native-testing-library/docs/api/queries#find-all-by" class="rp-link"><code>findAllBy*</code></a></td><td>At least one matching element</td><td><code>Promise&lt;Array&lt;ReactTestInstance&gt;&gt;</code></td><td>Yes</td></tr></tbody></table></div>
<p>Queries work as implicit assertions on the number of matching elements and will throw an error when the assertion fails.</p>
<h3 class="rp-toc-include" id="get-by"><a href="#get-by" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>getBy*</code> queries</h3>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByX</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-keyword)">...</span><span style="color:var(--shiki-foreground)">): ReactTestInstance</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p><code>getBy*</code> queries return the single matching element for a query, and throw an error if no elements match or if more than one match is found. If you need to find more than one element, then use <code>getAllBy</code>.</p>
<h3 class="rp-toc-include" id="get-all-by"><a href="#get-all-by" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>getAllBy*</code> queries</h3>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getAllByX</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-keyword)">...</span><span style="color:var(--shiki-foreground)">): ReactTestInstance[]</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p><code>getAllBy*</code> queries return an array of all matching elements for a query and throw an error if no elements match.</p>
<h3 class="rp-toc-include" id="query-by"><a href="#query-by" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>queryBy*</code> queries</h3>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">queryByX</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-keyword)">...</span><span style="color:var(--shiki-foreground)">): ReactTestInstance </span><span style="color:var(--shiki-token-keyword)">|</span><span style="color:var(--shiki-token-constant)"> null</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p><code>queryBy*</code> queries return the first matching node for a query, and return <code>null</code> if no elements match. This is useful for asserting an element that is not present. This throws if more than one match is found (use <code>queryAllBy</code> instead).</p>
<h3 class="rp-toc-include" id="query-all-by"><a href="#query-all-by" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>queryAllBy*</code> queries</h3>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">queryAllByX</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-keyword)">...</span><span style="color:var(--shiki-foreground)">): ReactTestInstance[]</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p><code>queryAllBy*</code> queries return an array of all matching nodes for a query and return an empty array (<code>[]</code>) when no elements match.</p>
<h3 class="rp-toc-include" id="find-by"><a href="#find-by" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>findBy*</code> queries</h3>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">findByX</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)"> ...</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> waitForOptions</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> timeout?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> number</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> interval?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> number</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): </span><span style="color:var(--shiki-token-constant)">Promise</span><span style="color:var(--shiki-token-keyword)">&lt;</span><span style="color:var(--shiki-foreground)">ReactTestInstance</span><span style="color:var(--shiki-token-keyword)">&gt;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p><code>findBy*</code> queries return a promise which resolves when a matching element is found. The promise is rejected if no elements match or if more than one match is found after a default timeout of 1000 ms. If you need to find more than one element use <code>findAllBy*</code> queries.</p>
<h3 class="rp-toc-include" id="find-all-by"><a href="#find-all-by" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>findAllBy*</code> queries</h3>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">findAllByX</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)"> ...</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> waitForOptions</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> timeout?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> number</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> interval?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> number</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): </span><span style="color:var(--shiki-token-constant)">Promise</span><span style="color:var(--shiki-token-keyword)">&lt;</span><span style="color:var(--shiki-foreground)">ReactTestInstance[]</span><span style="color:var(--shiki-token-keyword)">&gt;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p><code>findAllBy*</code> queries return a promise which resolves to an array of matching elements. The promise is rejected if no elements match after a default timeout of 1000 ms.</p>
<div class="rp-callout rp-callout--info"><div class="rp-callout__title">Info</div><div class="rp-callout__content"><p>
<code>findBy*</code> and <code>findAllBy*</code> queries accept optional <code>waitForOptions</code> object arguments, which can contain <code>timeout</code>, <code>interval</code> and <code>onTimeout</code> properties which have the same meaning as respective options for <a href="/react-native-testing-library/docs/api/misc/async#waitfor" class="rp-link"><code>waitFor</code></a> function.</p></div></div>
<div class="rp-callout rp-callout--info"><div class="rp-callout__title">Info</div><div class="rp-callout__content"><p>
In cases when your <code>findBy*</code> and <code>findAllBy*</code> queries throw when unable to find matching elements, it is helpful to pass <code>onTimeout: () =&gt; { screen.debug(); }</code> callback using the <code>waitForOptions</code> parameter.</p></div></div>
<h2 class="rp-toc-include" id="query-predicates"><a href="#query-predicates" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Query predicates</h2>
<p><em>Note: most methods like this one return a <a href="https://reactjs.org/docs/test-renderer.html#testinstance" target="_blank" rel="noopener noreferrer" class="rp-link"><code>ReactTestInstance</code></a> with following properties that you may be interested in:</em></p>
<div class="rp-codeblock language-typescript"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="typescript"><code><span class="line"><span style="color:var(--shiki-token-keyword)">type</span><span style="color:var(--shiki-token-function)"> ReactTestInstance</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> type</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-token-keyword)"> |</span><span style="color:var(--shiki-token-function)"> Function</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> props</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> { [propName</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">]</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> any</span><span style="color:var(--shiki-foreground)"> };</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> parent</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-function)"> ReactTestInstance</span><span style="color:var(--shiki-token-keyword)"> |</span><span style="color:var(--shiki-token-constant)"> null</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> children</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-function)"> Array</span><span style="color:var(--shiki-foreground)">&lt;</span><span style="color:var(--shiki-token-function)">ReactTestInstance</span><span style="color:var(--shiki-token-keyword)"> |</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">&gt;;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">};</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h3 class="rp-toc-include" id="by-role"><a href="#by-role" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>*ByRole</code></h3>
<blockquote>
<p>getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole</p>
</blockquote>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByRole</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> role: TextMatch</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> options</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> name?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> TextMatch</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> disabled</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> boolean</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> selected?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> checked?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean </span><span style="color:var(--shiki-token-keyword)">|</span><span style="color:var(--shiki-token-string-expression)"> &#x27;mixed&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> busy?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> expanded?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> value</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> min?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> number;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> max</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> number;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> now</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> number;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> text</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> TextMatch;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): ReactTestInstance;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Returns a <code>ReactTestInstance</code> with matching <code>role</code> or <code>accessibilityRole</code> prop.</p>
<div class="rp-callout rp-callout--info"><div class="rp-callout__title">Info</div><div class="rp-callout__content"><p>
In order for <code>*ByRole</code> queries to match an element it needs to be considered an accessibility element:</p><ol>
<li><code>Text</code>, <code>TextInput</code> and <code>Switch</code> host elements are these by default.</li>
<li><code>View</code> host elements need an explicit <a href="https://reactnative.dev/docs/accessibility#accessible" target="_blank" rel="noopener noreferrer" class="rp-link"><code>accessible</code></a> prop set to <code>true</code></li>
<li>Some React Native composite components like <code>Pressable</code> &amp; <code>TouchableOpacity</code> render host <code>View</code> element with <code>accessible</code> prop already set.</li>
</ol></div></div>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> &lt;</span><span style="color:var(--shiki-token-constant)">Pressable</span><span style="color:var(--shiki-token-function)"> accessibilityRole</span><span style="color:var(--shiki-token-keyword)">=</span><span style="color:var(--shiki-token-string-expression)">&quot;button&quot;</span><span style="color:var(--shiki-token-function)"> disabled</span><span style="color:var(--shiki-foreground)">&gt;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> &lt;</span><span style="color:var(--shiki-token-constant)">Text</span><span style="color:var(--shiki-foreground)">&gt;Hello&lt;/</span><span style="color:var(--shiki-token-constant)">Text</span><span style="color:var(--shiki-foreground)">&gt;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> &lt;/</span><span style="color:var(--shiki-token-constant)">Pressable</span><span style="color:var(--shiki-foreground)">&gt;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByRole</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;button&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element2</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByRole</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;button&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> { name</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-string-expression)"> &#x27;Hello&#x27;</span><span style="color:var(--shiki-foreground)"> });</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element3</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByRole</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;button&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> { name</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-string-expression)"> &#x27;Hello&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> disabled</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> true</span><span style="color:var(--shiki-foreground)"> });</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h4 class="rp-toc-include" id="by-role-options"><a href="#by-role-options" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Options</h4>
<ul>
<li>
<p><code>name</code>: Finds an element with given <code>role</code>/<code>accessibilityRole</code> and an accessible name (= accessability label or text content).</p>
</li>
<li>
<p><code>disabled</code>: You can filter elements by their disabled state (coming either from <code>aria-disabled</code> prop or <code>accessbilityState.disabled</code> prop). The possible values are <code>true</code> or <code>false</code>. Querying <code>disabled: false</code> will also match elements with <code>disabled: undefined</code> (see the <a href="https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State" target="_blank" rel="noopener noreferrer" class="rp-link">wiki</a> for more details).</p>
<ul>
<li>See <a href="https://reactnative.dev/docs/accessibility#accessibilitystate" target="_blank" rel="noopener noreferrer" class="rp-link">React Native&#x27;s accessibilityState</a> docs to learn more about the <code>disabled</code> state.</li>
<li>This option can alternatively be expressed using the <a href="/react-native-testing-library/docs/api/jest-matchers#tobeenabled" class="rp-link"><code>toBeEnabled()</code> / <code>toBeDisabled()</code></a> Jest matchers.</li>
</ul>
</li>
<li>
<p><code>selected</code>: You can filter elements by their selected state (coming either from <code>aria-selected</code> prop or <code>accessbilityState.selected</code> prop). The possible values are <code>true</code> or <code>false</code>. Querying <code>selected: false</code> will also match elements with <code>selected: undefined</code> (see the <a href="https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State" target="_blank" rel="noopener noreferrer" class="rp-link">wiki</a> for more details).</p>
<ul>
<li>See <a href="https://reactnative.dev/docs/accessibility#accessibilitystate" target="_blank" rel="noopener noreferrer" class="rp-link">React Native&#x27;s accessibilityState</a> docs to learn more about the <code>selected</code> state.</li>
<li>This option can alternatively be expressed using the <a href="/react-native-testing-library/docs/api/jest-matchers#tobeselected" class="rp-link"><code>toBeSelected()</code></a> Jest matcher.</li>
</ul>
</li>
</ul>
<ul>
<li>
<p><code>checked</code>: You can filter elements by their checked state (coming either from <code>aria-checked</code> prop or <code>accessbilityState.checked</code> prop). The possible values are <code>true</code>, <code>false</code>, or <code>&quot;mixed&quot;</code>.</p>
<ul>
<li>See <a href="https://reactnative.dev/docs/accessibility#accessibilitystate" target="_blank" rel="noopener noreferrer" class="rp-link">React Native&#x27;s accessibilityState</a> docs to learn more about the <code>checked</code> state.</li>
<li>This option can alternatively be expressed using the <a href="/react-native-testing-library/docs/api/jest-matchers#tobechecked" class="rp-link"><code>toBeChecked()</code> / <code>toBePartiallyChecked()</code></a> Jest matchers.</li>
</ul>
</li>
<li>
<p><code>busy</code>: You can filter elements by their busy state (coming either from <code>aria-busy</code> prop or <code>accessbilityState.busy</code> prop). The possible values are <code>true</code> or <code>false</code>. Querying <code>busy: false</code> will also match elements with <code>busy: undefined</code> (see the <a href="https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State" target="_blank" rel="noopener noreferrer" class="rp-link">wiki</a> for more details).</p>
<ul>
<li>See <a href="https://reactnative.dev/docs/accessibility#accessibilitystate" target="_blank" rel="noopener noreferrer" class="rp-link">React Native&#x27;s accessibilityState</a> docs to learn more about the <code>busy</code> state.</li>
<li>This option can alternatively be expressed using the <a href="/react-native-testing-library/docs/api/jest-matchers#tobebusy" class="rp-link"><code>toBeBusy()</code></a> Jest matcher.</li>
</ul>
</li>
<li>
<p><code>expanded</code>: You can filter elements by their expanded state (coming either from <code>aria-expanded</code> prop or <code>accessbilityState.expanded</code> prop). The possible values are <code>true</code> or <code>false</code>.</p>
<ul>
<li>See <a href="https://reactnative.dev/docs/accessibility#accessibilitystate" target="_blank" rel="noopener noreferrer" class="rp-link">React Native&#x27;s accessibilityState</a> docs to learn more about the <code>expanded</code> state.</li>
<li>This option can alternatively be expressed using the <a href="/react-native-testing-library/docs/api/jest-matchers#tobeexpanded" class="rp-link"><code>toBeExpanded()</code> / <code>toBeCollapsed()</code></a> Jest matchers.</li>
</ul>
</li>
<li>
<p><code>value</code>: Filter elements by their accessibility value, based on either <code>aria-valuemin</code>, <code>aria-valuemax</code>, <code>aria-valuenow</code>, <code>aria-valuetext</code> or <code>accessibilityValue</code> props. Accessiblity value conceptually consists of numeric <code>min</code>, <code>max</code> and <code>now</code> entries, as well as string <code>text</code> entry.</p>
<ul>
<li>See React Native <a href="https://reactnative.dev/docs/accessibility#accessibilityvalue" target="_blank" rel="noopener noreferrer" class="rp-link">accessibilityValue</a> docs to learn more about the accessibility value concept.</li>
<li>This option can alternatively be expressed using the <a href="/react-native-testing-library/docs/api/jest-matchers#tohaveaccessibilityvalue" class="rp-link"><code>toHaveAccessibilityValue()</code></a> Jest matcher.</li>
</ul>
</li>
</ul>
<h3 class="rp-toc-include" id="by-label-text"><a href="#by-label-text" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>*ByLabelText</code></h3>
<blockquote>
<p>getByLabelText, getAllByLabelText, queryByLabelText, queryAllByLabelText, findByLabelText, findAllByLabelText</p>
</blockquote>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByLabelText</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> text: TextMatch</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> options</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> exact?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> normalizer</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> (text</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> string;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): ReactTestInstance;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Returns a <code>ReactTestInstance</code> with matching label:</p>
<ul>
<li>either by matching <a href="https://reactnative.dev/docs/accessibility#aria-label" target="_blank" rel="noopener noreferrer" class="rp-link"><code>aria-label</code></a>/<a href="https://reactnative.dev/docs/accessibility#accessibilitylabel" target="_blank" rel="noopener noreferrer" class="rp-link"><code>accessibilityLabel</code></a> prop</li>
<li>or by matching text content of view referenced by <a href="https://reactnative.dev/docs/accessibility#aria-labelledby-android" target="_blank" rel="noopener noreferrer" class="rp-link"><code>aria-labelledby</code></a>/<a href="https://reactnative.dev/docs/accessibility#accessibilitylabelledby-android" target="_blank" rel="noopener noreferrer" class="rp-link"><code>accessibilityLabelledBy</code></a> prop</li>
</ul>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">MyComponent</span><span style="color:var(--shiki-foreground)"> /&gt;);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByLabelText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;my-label&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h3 class="rp-toc-include" id="by-placeholder-text"><a href="#by-placeholder-text" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>*ByPlaceholderText</code></h3>
<blockquote>
<p>getByPlaceholderText, getAllByPlaceholderText, queryByPlaceholderText, queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText</p>
</blockquote>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByPlaceholderText</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> text: TextMatch</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> options</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> exact?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> normalizer</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> (text</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> string;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): ReactTestInstance;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Returns a <code>ReactTestInstance</code> for a <code>TextInput</code> with a matching placeholder – may be a string or regular expression.</p>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">MyComponent</span><span style="color:var(--shiki-foreground)"> /&gt;);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByPlaceholderText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;username&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h3 class="rp-toc-include" id="by-display-value"><a href="#by-display-value" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>*ByDisplayValue</code></h3>
<blockquote>
<p>getByDisplayValue, getAllByDisplayValue, queryByDisplayValue, queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue</p>
</blockquote>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByDisplayValue</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> value: TextMatch</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> options</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> exact?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> normalizer</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> (text</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> string;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): ReactTestInstance;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Returns a <code>ReactTestInstance</code> for a <code>TextInput</code> with a matching display value – may be a string or regular expression.</p>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">MyComponent</span><span style="color:var(--shiki-foreground)"> /&gt;);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByDisplayValue</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;username&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h3 class="rp-toc-include" id="by-text"><a href="#by-text" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>*ByText</code></h3>
<blockquote>
<p>getByText, getAllByText, queryByText, queryAllByText, findByText, findAllByText</p>
</blockquote>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByText</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> text: TextMatch</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> options</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> exact?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> normalizer</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> (text</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> string;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): ReactTestInstance;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Returns a <code>ReactTestInstance</code> with matching text – may be a string or regular expression.</p>
<p>This method will join <code>&lt;Text&gt;</code> siblings to find matches, similarly to <a href="https://reactnative.dev/docs/text#containers" target="_blank" rel="noopener noreferrer" class="rp-link">how React Native handles these components</a>. This will allow for querying for strings that will be visually rendered together, but may be semantically separate React components.</p>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">MyComponent</span><span style="color:var(--shiki-foreground)"> /&gt;);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;banana&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h3 class="rp-toc-include" id="by-hint-text"><a href="#by-hint-text" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>*ByHintText</code></h3>
<blockquote>
<p>getByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint, findByA11yHint, findAllByA11yHint
getByAccessibilityHint, getAllByAccessibilityHint, queryByAccessibilityHint, queryAllByAccessibilityHint, findByAccessibilityHint, findAllByAccessibilityHint
getByHintText, getAllByHintText, queryByHintText, queryAllByHintText, findByHintText, findAllByHintText</p>
</blockquote>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByHintText</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> hint: TextMatch</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> options</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> exact?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> normalizer</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> (text</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> string;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): ReactTestInstance;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Returns a <code>ReactTestInstance</code> with matching <code>accessibilityHint</code> prop.</p>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">MyComponent</span><span style="color:var(--shiki-foreground)"> /&gt;);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByHintText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;Plays a song&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<div class="rp-callout rp-callout--info"><div class="rp-callout__title">Info</div><div class="rp-callout__content"><p>
Please consult <a href="https://developer.apple.com/documentation/objectivec/nsobject/1615093-accessibilityhint" target="_blank" rel="noopener noreferrer" class="rp-link">Apple guidelines on how <code>accessibilityHint</code> should be used</a>.</p></div></div>
<h3 class="rp-toc-include" id="by-test-id"><a href="#by-test-id" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>*ByTestId</code></h3>
<blockquote>
<p>getByTestId, getAllByTestId, queryByTestId, queryAllByTestId, findByTestId, findAllByTestId</p>
</blockquote>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-function)">getByTestId</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> testId: TextMatch</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> options</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> exact?</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> normalizer</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> (text</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-foreground)"> string;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> boolean;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> }</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">): ReactTestInstance;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Returns a <code>ReactTestInstance</code> with matching <code>testID</code> prop. <code>testID</code> – may be a string or a regular expression.</p>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-keyword)">import</span><span style="color:var(--shiki-foreground)"> { render</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> screen } </span><span style="color:var(--shiki-token-keyword)">from</span><span style="color:var(--shiki-token-string-expression)"> &#x27;@testing-library/react-native&#x27;</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">MyComponent</span><span style="color:var(--shiki-foreground)"> /&gt;);</span></span>
<span class="line"><span style="color:var(--shiki-token-keyword)">const</span><span style="color:var(--shiki-token-constant)"> element</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByTestId</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;unique-id&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<div class="rp-callout rp-callout--info"><div class="rp-callout__title">Info</div><div class="rp-callout__content"><p>
In the spirit of <a href="https://testing-library.com/docs/guiding-principles" target="_blank" rel="noopener noreferrer" class="rp-link">the guiding principles</a>, it is recommended to use this only after the other queries don&#x27;t work for your use case. Using <code>testID</code> attributes do not resemble how your software is used and should be avoided if possible. However, they are particularly useful for end-to-end testing on real devices, e.g. using Detox and it&#x27;s an encouraged technique to use there. Learn more from the blog post <a href="https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change" target="_blank" rel="noopener noreferrer" class="rp-link">&quot;Making your UI tests resilient to change&quot;</a>.</p></div></div>
<h3 class="rp-toc-include" id="common-options"><a href="#common-options" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Common options</h3>
<p>Usually query first argument can be a <strong>string</strong> or a <strong>regex</strong>. All queries take at least the <a href="#hidden-option" class="rp-link"><code>hidden</code></a> option as an optionnal second argument and some queries accept more options which change string matching behaviour. See <a href="#textmatch" class="rp-link">TextMatch</a> for more info.</p>
<h4 class="rp-toc-include" id="includehiddenelements-option"><a href="#includehiddenelements-option" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>includeHiddenElements</code> option</h4>
<p>All queries have the <code>includeHiddenElements</code> option which affects whether <a href="/react-native-testing-library/docs/api/misc/accessibility#ishiddenfromaccessibility" class="rp-link">elements hidden from accessibility</a> are matched by the query. By default queries will not match hidden elements, because the users of the app would not be able to see such elements.</p>
<p>You can configure the default value with the <a href="/react-native-testing-library/docs/api/misc/config#configure" class="rp-link"><code>configure</code> function</a>.</p>
<p>This option is also available as <code>hidden</code> alias for compatibility with <a href="https://testing-library.com/docs/queries/byrole#hidden" target="_blank" rel="noopener noreferrer" class="rp-link">React Testing Library</a>.</p>
<p><strong>Examples</strong></p>
<div class="rp-codeblock language-tsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="tsx"><code><span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">Text</span><span style="color:var(--shiki-token-function)"> style</span><span style="color:var(--shiki-token-keyword)">=</span><span style="color:var(--shiki-foreground)">{{ display</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-string-expression)"> &#x27;none&#x27;</span><span style="color:var(--shiki-foreground)"> }}&gt;Hidden from accessibility&lt;/</span><span style="color:var(--shiki-token-constant)">Text</span><span style="color:var(--shiki-foreground)">&gt;);</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-comment)">// Exclude hidden elements</span></span>
<span class="line"><span style="color:var(--shiki-token-function)">expect</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.queryByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;Hidden from accessibility&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> false</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> })</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">).</span><span style="color:var(--shiki-token-constant)">not</span><span style="color:var(--shiki-token-function)">.toBeOnTheScreen</span><span style="color:var(--shiki-foreground)">();</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-comment)">// Include hidden elements</span></span>
<span class="line"><span style="color:var(--shiki-token-function)">expect</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;Hidden from accessibility&#x27;</span><span style="color:var(--shiki-foreground)">))</span><span style="color:var(--shiki-token-function)">.toBeOnTheScreen</span><span style="color:var(--shiki-foreground)">();</span></span>
<span class="line"><span style="color:var(--shiki-token-function)">expect</span><span style="color:var(--shiki-foreground)">(</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)"> screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;Hidden from accessibility&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> { includeHiddenElements</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> true</span><span style="color:var(--shiki-foreground)"> })</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">)</span><span style="color:var(--shiki-token-function)">.toBeOnTheScreen</span><span style="color:var(--shiki-foreground)">();</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h2 class="rp-toc-include" id="textmatch-type"><a href="#textmatch-type" class="rp-header-anchor rp-link" aria-hidden="true">#</a>TextMatch type</h2>
<div class="rp-codeblock language-ts"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="ts"><code><span class="line"><span style="color:var(--shiki-token-keyword)">type</span><span style="color:var(--shiki-token-function)"> TextMatch</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-token-keyword)"> |</span><span style="color:var(--shiki-token-function)"> RegExp</span><span style="color:var(--shiki-foreground)">;</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Most of the query APIs take a <code>TextMatch</code> as an argument, which means the argument can be either a <em>string</em> or <em>regex</em>.</p>
<h3 class="rp-toc-include" id="examples"><a href="#examples" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Examples</h3>
<p>Given the following render:</p>
<div class="rp-codeblock language-jsx"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="jsx"><code><span class="line"><span style="color:var(--shiki-token-function)">render</span><span style="color:var(--shiki-foreground)">(&lt;</span><span style="color:var(--shiki-token-constant)">Text</span><span style="color:var(--shiki-foreground)">&gt;Hello World&lt;/</span><span style="color:var(--shiki-token-constant)">Text</span><span style="color:var(--shiki-foreground)">&gt;);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Will <strong>find a match</strong>:</p>
<div class="rp-codeblock language-js"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="js"><code><span class="line"><span style="color:var(--shiki-token-comment)">// Matching a string:</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;Hello World&#x27;</span><span style="color:var(--shiki-foreground)">); </span><span style="color:var(--shiki-token-comment)">// full string match</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;llo Worl&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> { exact</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> false</span><span style="color:var(--shiki-foreground)"> }); </span><span style="color:var(--shiki-token-comment)">// substring match</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;hello world&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> { exact</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> false</span><span style="color:var(--shiki-foreground)"> }); </span><span style="color:var(--shiki-token-comment)">// ignore case-sensitivity</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-comment)">// Matching a regex:</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">/World/</span><span style="color:var(--shiki-foreground)">); </span><span style="color:var(--shiki-token-comment)">// substring match</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">/world/</span><span style="color:var(--shiki-token-keyword)">i</span><span style="color:var(--shiki-foreground)">); </span><span style="color:var(--shiki-token-comment)">// substring match, ignore case</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">/</span><span style="color:var(--shiki-token-keyword)">^</span><span style="color:var(--shiki-token-string-expression)">hello world</span><span style="color:var(--shiki-token-keyword)">$</span><span style="color:var(--shiki-token-string-expression)">/</span><span style="color:var(--shiki-token-keyword)">i</span><span style="color:var(--shiki-foreground)">); </span><span style="color:var(--shiki-token-comment)">// full string match, ignore case-sensitivity</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">/Hello W</span><span style="color:var(--shiki-token-keyword)">?</span><span style="color:var(--shiki-token-string-expression)">oRlD/</span><span style="color:var(--shiki-token-keyword)">i</span><span style="color:var(--shiki-foreground)">); </span><span style="color:var(--shiki-token-comment)">// advanced regex</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Will <strong>NOT find a match</strong></p>
<div class="rp-codeblock language-js"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="js"><code><span class="line"><span style="color:var(--shiki-token-comment)">// substring does not match</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;llo Worl&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span>
<span class="line"><span style="color:var(--shiki-token-comment)">// full string does not match</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">&#x27;Goodbye World&#x27;</span><span style="color:var(--shiki-foreground)">);</span></span>
<span class="line"></span>
<span class="line"><span style="color:var(--shiki-token-comment)">// case-sensitive regex with different case</span></span>
<span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">/hello world/</span><span style="color:var(--shiki-foreground)">);</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h3 class="rp-toc-include" id="text-match-options"><a href="#text-match-options" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Options</h3>
<h4 class="rp-toc-include" id="precision"><a href="#precision" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Precision</h4>
<div class="rp-codeblock language-typescript"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="typescript"><code><span class="line"><span style="color:var(--shiki-token-keyword)">type</span><span style="color:var(--shiki-token-function)"> TextMatchOptions</span><span style="color:var(--shiki-token-keyword)"> =</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> exact</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-token-constant)"> boolean</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"><span style="color:var(--shiki-token-function)"> normalizer</span><span style="color:var(--shiki-token-keyword)">?:</span><span style="color:var(--shiki-foreground)"> (text</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-token-constant)"> string</span><span style="color:var(--shiki-foreground)">;</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">};</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>Queries that take a <code>TextMatch</code> also accept an object as the second argument that can contain options that affect the precision of string matching:</p>
<ul>
<li><code>exact</code>: Defaults to <code>true</code>; matches full strings, case-sensitive. When false, matches substrings and is not case-sensitive.<!-- -->
<ul>
<li><code>exact</code> has no effect on regex argument.</li>
<li>In most cases using a <code>regex</code> instead of a string gives you more control over fuzzy matching and should be preferred over <code>{ exact: false }</code>.</li>
</ul>
</li>
<li><code>normalizer</code>: An optional function which overrides normalization behavior. See <a href="#normalization" class="rp-link">Normalization</a>.</li>
</ul>
<p><code>exact</code> option defaults to <code>true</code> but if you want to search for a text slice or make text matching case-insensitive you can override it. That being said we advise you to use regex in more complex scenarios.</p>
<h4 class="rp-toc-include" id="normalization"><a href="#normalization" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Normalization</h4>
<p>Before running any matching logic against text, it is automatically normalized. By default, normalization consists of trimming whitespace from the start and end of text, and collapsing multiple adjacent whitespace characters into a single space.</p>
<p>If you want to prevent that normalization, or provide alternative normalization (e.g. to remove Unicode control characters), you can provide a <code>normalizer</code> function in the options object. This function will be given a string and is expected to return a normalized version of that string.</p>
<div class="rp-callout rp-callout--info"><div class="rp-callout__title">Info</div><div class="rp-callout__content"><p>
Specifying a value for <code>normalizer</code> replaces the built-in normalization, but you can call <code>getDefaultNormalizer</code> to obtain a built-in normalizer, either to adjust that normalization or to call it from your own normalizer.</p></div></div>
<p><code>getDefaultNormalizer</code> take options object which allows the selection of behaviour:</p>
<ul>
<li><code>trim</code>: Defaults to <code>true</code>. Trims leading and trailing whitespace.</li>
<li><code>collapseWhitespace</code>: Defaults to <code>true</code>. Collapses inner whitespace (newlines, tabs repeated spaces) into a single space.</li>
</ul>
<h5 class="rp-toc-include" id="normalization-examples"><a href="#normalization-examples" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Normalization Examples</h5>
<p>To perform a match against text without trimming:</p>
<div class="rp-codeblock language-typescript"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="typescript"><code><span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(node</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-token-string-expression)"> &#x27;text&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-foreground)"> normalizer</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-function)"> getDefaultNormalizer</span><span style="color:var(--shiki-foreground)">({ trim</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> false</span><span style="color:var(--shiki-foreground)"> })</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">});</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<p>To override normalization to remove some Unicode characters whilst keeping some (but not all) of the built-in normalization behavior:</p>
<div class="rp-codeblock language-typescript"><div class="rp-codeblock__content"><div class="rp-codeblock__content__scroll-container rp-scrollbar rp-scrollbar--always"><pre class="shiki css-variables" style="background-color:var(--shiki-background);color:var(--shiki-foreground)" tabindex="0" data-lang="typescript"><code><span class="line"><span style="color:var(--shiki-token-constant)">screen</span><span style="color:var(--shiki-token-function)">.getByText</span><span style="color:var(--shiki-foreground)">(node</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-token-string-expression)"> &#x27;text&#x27;</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-foreground)"> {</span></span>
<span class="line"><span style="color:var(--shiki-token-function)"> normalizer</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-foreground)"> (str) </span><span style="color:var(--shiki-token-keyword)">=&gt;</span><span style="color:var(--shiki-token-function)"> getDefaultNormalizer</span><span style="color:var(--shiki-foreground)">({ trim</span><span style="color:var(--shiki-token-keyword)">:</span><span style="color:var(--shiki-token-constant)"> false</span><span style="color:var(--shiki-foreground)"> })(str)</span><span style="color:var(--shiki-token-function)">.replace</span><span style="color:var(--shiki-foreground)">(</span><span style="color:var(--shiki-token-string-expression)">/[\u200E-\u200F]</span><span style="color:var(--shiki-token-keyword)">*</span><span style="color:var(--shiki-token-string-expression)">/</span><span style="color:var(--shiki-token-keyword)">g</span><span style="color:var(--shiki-token-punctuation)">,</span><span style="color:var(--shiki-token-string-expression)"> &#x27;&#x27;</span><span style="color:var(--shiki-foreground)">)</span><span style="color:var(--shiki-token-punctuation)">,</span></span>
<span class="line"><span style="color:var(--shiki-foreground)">});</span></span></code></pre></div><div class="rp-code-button-group"><button class="rp-code-button-group__button rp-code-wrap-button" title="Toggle code wrap"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrapped"><path fill="#22a041" d="M21 5H3v2h18zM3 19h7v-2H3zm0-6h15c1 0 2 .43 2 2s-1 2-2 2h-2v-2l-4 3 4 3v-2h2c2.95 0 4-1.27 4-4 0-2.72-1-4-4-4H3z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" class="rp-code-button-group__icon rp-code-button-group__icon--wrap"><path fill="currentColor" d="M16 7H3V5h13zM3 19h13v-2H3zm19-7-4-3v2H3v2h15v2z"></path></svg></button><button class="rp-code-button-group__button rp-code-copy-button" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--copy"><path fill="currentColor" d="M28 10v18H10V10zm0-2H10a2 2 0 0 0-2 2v18a2 2 0 0 0 2 2h18a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2"></path><path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z"></path></svg><svg width="32" height="32" viewBox="0 0 30 30" class="rp-code-button-group__icon rp-code-copy-button__icon rp-code-copy-button__icon--success"><path fill="#49cd37" d="m13 24-9-9 1.414-1.414L13 21.171 26.586 7.586 28 9z"></path></svg></button></div></div></div>
<h2 class="rp-toc-include" id="legacy-unit-testing-helpers"><a href="#legacy-unit-testing-helpers" class="rp-header-anchor rp-link" aria-hidden="true">#</a>Legacy unit testing helpers</h2>
<p><code>render</code> from <code>@testing-library/react-native</code> exposes additional queries that <strong>should not be used in integration or component testing</strong>, but some users (like component library creators) interested in unit testing some components may find helpful.</p>
<p>The interface is the same as for other queries, but we won&#x27;t provide full names so that they&#x27;re harder to find by search engines.</p>
<h3 class="rp-toc-include" id="unsafe_bytype"><a href="#unsafe_bytype" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>UNSAFE_ByType</code></h3>
<blockquote>
<p>UNSAFE_getByType, UNSAFE_getAllByType, UNSAFE_queryByType, UNSAFE_queryAllByType</p>
</blockquote>
<p>Returns a <code>ReactTestInstance</code> with matching a React component type.</p>
<div class="rp-callout rp-callout--caution"><div class="rp-callout__title">Caution</div><div class="rp-callout__content"><p>
This query has been marked unsafe, since it requires knowledge about implementation details of the component. Use responsibly.</p></div></div>
<h3 class="rp-toc-include" id="unsafe_byprops"><a href="#unsafe_byprops" class="rp-header-anchor rp-link" aria-hidden="true">#</a><code>UNSAFE_ByProps</code></h3>
<blockquote>
<p>UNSAFE_getByProps, UNSAFE_getAllByProps, UNSAFE_queryByProps, UNSAFE_queryAllByProps</p>
</blockquote>
<p>Returns a <code>ReactTestInstance</code> with matching props object.</p>
<div class="rp-callout rp-callout--caution"><div class="rp-callout__title">Caution</div><div class="rp-callout__content"><p>
This query has been marked unsafe, since it requires knowledge about implementation details of the component. Use responsibly.</p></div></div><!--/$--></div><div class="container-uhcWmO"><img class="logo-IwzwG8" src="/react-native-testing-library/static/image/abstract-atom.4eca0300.avif" alt="Abstract Logo" aria-hidden="true"/><div class="content-uJxcIj"><div class="headlineContainer-NHNT4y"><h1 class="headline-iCUUUl">Need React or React Native
expertise you can count on?</h1></div><div class="buttonContainer-wOj8Y6"><div class="dark"><a href="https://www.callstack.com/contact" class="button-DogSnd brand-rT2ahT ">Let&#x27;s talk<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16" class="button-icon-Okk0hT" aria-hidden="true" focusable="false"><path fill="currentColor" d="M9.333 13.333h1.334V12H9.333zm-6.666-2.666h8V12H12v-1.333h1.333V9.333H12V8h-1.333v1.333H4V2.667H2.667zM9.333 8h1.334V6.667H9.333z"></path></svg></a></div></div></div></div><footer class="rp-doc-footer"><div class="rp-doc-footer__edit"></div><div class="rp-doc-footer__divider"></div><div class="rp-prev-next-page"><a href="/react-native-testing-library/docs/api/screen" class="rp-prev-next-page__item rp-prev-next-page__prev rp-link"><span class="rp-prev-next-page__item__desc">Previous page</span><span class="rp-prev-next-page__item__title"><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt="" class="rp-prev-next-page__icon rp-prev-next-page__rotate_180"/><span>Screen object</span></span></a><a href="/react-native-testing-library/docs/api/jest-matchers" class="rp-prev-next-page__item rp-prev-next-page__next rp-link"><span class="rp-prev-next-page__item__desc">Next page</span><span class="rp-prev-next-page__item__title"><span>Jest Matchers</span><img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTMiIHZpZXdCb3g9IjAgMCAxMiAxMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTYuNSA0LjVINy41VjMuNUg2LjVWMi41SDUuNVYzLjVINC41VjQuNUg1LjVWMTAuNUg2LjVWNC41Wk00LjUgNC41SDMuNVY1LjVINC41VjQuNVpNOC41IDQuNUg3LjVWNS41SDguNVY0LjVaTTMuNSA2LjVWNS41SDIuNVY2LjVIMy41Wk05LjUgNS41SDguNVY2LjVIOS41VjUuNVoiIGZpbGw9IiNCQ0JCQzIiLz4KPC9zdmc+Cg==" alt="" class="rp-prev-next-page__icon"/></span></a></div></footer></main></div><aside class="rp-doc-layout__outline rp-scrollbar"><div class="rp-outline__divider"></div><div class="container-LzbylO"><div><div class="headline-y75_LS">Need help with React or React Native projects?</div><div class="description-muYVs3">We support teams building scalable apps with React and React Native.</div></div><a href="https://www.callstack.com/contact" class="button-DogSnd brand-rT2ahT ">Let&#x27;s talk<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16" class="button-icon-Okk0hT" aria-hidden="true" focusable="false"><path fill="currentColor" d="M9.333 13.333h1.334V12H9.333zm-6.666-2.666h8V12H12v-1.333h1.333V9.333H12V8h-1.333v1.333H4V2.667H2.667zM9.333 8h1.334V6.667H9.333z"></path></svg></a></div></aside></div></div>
<div id="__rspress_modal_container"></div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink