API

React Testing Library は DOM Testing Library のすべてと、以下のメソッドを再エクスポートします

render
render オプション
render 結果
cleanup
act
renderHook
renderHook オプション
- initialProps
- wrapper
renderHook 結果
configure
configure オプション

`render`

function render(
  ui: React.ReactElement<any>,
  options?: {
    /* You won't often use this, expand below for docs on options */
  },
): RenderResult

document.body に追加されたコンテナにレンダリングします。

import {render} from '@testing-library/react'

render(<div />)

import {render} from '@testing-library/react'
import '@testing-library/jest-dom'

test('renders a message', () => {
  const {asFragment, getByText} = render(<Greeting />)
  expect(getByText('Hello, world!')).toBeInTheDocument()
  expect(asFragment()).toMatchInlineSnapshot(`
    <h1>Hello, World!</h1>
  `)
})

`render` オプション

オプションを指定する必要があることはあまりありませんが、必要な場合は、render の2番目の引数として提供できるオプションを以下に示します。

`container`

デフォルトでは、React Testing Library は div を作成し、その div を document.body に追加します。これがReactコンポーネントがレンダリングされる場所です。このオプションを介して独自の HTMLElement container を提供する場合、自動的に document.body に追加されません。

例：tablebody 要素をユニットテストする場合、それは div の子にすることはできません。この場合、レンダリング container として table を指定できます。

const table = document.createElement('table')

const {container} = render(<TableBody {...props} />, {
  container: document.body.appendChild(table),
})

`baseElement`

container が指定されている場合、これはデフォルトでそれになります。そうでない場合、これはデフォルトで document.body になります。これは、クエリと debug() を使用したときの出力の基底要素として使用されます。

`hydrate`

hydrate が true に設定されている場合、ReactDOM.hydrate を使用してレンダリングされます。これは、サーバーサイドレンダリングを使用してコンポーネントをマウントする場合に役立ちます。

`legacyRoot`

危険

このオプションは、テストがReact 18以前で実行される場合にのみ使用できます。

デフォルトでは、同時実行機能（つまり、ReactDOMClient.createRoot）をサポートしてレンダリングします。ただし、React 17（つまり、ReactDOM.render）のようにレンダリングする必要があるレガシーアプリを扱っている場合は、legacyRoot: true を設定してこのオプションを有効にする必要があります。

`wrapper`

Reactコンポーネントを wrapper オプションとして渡して、内部要素の周りにレンダリングします。これは、共通のデータプロバイダーに再利用可能なカスタムレンダリング関数を作成する場合に最も役立ちます。例については、セットアップを参照してください。

`queries`

バインドするクエリ。マージされない限り、DOM Testing Library からのデフォルトセットをオーバーライドします。

// Example, a function to traverse table contents
import * as tableQueries from 'my-table-query-library'
import {queries} from '@testing-library/react'

const {getByRowColumn, getByText} = render(<MyTable />, {
  queries: {...queries, ...tableQueries},
})

ユーティリティ関数を使用してカスタムクエリを作成する方法については、ヘルパーを参照してください。

カスタムレンダーガイドに従うことで、カスタムクエリをグローバルに追加することもできます。

`render` 結果

render メソッドは、いくつかのプロパティを持つオブジェクトを返します

`...queries`

render の最も重要な機能は、DOM Testing Library からのクエリが、最初の引数が baseElement（デフォルトは document.body）にバインドされて自動的に返されることです。

完全なリストについては、クエリを参照してください。

例

const {getByLabelText, queryAllByTestId} = render(<Component />)

`container`

レンダリングされた React 要素（ReactDOM.render を使用してレンダリングされた）を含む DOM ノード。これは div です。これは通常の DOM ノードなので、container.querySelector などを呼び出して子要素を検査できます。

ヒント：レンダリングされた要素のルート要素を取得するには、container.firstChild を使用します。
注：そのルート要素が React Fragment の場合、container.firstChild は Fragment 自体ではなく、Fragment の最初の子のみを取得します。

🚨 レンダリングされた要素を照会するために container を使用していることに気付いた場合は、再考する必要があります。他のクエリは、テスト対象のコンポーネントに加えられる変更に対してより回復力があるように設計されています。要素を照会するために container を使用しないでください！

