メインコンテンツへスキップ

概要

コンポーネントテストとはコンポーネントを実際に描画し、ユーザーの操作を再現して、画面に現れる結果を検証するテストです。Testing Trophyでは、バックエンドとの境界をモックして振る舞いを検証するIntegration層にあたり、ツールにはVitestとTesting Libraryを使います。層の全体像はテスト戦略を参照してください。 本ページでは、コンポーネントテストが検証する対象を決める原則と、VitestとTesting Libraryで安定したテストを書く実践パターンを扱います。見た目の変化の検証はStorybookとビジュアルリグレッションテストの役割で、本ページでは扱いません。 個々のテストを信頼できる状態に保つ共通の原則(実行状態の検証、期待値の全体の検証、外部境界のモック)はテストコードを参照してください。本ページはその原則をコンポーネントに適用したものです。

原則

実装の詳細ではなく、ユーザーが観察できる振る舞いを検証する

コンポーネントテストの対象はユーザーが見て操作できるものです。Testing Libraryはこの方針を「テストがソフトウェアの使われ方に似ているほど、テストが与える信頼度は高くなる」という指針で表し、コンポーネントのインスタンスではなくDOMノードを扱うAPIだけを提供します。 コンポーネントには2種類の利用者がいます。描画された画面を操作するエンドユーザーと、propsを渡す開発者です。テストもこの2つの立場からだけコンポーネントに触れ、内部の状態、子コンポーネントに渡したprops、CSSクラス名のような実装の詳細には依存しません。 実装の詳細に依存したテストは、2つの方向で信頼できなくなります。構造を整理しただけで失敗する偽陰性と、画面が壊れていても内部の値が期待どおりなら通る偽陽性です。
Vitest + Testing Library

狭義のユニットテストと広義のユニットテストを使い分ける

ユニットテストには2つの意味があります。狭義のユニットテストは単一の関数を対象にし、金額の計算や日付範囲の正規化のような純粋なロジックを、描画を伴わないUnit層で入力と出力から検証します。 広義のユニットテストは、フックとコンポーネントの組み合わせが生み出す1つの振る舞いを対象にします。Reactのフックは多くの場合に関数を返すため、関数を1つずつ分離して検証しても画面が正しく振る舞う保証にはならず、振る舞いの単位でテストします。本ページのコンポーネントテストはこの広義のユニットテストにあたります。 この2つを使い分ける必要があるのは、どちらも同じテストランナー(Vitest)で実行され、同じテストファイルに書かれることが多いためです。関数の入出力を確かめる観点と、描画された画面の振る舞いを確かめる観点が1つのファイルに混ざると、一方のテストばかりが厚くなり、もう一方が薄くなっていても気づきにくくなります。テストを書くときは、どちらの観点で検証しているかを意識して区別します。

狭義のユニットテスト(Unit層)

純粋な関数の入力と出力。金額計算、日付の正規化、ソートの比較関数。描画を伴わず、Vitestだけで検証します。

広義のユニットテスト(Integration層)

コンポーネントとフックが組み合わさった振る舞い。操作に対する画面の変化を、Testing Libraryで検証します。

型で保証できることはStatic層に委ねる

コンポーネントテストはStatic層の上に成り立ちます。TypeScriptの型がpropsや状態の取りうる値を限定していれば、その範囲の外にある値(渡せないundefined、存在しないステータスなど)はコンパイルが拒否するため、コンポーネントテストで検証する必要はありません。検証はその失敗を検出できる最も低い層に置くというテスト戦略の原則を、Static層とIntegration層の間に適用したものです。 型が検証を引き受ける場面は多くあります。ある項目がnullになりうるのかundefinedになりうるのかを型が保証していれば、両方の場合のテストは不要で、型が許す側だけを検証します。取りうる値を文字列リテラルの合併型で限定したステータスや、必須と任意を区別したpropsも同じです。型が排除した値をテストから外すほど、コンポーネントテストは振る舞いの検証に集中できます。
Vitest + Testing Library
この分担はモックにも及びます。バックエンドの応答を差し替えるときにAPIを提供する側の型を付けておけば、APIの仕様変更はコンポーネントテストではなくStatic層の型チェックが検出します。具体的な方法は実践パターンの「モックの応答にはAPIを提供する側の型を付ける」のとおりです。

VitestとTesting Libraryでの実践パターン

以下のパターンは注文一覧の画面を題材にします。画面はステータスで注文を絞り込むフォームと、取得した注文を表示する表からなります。コード例はVitestのグローバルAPI(test、expect、vi)と、@testing-library/jest-domのマッチャーを前提としています。

