@eps1lon/testing-library-react

    9.1.4 • Public • Published

    react-testing-library

    goat

    Simple and complete React DOM testing utilities that encourage good testing practices.


    Read The Docs | Edit the docs



    Build Status Code Coverage version downloads MIT License

    All Contributors PRs Welcome Code of Conduct Join the community on Spectrum

    Watch on GitHub Star on GitHub Tweet

    Table of Contents

    The problem

    You want to write maintainable tests for your React components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your testbase to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.

    This solution

    The react-testing-library is a very lightweight solution for testing React components. It provides light utility functions on top of react-dom and react-dom/test-utils, in a way that encourages better testing practices. Its primary guiding principle is:

    The more your tests resemble the way your software is used, the more confidence they can give you.

    Installation

    This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

    npm install --save-dev @testing-library/react
    

    This library has peerDependencies listings for react and react-dom.

    You may also be interested in installing @testing-library/jest-dom so you can use the custom jest matchers.

    Docs

    Suppressing unnecessary warnings on React DOM 16.8

    There is a known compatibility issue with React DOM 16.8 where you will see the following warning:

    Warning: An update to ComponentName inside a test was not wrapped in act(...).
    

    If you cannot upgrade to React DOM 16.9, you may suppress the warnings by adding the following snippet to your test configuration (learn more):

    // this is just a little hack to silence a warning that we'll get until we
    // upgrade to 16.9: https://github.com/facebook/react/pull/14853
    const originalError = console.error
    beforeAll(() => {
      console.error = (...args) => {
        if (/Warning.*not wrapped in act/.test(args[0])) {
          return
        }
        originalError.call(console, ...args)
      }
    })
     
    afterAll(() => {
      console.error = originalError
    })

    Examples

    Basic Example

    // hidden-message.js
    import React from 'react'
     
    // NOTE: React Testing Library works with React Hooks _and_ classes just as well
    // and your tests will be the same however you write your components.
    function HiddenMessage({children}) {
      const [showMessage, setShowMessage] = React.useState(false)
      return (
        <div>
          <label htmlFor="toggle">Show Message</label>
          <input
            id="toggle"
            type="checkbox"
            onChange={e => setShowMessage(e.target.checked)}
            checked={showMessage}
          />
          {showMessage ? children : null}
        </div>
      )
    }
     
    export default HiddenMessage
     
    // __tests__/hidden-message.js
    // these imports are something you'd normally configure Jest to import for you
    // automatically. Learn more in the setup docs: https://testing-library.com/docs/react-testing-library/setup#cleanup
    import '@testing-library/react/cleanup-after-each'
    import '@testing-library/jest-dom/extend-expect'
    // NOTE: jest-dom adds handy assertions to Jest and is recommended, but not required
     
    import React from 'react'
    import {render, fireEvent} from '@testing-library/react'
    import HiddenMessage from '../hidden-message'
     
    test('shows the children when the checkbox is checked', () => {
      const testMessage = 'Test Message'
      const {queryByText, getByLabelText, getByText} = render(
        <HiddenMessage>{testMessage}</HiddenMessage>,
      )
     
      // query* functions will return the element or null if it cannot be found
      // get* functions will return the element or throw an error if it cannot be found
      expect(queryByText(testMessage)).toBeNull()
     
      // the queries can accept a regex to make your selectors more resilient to content tweaks and changes.
      fireEvent.click(getByLabelText(/show/i))
     
      // .toBeInTheDocument() is an assertion that comes from jest-dom
      // otherwise you could use .toBeDefined()
      expect(getByText(testMessage)).toBeInTheDocument()
    })

    Complex Example

    // login.js
    import React from 'react'
     
    function Login() {
      const [state, setState] = React.useReducer((s, a) => ({...s, ...a}), {
        resolved: false,
        loading: false,
        error: null,
      })
     
      function handleSubmit(event) {
        event.preventDefault()
        const {usernameInput, passwordInput} = event.target.elements
     
        setState({loading: true, resolved: false, error: null})
     
        window
          .fetch('/api/login', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({
              username: usernameInput.value,
              password: passwordInput.value,
            }),
          })
          .then(r => r.json())
          .then(
            user => {
              setState({loading: false, resolved: true, error: null})
              window.localStorage.setItem('token', user.token)
            },
            error => {
              setState({loading: false, resolved: false, error: error.message})
            },
          )
      }
     
      return (
        <div>
          <form onSubmit={handleSubmit}>
            <div>
              <label htmlFor="usernameInput">Username</label>
              <input id="usernameInput" />
            </div>
            <div>
              <label htmlFor="passwordInput">Password</label>
              <input id="passwordInput" type="password" />
            </div>
            <button type="submit">Submit{state.loading ? '...' : null}</button>
          </form>
          {state.error ? <div role="alert">{state.error.message}</div> : null}
          {state.success ? (
            <div role="alert">Congrats! You're signed in!</div>
          ) : null}
        </div>
      )
    }
     
    export default Login
     
    // __tests__/login.js
    // again, these first two imports are something you'd normally handle in
    // your testing framework configuration rather than importing them in every file.
    import '@testing-library/react/cleanup-after-each'
    import '@testing-library/jest-dom/extend-expect'
    import React from 'react'
    import {render, fireEvent} from '@testing-library/react'
    import Login from '../login'
     
    test('allows the user to login successfully', async () => {
      // mock out window.fetch for the test
      const fakeUserResponse = {token: 'fake_user_token'}
      jest.spyOn(window, 'fetch').mockImplementationOnce(() => {
        return Promise.resolve({
          json: () => Promise.resolve(fakeUserResponse),
        })
      })
     
      const {getByLabelText, getByText, findByRole} = render(<Login />)
     
      // fill out the form
      fireEvent.change(getByLabelText(/username/i), {target: {value: 'chuck'}})
      fireEvent.change(getByLabelText(/password/i), {target: {value: 'norris'}})
     
      fireEvent.click(getByText(/submit/i))
     
      // just like a manual tester, we'll instruct our test to wait for the alert
      // to show up before continuing with our assertions.
      const alert = await findByRole('alert')
     
      // .toHaveTextContent() comes from jest-dom's assertions
      // otherwise you could use expect(alert.textContent).toMatch(/congrats/i)
      // but jest-dom will give you better error messages which is why it's recommended
      expect(alert).toHaveTextContent(/congrats/i)
      expect(window.localStorage.getItem('token')).toEqual(fakeUserResponse.token)
    })

    More Examples

    We're in the process of moving examples to the docs site

    You'll find runnable examples of testing with different libraries in the react-testing-library-examples codesandbox. Some included are:

    You can also find react-testing-library examples at react-testing-examples.com.

    Hooks

    If you are interested in testing a custom hook, check out react-hooks-testing-library.

    NOTE it is not recommended to test single-use custom hooks in isolation from the components where it's being used. It's better to test the component that's using the hook rather than the hook itself. The react-hooks-testing-library is intended to be used for reusable hooks/libraries.

    Guiding Principles

    The more your tests resemble the way your software is used, the more confidence they can give you.

    We try to only expose methods and utilities that encourage you to write tests that closely resemble how your react components are used.

    Utilities are included in this project based on the following guiding principles:

    1. If it relates to rendering components, it deals with DOM nodes rather than component instances, nor should it encourage dealing with component instances.
    2. It should be generally useful for testing individual React components or full React applications. While this library is focused on react-dom, utilities could be included even if they don't directly relate to react-dom.
    3. Utility implementations and APIs should be simple and flexible.

    At the end of the day, what we want is for this library to be pretty light-weight, simple, and understandable.

    Docs

    Read The Docs | Edit the docs

    Issues

    Looking to contribute? Look for the Good First Issue label.

    🐛 Bugs

    Please file an issue for bugs, missing documentation, or unexpected behavior.

    See Bugs

    💡 Feature Requests

    Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

    See Feature Requests

    ❓ Questions

    For questions related to using the library, please visit a support community instead of filing an issue on GitHub.

    Contributors

    Thanks goes to these people (emoji key):

    Kent C. Dodds
    Kent C. Dodds

    💻 📖 🚇 ⚠️
    Ryan Castner
    Ryan Castner

    📖
    Daniel Sandiego
    Daniel Sandiego

    💻
    Paweł Mikołajczyk
    Paweł Mikołajczyk

    💻
    Alejandro Ñáñez Ortiz
    Alejandro Ñáñez Ortiz

    📖
    Matt Parrish
    Matt Parrish

    🐛 💻 📖 ⚠️
    Justin Hall
    Justin Hall

    📦
    Anto Aravinth
    Anto Aravinth

    💻 ⚠️ 📖
    Jonah Moses
    Jonah Moses

    📖
    Łukasz Gandecki
    Łukasz Gandecki

    💻 ⚠️ 📖
    Ivan Babak
    Ivan Babak

    🐛 🤔
    Jesse Day
    Jesse Day

    💻
    Ernesto García
    Ernesto García

    💬 💻 📖
    Josef Maxx Blake
    Josef Maxx Blake

    💻 📖 ⚠️
    Michal Baranowski
    Michal Baranowski

    📝
    Arthur Puthin
    Arthur Puthin

    📖
    Thomas Chia
    Thomas Chia

    💻 📖
    Thiago Galvani
    Thiago Galvani

    📖
    Christian
    Christian

    ⚠️
    Alex Krolick
    Alex Krolick

    💬 📖 💡 🤔
    Johann Hubert Sonntagbauer
    Johann Hubert Sonntagbauer

    💻 📖 ⚠️
    Maddi Joyce
    Maddi Joyce

    💻
    Ryan Vice
    Ryan Vice

    📖
    Ian Wilson
    Ian Wilson

    📝
    Daniel
    Daniel

    🐛 💻
    Giorgio Polvara
    Giorgio Polvara

    🐛 🤔
    John Gozde
    John Gozde

    💻
    Sam Horton
    Sam Horton

    📖 💡 🤔
    Richard Kotze (mobile)
    Richard Kotze (mobile)

    📖
    Brahian E. Soto Mercedes
    Brahian E. Soto Mercedes

    📖
    Benoit de La Forest
    Benoit de La Forest

    📖
    Salah
    Salah

    💻 ⚠️
    Adam Gordon
    Adam Gordon

    🐛 💻
    Matija Marohnić
    Matija Marohnić

    📖
    Justice Mba
    Justice Mba

    📖
    Mark Pollmann
    Mark Pollmann

    📖
    Ehtesham Kafeel
    Ehtesham Kafeel

    💻 📖
    Julio Pavón
    Julio Pavón

    💻
    Duncan L
    Duncan L

    📖 💡
    Tiago Almeida
    Tiago Almeida

    📖
    Robert Smith
    Robert Smith

    🐛
    Zach Green
    Zach Green

    📖
    dadamssg
    dadamssg

    📖
    Yazan Aabed
    Yazan Aabed

    📝
    Tim
    Tim

    🐛 💻 📖 ⚠️
    Divyanshu Maithani
    Divyanshu Maithani

    📹
    Deepak Grover
    Deepak Grover

    📹
    Eyal Cohen
    Eyal Cohen

    📖
    Peter Makowski
    Peter Makowski

    📖
    Michiel Nuyts
    Michiel Nuyts

    📖
    Joe Ng'ethe
    Joe Ng'ethe

    💻 📖
    Kate
    Kate

    📖
    Sean
    Sean

    📖
    James Long
    James Long

    🤔 📦
    Herb Hagely
    Herb Hagely

    💡
    Alex Wendte
    Alex Wendte

    💡
    Monica Powell
    Monica Powell

    📖
    Vitaly Sivkov
    Vitaly Sivkov

    💻
    Weyert de Boer
    Weyert de Boer

    🤔 👀
    EstebanMarin
    EstebanMarin

    📖
    Victor Martins
    Victor Martins

    📖
    Royston Shufflebotham
    Royston Shufflebotham

    🐛 📖 💡
    chrbala
    chrbala

    💻
    Donavon West
    Donavon West

    💻 📖 🤔 ⚠️
    Richard Maisano
    Richard Maisano

    💻
    Marco Biedermann
    Marco Biedermann

    💻 🚧 ⚠️
    Alex Zherdev
    Alex Zherdev

    🐛 💻
    André Matulionis dos Santos
    André Matulionis dos Santos

    💻 💡 ⚠️
    Daniel K.
    Daniel K.

    🐛 💻 🤔 ⚠️ 👀
    mohamedmagdy17593
    mohamedmagdy17593

    💻
    Loren ☺️
    Loren ☺️

    📖
    MarkFalconbridge
    MarkFalconbridge

    🐛 💻
    Vinicius
    Vinicius

    📖 💡
    Peter Schyma
    Peter Schyma

    💻
    Ian Schmitz
    Ian Schmitz

    📖
    Joel Marcotte
    Joel Marcotte

    🐛 ⚠️ 💻
    Alejandro Dustet
    Alejandro Dustet

    🐛
    Brandon Carroll
    Brandon Carroll

    📖
    Lucas Machado
    Lucas Machado

    📖
    Pascal Duez
    Pascal Duez

    📦
    Minh Nguyen
    Minh Nguyen

    💻
    LiaoJimmy
    LiaoJimmy

    📖
    Sunil Pai
    Sunil Pai

    💻 ⚠️
    Dan Abramov
    Dan Abramov

    👀
    Christian Murphy
    Christian Murphy

    🚇
    Ivakhnenko Dmitry
    Ivakhnenko Dmitry

    💻
    James George
    James George

    📖
    João Fernandes
    João Fernandes

    📖
    Alejandro Perea
    Alejandro Perea

    👀
    Nick McCurdy
    Nick McCurdy

    👀
    Sebastian Silbermann
    Sebastian Silbermann

    👀
    Adrià Fontcuberta
    Adrià Fontcuberta

    👀
    John Reilly
    John Reilly

    👀
    Michaël De Boey
    Michaël De Boey

    👀
    Tim Yates
    Tim Yates

    👀
    Brian Donovan
    Brian Donovan

    💻

    This project follows the all-contributors specification. Contributions of any kind welcome!

    LICENSE

    MIT

    Install

    npm i @eps1lon/testing-library-react

    DownloadsWeekly Downloads

    9

    Version

    9.1.4

    License

    MIT

    Unpacked Size

    3.36 MB

    Total Files

    22

    Last publish

    Collaborators

    • eps1lon