`baseElement`

React 要素がコンテナにレンダリングされる DOM ノードを含む。render のオプションで baseElement を指定しない場合、デフォルトで document.body になります。

これは、テストするコンポーネントがコンテナdivの外側に何かをレンダリングする場合に役立ちます。たとえば、HTMLをbodyに直接レンダリングするポータルコンポーネントのスナップショットテストを行う場合などです。

注：render によって返されるクエリは baseElement を調べるため、baseElement なしでクエリを使用してポータルコンポーネントをテストできます。

`debug`

注：代わりに screen.debug を使用することをお勧めします。

このメソッドは console.log(prettyDOM(baseElement)) のショートカットです。

import React from 'react'
import {render} from '@testing-library/react'

const HelloWorld = () => <h1>Hello World</h1>
const {debug} = render(<HelloWorld />)
debug()
// <div>
//   <h1>Hello World</h1>
// </div>
// you can also pass an element: debug(getByTestId('messages'))
// and you can pass all the same arguments to debug as you can
// to prettyDOM:
// const maxLengthToPrint = 10000
// debug(getByTestId('messages'), maxLengthToPrint, {highlight: false})

これは、公開されている DOM Testing Library からの prettyDOM のシンプルなラッパーです。

`rerender`

おそらく、小道具の更新を行っているコンポーネントをテストして、小道具が正しく更新されていることを確認することをお勧めします（ガイディングプリンシプルセクションを参照）。とはいえ、テストでレンダリングされたコンポーネントの小道具を更新したい場合は、この関数を使用してレンダリングされたコンポーネントの小道具を更新できます。

import {render} from '@testing-library/react'

const {rerender} = render(<NumberDisplay number={1} />)

// re-render the same component with different props
rerender(<NumberDisplay number={2} />)

例ページを参照してください

`unmount`

これにより、レンダリングされたコンポーネントがアンマウントされます。これは、コンポーネントがページから削除されたときに何が起こるかをテストする場合に役立ちます（イベントハンドラーがぶら下がっていてメモリリークが発生していないことをテストするなど）。

このメソッドは、ReactDOM.unmountComponentAtNode のかなり小さな抽象化です

import {render} from '@testing-library/react'

const {container, unmount} = render(<Login />)
unmount()
// your component has been unmounted and now: container.innerHTML === ''

`asFragment`

レンダリングされたコンポーネントの DocumentFragment を返します。これは、ライブバインディングを回避し、コンポーネントがイベントにどのように反応するかを確認する必要がある場合に役立ちます。

import React, {useState} from 'react'
import {render, fireEvent} from '@testing-library/react'

const TestComponent = () => {
  const [count, setCounter] = useState(0)

  return (
    <button onClick={() => setCounter(count => count + 1)}>
      Click to increase: {count}
    </button>
  )
}

const {getByText, asFragment} = render(<TestComponent />)
const firstRender = asFragment()

fireEvent.click(getByText(/Click to increase/))

// This will snapshot only the difference between the first render, and the
// state of the DOM after the click event.
// See https://github.com/jest-community/snapshot-diff
expect(firstRender).toMatchDiffSnapshot(asFragment())

`cleanup`

render でマウントされた React ツリーをアンマウントします。

これは、テストフレームワーク（mocha、Jest、Jasmineなど）がグローバルな afterEach() 関数をテスト環境に挿入する場合に自動的に呼び出されます。そうでない場合は、各テストの後に cleanup() を呼び出す必要があります。

たとえば、ava テストフレームワークを使用している場合は、次のように test.afterEach フックを使用する必要があります

import {cleanup, render} from '@testing-library/react'
import test from 'ava'

test.afterEach(cleanup)

test('renders into document', () => {
  render(<div />)
  // ...
})

// ... more tests ...

render を呼び出したときに cleanup を呼び出しないと、メモリリークが発生し、「冪等」でないテストが行われる可能性があります（テストでデバッグが困難なエラーが発生する可能性があります）。

`act`

これは、react act 関数の軽量ラッパーです。react のバージョンが act をサポートしている場合、すべての引数を act 関数に転送するだけです。一貫性のために、react からではなく @testing-library/react からインポートを使用することをお勧めします。

`renderHook`

