[Testing Library] getBy, queryBy, findByの違いと使い方

こんにちは、スペースマーケットのWebエンジニアのShotaです。
今回はTesting LibraryのgetBy, queryBy, findByの使い方を挙動とユースケースに分けてご紹介します。
コンポーネントのテストを書く時に参考にしてみてください。

getBy, getAllBy

要素の取得に使う基本的なメソッドです。
指定した条件に一致する要素を取得したいときに使用します。

	一致する要素がある場合	一致する要素が複数見つかった場合	一致する要素がない場合
getBy	一致する要素を返す	エラーを返す	エラーを返す
getAllBy	一致するすべての要素を配列で返す	一致するすべての要素を配列で返す	エラーを返す

ユースケース

expect(screen.getByRole('heading', { level: 1, name: 'タイトル' })).toBeInTheDocument();

h1タグの見出しが指定したテキストタイトルを持っているかを検証しています。
UIの要素が表示されていることを検証する時に使ってみましょう。

queryBy, queryAllBy

存在しない要素を取得する場合によく使うメソッドです。
一致する要素がないことを検証できます。

	一致する要素がある場合	一致する要素が複数見つかった場合	一致する要素がない場合
queryBy	一致する要素を返す	エラーを返す	nullを返す
queryAllBy	一致するすべての要素を配列で返す	一致するすべての要素を配列で返す	[]を返す

ユースケース

expect(screen.queryByRole('list')).not.toBeInTheDocument()

特定の要素role="list"を持つ要素がDOMに存在しないことを検証しています。
要素の削除後や非表示状態の確認に使えるので、最初から存在しないことを期待するならqueryBy, queryAllByを使いましょう。

findBy, findAllBy

要素を非同期に取得したい時に使うメソッドです。
非同期で要素を探しタイムアウトまで待機します。

	一致する要素がある場合	一致する要素が複数見つかった場合	一致する要素がない場合
findBy	Promise<要素>を返す	エラーを返す	エラーを返す
findAllBy	Promise<要素[]>を返す	Promise<要素[]>を返す	エラーを返す

ユースケース

test('...', async () => {...
  await expect(screen.findByText('照会中')).resolves.toBeInTheDocument()
})

照会中というテキストが非同期で表示されることを検証しています。
データ取得後に表示される要素の確認などに使いましょう。

補足

toBeInTheDocumentとtoBeVisible

toBeInTheDocument()で表示されているかのチェックは必ずしもできるわけではない点には注意が必要です。

// DOMにあれば display:none になっていてもこのテストは通る
expect(screen.getByRole('heading', { level: 1, name: 'タイトル' })).toBeInTheDocument();

// DOMにあるけど display:none なのでこのテストは落ちる（ブラウザでは表示されないから）
expect(screen.getByRole('heading', { level: 1, name: 'タイトル' })).toBeVisible();

	display:noneの要素がDOMにある場合
toBeInTheDocument	一致する要素を返す
toBeVisible	エラーを返す

https://qiita.com/kawabata324/items/39c2c4eedc94151c191f

まとめ

各メソッドの違い

メソッド	一致する要素がある場合	一致する要素が複数見つかった場合	一致する要素がない場合
getBy	一致する要素を返す	エラーを返す	エラーを返す
getAllBy	一致するすべての要素を配列で返す	一致するすべての要素を配列で返す	エラーを返す
queryBy	一致する要素を返す	エラーを返す	nullを返す
queryAllBy	一致するすべての要素を配列で返す	一致するすべての要素を配列で返す	[]を返す
findBy	Promise<要素>を返す	エラーを返す	エラーを返す
findAllBy	Promise<要素[]>を返す	Promise<要素[]>を返す	エラーを返す

各メソッドのユースケース

メソッド	ユースケース
getBy	送信ボタンが表示されていることを検証する
getAllBy	3件のデータが表示されていることを検証する
queryBy	削除済みのデータが表示されないことを検証する
queryAllBy	全てのブロック済みのユーザーが表示されないことを検証する
findBy	読み込みの処理を開始したら読み込み中が表示されることを検証する
findAllBy	検索条件ボタンを押した時に選択肢が10件表示されることを検証する

https://testing-library.com/docs/queries/about/