ユーザーが見つけるのと同じ方法で要素を取得する

Testing Libraryのクエリには優先順位があります。最優先はすべてのユーザーに見える手がかりで要素を見つけるクエリで、ロールと名前で探すgetByRole、ラベルで探すgetByLabelText、表示文字列で探すgetByTextが属します。 getByTestIdは最後の手段です。テスト用の属性はユーザーには見えず、聞こえず、要素がロールや名前で見つからないこと自体が、アクセシビリティに問題がある可能性を示しています。DOM構造に依存するcontainer.querySelectorも構造を整理しただけで失敗するため使いません。
Vitest + Testing Library

操作はuser-eventで再現する

ユーザーの操作は@testing-library/user-eventで再現します。fireEventは単一のDOMイベントを発火するだけですが、user-eventはクリック時のフォーカス移動やキー入力ごとのイベント列のように、ブラウザで実際に起きる一連のイベントを再現します。 テストの先頭でuserEvent.setup()を呼び、返されたインスタンスで操作します。操作は非同期なのでawaitを付けます。
Vitest + Testing Library

非同期の画面変化は要素の出現で待つ

データの取得後に現れる要素はfindBy系のクエリで待ちます。findByは要素が現れるまで再試行し、見つからなければ既定の1秒で失敗するクエリです。固定時間の待機は短すぎると不安定になり、長すぎるとスイート全体を遅くします。 要素が消えたことや存在しないことは、queryBy系のクエリで検証します。getByは見つからないと例外を投げるため、不在の検証には使えません。要素の有無以外の条件を待つときはwaitForを使います。
Vitest + Testing Library

画面と独立したロジックのフックはrenderHookで検証する

renderHookはフックをコンポーネントの外で実行し、戻り値をresult.currentから読むためのAPIです。@testing-library/reactからインポートし、状態を更新する関数の呼び出しはactで囲みます。 対象は複数の画面から使われるロジックのフックや、UIを持たないフックです。1つの画面のためだけに存在するフックは、その画面のコンポーネントテストで操作を通して検証します。両方で検証すると、同じ振る舞いのテストが2重になり、変更のたびに2か所を直すことになります。
Vitest + Testing Library

バックエンドとの境界だけをモックする

コンポーネントテストでモックするのは、バックエンドとの境界だけです。応答はMock Service Worker(msw)でネットワークの境界で差し替えます。コンポーネントから見ると本物のHTTP通信が行われているため、APIクライアントやデータ取得のフックは本物のまま動き、モックの応答を解釈する処理の誤りまでテストが検出します。 子コンポーネント、フック、状態管理のストアは差し替えません。これらはコンポーネントが振る舞いを生み出す構成要素であり、差し替えるとテストコードのパターン3で述べる「検証対象のロジックそのものをモックする」状態になります。差し替えたテストは、実装がどう変わっても通り続けます。現在時刻やランダム値のような、ネットワーク以外の外部境界の扱いも同じページを参照してください。 正常系の応答はセットアップファイルに登録し、エラー応答のようなテスト固有の応答はserver.useでそのテストだけ上書きします。各テスト後にresetHandlersで上書きを戻し、テスト間の独立性を保ちます。
vitest.setup.ts
Vitest + Testing Library

モックの応答にはAPIを提供する側の型を付ける

mswで応答を差し替えている限り、実際のAPIの仕様が変わってもコンポーネントテストは通り続けます。ハンドラーを実際のAPIの仕様から乖離させないために、APIを提供する側から型情報を得て、ハンドラーの応答にその型を付けます。型の出所はOpenAPIドキュメントやGraphQLスキーマから生成した型、またはバックエンドと共有する型定義です。 型を付けておけば、APIの仕様変更はコンポーネントテストではなくStatic層の型チェックが検出します。コンポーネントテストは正しいと分かっているモックの上で動き続け、モックの正しさを型で担保することがこの層のテストの品質を支えます。原則で述べたStatic層との分担を、モックに適用したものです。
vitest.setup.ts

関連ページ

以下のページで、コンポーネントテストを置く層の判断と、その上下の層の詳細を扱います。

テスト戦略

検証をどの層に置くかの判断基準。コンポーネントテストがIntegration層で最も広い理由。

テストコード

本ページの原則の土台。実行状態の検証、期待値の全体の検証、外部境界のモック。

E2Eテスト

モックでは検出できないバックエンドとの連携を、主要な動線に絞って守る方法。

ビジュアルリグレッションテスト

同じ層の見た目の側。DOMのクエリには見えないものを、ストーリーとスナップショットで検証します。