CINXE.COM
<!doctype html> <html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-introduction"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <meta name="generator" content="Docusaurus v2.0.1"> <link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="Testing Library RSS Feed"> <link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="Testing Library Atom Feed"> <link rel="alternate" type="application/json" href="/blog/feed.json" title="Testing Library JSON Feed"> <link rel="preconnect" href="https://www.google-analytics.com"> <link rel="preconnect" href="https://www.googletagmanager.com"> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-137787095-1"></script> <script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","UA-137787095-1",{})</script> <link rel="search" type="application/opensearchdescription+xml" title="Testing Library" href="/opensearch.xml"> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=IBM+Plex+Mono:500,700|Source+Code+Pro:500,700|Source+Sans+Pro:400,400i,700"> <script src="https://buttons.github.io/buttons.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js"></script><title data-rh="true">Introduction | Testing Library</title><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://testing-library.com/img/octopus-128x128.png"><meta data-rh="true" name="twitter:image" content="https://testing-library.com/img/octopus-128x128.png"><meta data-rh="true" property="og:url" content="https://testing-library.com/docs/"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Introduction | Testing Library"><meta data-rh="true" name="description" content="The @testing-library family of packages helps you test UI components in"><meta data-rh="true" property="og:description" content="The @testing-library family of packages helps you test UI components in"><link data-rh="true" rel="icon" href="/img/octopus-32x32.png"><link data-rh="true" rel="canonical" href="https://testing-library.com/docs/"><link data-rh="true" rel="alternate" href="https://testing-library.com/docs/" hreflang="en"><link data-rh="true" rel="alternate" href="https://testing-library.com/docs/" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://TUPO88CFRP-dsn.algolia.net" crossorigin="anonymous"><link rel="stylesheet" href="/assets/css/styles.67d9695e.css"> <link rel="preload" href="/assets/js/runtime~main.d843c6fc.js" as="script"> <link rel="preload" href="/assets/js/main.d3a3b6aa.js" as="script"> </head> <body class="navigation-with-keyboard"> <script>!function(){function e(e){document.documentElement.setAttribute("data-theme",e)}var t=function(){var e=null;try{e=localStorage.getItem("theme")}catch(e){}return e}();null!==t?e(t):window.matchMedia("(prefers-color-scheme: dark)").matches?e("dark"):(window.matchMedia("(prefers-color-scheme: light)").matches,e("light"))}()</script><div id="__docusaurus"> <div role="region"><a href="#" class="skipToContent_fXgn">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Navigation bar toggle" class="navbar__toggle clean-btn" type="button" tabindex="0"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/octopus-64x64.png" alt="An octopus representing the DOM Testing Library Logo" class="themedImage_ToTc themedImage--light_HNdA" height="32" width="32"><img src="/img/octopus-64x64.png" alt="An octopus representing the DOM Testing Library Logo" class="themedImage_ToTc themedImage--dark_i4oU" height="32" width="32"></div><b class="navbar__title text--truncate">Testing Library</b></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/">Docs</a><a class="navbar__item navbar__link" href="/docs/recipes">Examples</a></div><div class="navbar__items navbar__items--right"><a class="navbar__item navbar__link" href="/help">Help</a><a class="navbar__item navbar__link" href="/blog">Blog</a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebar_njMd"><nav class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" aria-expanded="true" href="/docs/">Getting Started</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/">Introduction</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/guiding-principles">Guiding Principles</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/dom-testing-library/faq">FAQ</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/queries/about">Core API</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/dom-testing-library/intro">Frameworks</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/user-event/intro">User Interactions</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/ecosystem-jest-dom">Ecosystem</a></div></li></ul></nav></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_OVgt"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Getting Started</span><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Introduction</span><meta itemprop="position" content="2"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Introduction</h1></header><p>The <a href="https://www.npmjs.com/org/testing-library" target="_blank" rel="noopener noreferrer"><code>@testing-library</code></a> family of packages helps you test UI components in a user-centric way.</p><blockquote><p><a href="/docs/guiding-principles">The more your tests resemble the way your software is used, the more confidence they can give you.</a></p></blockquote><h2 class="anchor anchorWithStickyNavbar_LWe7" id="the-problem">The problem<a class="hash-link" href="#the-problem" title="Direct link to heading"></a></h2><p>You want to write maintainable tests that give you high confidence that your components are working for your users. As a part of this goal, you want your tests to avoid including implementation details so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="the-solution">The solution<a class="hash-link" href="#the-solution" title="Direct link to heading"></a></h2><p>The core library, <a href="/docs/dom-testing-library/intro"><code>DOM Testing Library</code></a>, is a light-weight solution for testing web pages by querying and interacting with DOM nodes (whether simulated with <a href="https://github.com/jsdom/jsdom" target="_blank" rel="noopener noreferrer"><code>JSDOM</code></a>/<a href="https://jestjs.io" target="_blank" rel="noopener noreferrer">Jest</a> or in the browser). The main utilities it provides involve querying the DOM for nodes in a way that's similar to how the user finds elements on the page. In this way, the library helps ensure your tests give you confidence that your application will work when a real user uses it.</p><p>The core library has been wrapped to provide ergonomic APIs for several frameworks, including <a href="/docs/react-testing-library/intro">React</a>, <a href="/docs/angular-testing-library/intro">Angular</a>, and <a href="/docs/vue-testing-library/intro">Vue</a>. There is also a plugin to use testing-library queries for end-to-end tests in <a href="/docs/cypress-testing-library/intro">Cypress</a> and an implementation for <a href="/docs/react-native-testing-library/intro">React Native</a>.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="what-this-library-is-not">What this library is not<a class="hash-link" href="#what-this-library-is-not" title="Direct link to heading"></a></h3><ol><li>A test runner or framework</li><li>Specific to a testing framework</li></ol><p><code>DOM Testing Library</code> works with any environment that provides DOM APIs, such as Jest, Mocha + JSDOM, or a real browser.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="what-you-should-avoid-with-testing-library">What you should avoid with Testing Library<a class="hash-link" href="#what-you-should-avoid-with-testing-library" title="Direct link to heading"></a></h3><p>Testing Library encourages you to avoid testing <a href="https://kentcdodds.com/blog/testing-implementation-details" target="_blank" rel="noopener noreferrer">implementation details</a> like the internals of a component you're testing (though it's still possible). <a href="/docs/guiding-principles">The Guiding Principles</a> of this library emphasize a focus on tests that closely resemble how your web pages are interacted by the users.</p><p>You may want to avoid the following implementation details:</p><ol><li>Internal state of a component</li><li>Internal methods of a component</li><li>Lifecycle methods of a component</li><li>Child components</li></ol></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/testing-library/testing-library-docs/edit/main/docs/intro.mdx" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2021-09-15T10:14:41.000Z">Sep 15, 2021</time></b> by <b>HonkingGoose</b></span></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--next" href="/docs/guiding-principles"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Guiding Principles</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#the-problem" class="table-of-contents__link toc-highlight">The problem</a></li><li><a href="#the-solution" class="table-of-contents__link toc-highlight">The solution</a><ul><li><a href="#what-this-library-is-not" class="table-of-contents__link toc-highlight">What this library is not</a></li><li><a href="#what-you-should-avoid-with-testing-library" class="table-of-contents__link toc-highlight">What you should avoid with Testing Library</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="footer"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs">Getting Started</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/example-codesandbox">Examples</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/dom-testing-library/api">API</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/dom-testing-library/faq">Help</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/blog">Blog</a></li><li class="footer__item"><a href="https://stackoverflow.com/questions/tagged/react-testing-library" target="_blank" rel="noopener noreferrer" class="footer__link-item">Stack Overflow<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://discord.gg/testing-library" target="_blank" rel="noopener noreferrer" class="footer__link-item">Discord<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"> <a target="_blank" rel="noreferrer noopener" class="github-button" href="https://github.com/testing-library/react-testing-library" data-icon="octicon-star" data-count-href="/testing-library/react-testing-library/stargazers" data-show-count="true" data-count-aria-label="# stargazers on GitHub" aria-label="Star this project on GitHub">Star</a> </li><li class="footer__item"><a href="https://github.com/testing-library" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://github.com/testing-library/testing-library-docs" target="_blank" rel="noopener noreferrer" class="footer__link-item">Edit Docs on GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://netlify.com" target="_blank" rel="noopener noreferrer" class="footer__link-item">Hosted by Netlify<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="margin-bottom--sm"><img src="/img/octopus-128x128.png" alt="An octopus representing the DOM Testing Library Logo" class="themedImage_ToTc themedImage--light_HNdA footer__logo" width="128" height="128"><img src="/img/octopus-128x128.png" alt="An octopus representing the DOM Testing Library Logo" class="themedImage_ToTc themedImage--dark_i4oU footer__logo" width="128" height="128"></div><div class="footer__copyright">Copyright © 2018-2025 Kent C. Dodds and contributors</div></div></div></footer></div> <script src="/assets/js/runtime~main.d843c6fc.js"></script> <script src="/assets/js/main.d3a3b6aa.js"></script> </body> </html>