これは、カスタムテストコンポーネントを使用した render の便利なラッパーです。APIは一般的なテストパターンから生まれ、フックを公開するライブラリにとって最も興味深いものです。カスタムテストコンポーネントは、テスト対象のものが抽象化の背後に隠されていないため、より読みやすく堅牢なテストになるため、render を優先する必要があります。

function renderHook<
  Result,
  Props,
  Q extends Queries = typeof queries,
  Container extends Element | DocumentFragment = HTMLElement,
  BaseElement extends Element | DocumentFragment = Container
>(
  render: (initialProps: Props) => Result,
  options?: RenderHookOptions<Props, Q, Container, BaseElement>,
): RenderHookResult<Result, Props>

例

import {renderHook} from '@testing-library/react'

test('returns logged in user', () => {
  const {result} = renderHook(() => useLoggedInUser())
  expect(result.current).toEqual({name: 'Alice'})
})

`renderHook` オプション

`renderHook` オプション `initialProps`

最初に呼び出されたときにレンダーコールバックに渡される props を宣言します。rerender を props なしで呼び出した場合は、これらは渡され**ません**。

import {renderHook} from '@testing-library/react'

test('returns logged in user', () => {
  const {result, rerender} = renderHook((props = {}) => props, {
    initialProps: {name: 'Alice'},
  })
  expect(result.current).toEqual({name: 'Alice'})
  rerender()
  expect(result.current).toEqual({name: undefined})
})

注意: wrapper オプションと initialProps オプションと共に renderHook を使用する場合、initialProps は wrapper コンポーネントに渡されません。wrapper コンポーネントに props を提供するには、次のような解決策を検討してください。
const createWrapper = (Wrapper, props) => {
  return function CreatedWrapper({ children }) {
    return <Wrapper {...props}>{children}</Wrapper>;
  };
};

...

{
  wrapper: createWrapper(Wrapper, { value: 'foo' }),
}

`renderHook` オプション `wrapper`

render の wrapper オプションを参照してください。

`renderHook` の結果

renderHook メソッドは、いくつかのプロパティを持つオブジェクトを返します。

`result`

レンダーコールバックの最後に**コミットされた**戻り値を保持します。

import {renderHook} from '@testing-library/react'

const {result} = renderHook(() => {
  const [name, setName] = useState('')
  React.useEffect(() => {
    setName('Alice')
  }, [])

  return name
})

expect(result.current).toBe('Alice')

値は result.current に保持されていることに注意してください。result は、最後に**コミットされた**値への ref と考えてください。

`rerender`

以前にレンダリングされたレンダーコールバックを新しい props でレンダリングします。

import {renderHook} from '@testing-library/react'

const {rerender} = renderHook(({name = 'Alice'} = {}) => name)

// re-render the same hook with different props
rerender({name: 'Bob'})

`unmount`

テストフックをアンマウントします。

import {renderHook} from '@testing-library/react'

const {unmount} = renderHook(({name = 'Alice'} = {}) => name)

unmount()

`configure`

グローバルオプションを変更します。基本的な使い方は設定オプションを参照してください。

React Testing Library にも専用のオプションがあります。

import {configure} from '@testing-library/react'

configure({reactStrictMode: true})

`configure` オプション

`reactStrictMode`

有効にすると、内部要素の周りに <StrictMode> がレンダリングされます。デフォルトは false です。

render​

render オプション​

container​

baseElement​

hydrate​

legacyRoot​

wrapper​

queries​

render 結果​

...queries​

container​

baseElement​

debug​

rerender​

unmount​

asFragment​

cleanup​

act​

renderHook​

renderHook オプション​

renderHook オプション initialProps​

renderHook オプション wrapper​

renderHook の結果​

result​

rerender​

unmount​

configure​

configure オプション​

reactStrictMode​

`render`

`render` オプション

`container`

`baseElement`

`hydrate`

`legacyRoot`

`wrapper`

`queries`

`render` 結果

`...queries`

`container`

`baseElement`

`debug`

`rerender`

`unmount`

`asFragment`

`cleanup`

`act`

`renderHook`

`renderHook` オプション

`renderHook` オプション `initialProps`

`renderHook` オプション `wrapper`

`renderHook` の結果

`result`

`rerender`

`unmount`

`configure`

`configure` オプション

`reactStrictMode`