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

Read The Docs |Edit the docs

Table of Contents

The problem

The solution

Installation

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

yarn add --dev @testing-library/react @testing-library/dom

npm install --save-dev @testing-library/react@12yarn add --dev @testing-library/react@12

Suppressing unnecessary warnings on React DOM 16.8

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

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

Examples

Basic Example

// hidden-message.jsimport*asReactfrom'react'// NOTE: React Testing Library works well with React Hooks and classes.// Your tests will be the same regardless of how you write your components.functionHiddenMessage({children}){const[showMessage,setShowMessage]=React.useState(false)return(<div><labelhtmlFor="toggle">Show Message</label><inputid="toggle"type="checkbox"onChange={e=>setShowMessage(e.target.checked)}checked={showMessage}/>{showMessage ?children :null}</div>)}exportdefaultHiddenMessage

// __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#cleanupimport'@testing-library/jest-dom'// NOTE: jest-dom adds handy assertions to Jest and is recommended, but not requiredimport*asReactfrom'react'import{render,fireEvent,screen}from'@testing-library/react'importHiddenMessagefrom'../hidden-message'test('shows the children when the checkbox is checked',()=>{consttestMessage='Test Message'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 foundexpect(screen.queryByText(testMessage)).toBeNull()// the queries can accept a regex to make your selectors more resilient to content tweaks and changes.fireEvent.click(screen.getByLabelText(/show/i))// .toBeInTheDocument() is an assertion that comes from jest-dom// otherwise you could use .toBeDefined()expect(screen.getByText(testMessage)).toBeInTheDocument()})

Complex Example

// login.jsimport*asReactfrom'react'functionLogin(){const[state,setState]=React.useReducer((s,a)=>({...s, ...a}),{resolved:false,loading:false,error:null,})functionhandleSubmit(event){event.preventDefault()const{usernameInput, passwordInput}=event.target.elementssetState({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(data=>(r.ok ?data :Promise.reject(data)))).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><formonSubmit={handleSubmit}><div><labelhtmlFor="usernameInput">Username</label><inputid="usernameInput"/></div><div><labelhtmlFor="passwordInput">Password</label><inputid="passwordInput"type="password"/></div><buttontype="submit">Submit{state.loading ?'...' :null}</button></form>{state.error ?<divrole="alert">{state.error}</div> :null}{state.resolved ?(<divrole="alert">Congrats! You're signed in!</div>) :null}</div>)}exportdefaultLogin

// __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/jest-dom'import*asReactfrom'react'// import API mocking utilities from Mock Service Worker.import{rest}from'msw'import{setupServer}from'msw/node'// import testing utilitiesimport{render,fireEvent,screen}from'@testing-library/react'importLoginfrom'../login'constfakeUserResponse={token:'fake_user_token'}constserver=setupServer(rest.post('/api/login',(req,res,ctx)=>{returnres(ctx.json(fakeUserResponse))}),)beforeAll(()=>server.listen())afterEach(()=>{server.resetHandlers()window.localStorage.removeItem('token')})afterAll(()=>server.close())test('allows the user to login successfully',async()=>{render(<Login/>)// fill out the formfireEvent.change(screen.getByLabelText(/username/i),{target:{value:'chuck'},})fireEvent.change(screen.getByLabelText(/password/i),{target:{value:'norris'},})fireEvent.click(screen.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.constalert=awaitscreen.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 recommendedexpect(alert).toHaveTextContent(/congrats/i)expect(window.localStorage.getItem('token')).toEqual(fakeUserResponse.token)})test('handles server exceptions',async()=>{// mock the server error response for this test suite only.server.use(rest.post('/api/login',(req,res,ctx)=>{returnres(ctx.status(500),ctx.json({message:'Internal server error'}))}),)render(<Login/>)// fill out the formfireEvent.change(screen.getByLabelText(/username/i),{target:{value:'chuck'},})fireEvent.change(screen.getByLabelText(/password/i),{target:{value:'norris'},})fireEvent.click(screen.getByText(/submit/i))// wait for the error messageconstalert=awaitscreen.findByRole('alert')expect(alert).toHaveTextContent(/internalservererror/i)expect(window.localStorage.getItem('token')).toBeNull()})

More Examples

Hooks

Guiding Principles

Docs

Issues

🐛 Bugs

💡 Feature Requests

❓ Questions

Contributors

LICENSE