react-testing-library

React Testing Library のベストプラクティス

Testing Library を使って React コンポーネントをテストするための、9 つのカテゴリーにわたる 43 のルールです。影響度の高い順に優先順位を付け、テストの作成とコードレビューを支援します。

対象範囲

このスキルでは、React コンポーネントとフックのテスト手法を扱います。 フレームワークに依存しない質問（ある振る舞いをどのレベルで扱うべきか、カバレッジの数値が何を意味するか、テストデータをどう選ぶか、不安定なテストをどう解消するか）には、 testing-expert を使用してください。

適用する場面

• React Testing Library を使った新しいコンポーネントテストの作成
• クエリの選択（getByRole、getByLabelText など）
• テストでの非同期処理の扱い（findBy、waitFor）
• ユーザー操作のシミュレーション（userEvent）
• アンチパターンや実装詳細のテストについてのテストレビュー

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
1	クエリの選択	CRITICAL	query-
2	非同期処理の扱い	CRITICAL	async-
3	よくあるアンチパターン	CRITICAL	anti-
4	ユーザー操作	HIGH	user-
5	アサーション	HIGH	assert-
6	コンポーネントのセットアップ	MEDIUM	setup-
7	テストの構成	MEDIUM	struct-
8	デバッグ	LOW-MEDIUM	debug-
9	アクセシビリティテスト	LOW	a11y-

クイックリファレンス

1. クエリの選択（CRITICAL）

• query-prefer-role - 他のクエリより getByRole を優先する
• query-avoid-testid - 主なクエリとして getByTestId を使わない
• query-use-screen - クエリには screen を使う
• query-label-text-forms - フォームフィールドには getByLabelText を使う
• query-role-name-option - getByRole では name オプションを使う
• query-get-vs-query - 要素がある場合は getBy、ない場合は queryBy を使う
• query-within-scope - クエリの対象範囲を絞るには within() を使う

2. 非同期処理の扱い（CRITICAL）

• async-findby-over-waitfor - waitFor + getBy の代わりに findBy を使う
• async-await-findby - findBy クエリには必ず await を付ける
• async-single-assertion-waitfor - waitFor 内のアサーションは 1 つにする
• async-no-side-effects-waitfor - waitFor 内で副作用を起こさない
• async-waitfor-disappear - waitForElementToBeRemoved を使う

3. よくあるアンチパターン（CRITICAL）

• anti-unnecessary-act - 不要な act() によるラップを避ける
• anti-manual-cleanup - 手動のクリーンアップ呼び出しを削除する
• anti-implementation-details - 実装詳細のテストを避ける
• anti-empty-waitfor - 空の waitFor コールバックを避ける
• anti-container-queries - クエリに container を使わない
• anti-redundant-roles - 冗長な ARIA ロールの追加を避ける

4. ユーザー操作（HIGH）

• user-prefer-userevent - fireEvent より userEvent を優先する
• user-setup-before-render - render の前に userEvent をセットアップする
• user-await-interactions - userEvent による操作には必ず await を付ける
• user-keyboard-for-special-keys - 特殊キーには keyboard() を使う
• user-clear-before-type - 入力し直す前に clear() を使う

5. アサーション（高）

• assert-dom-matchers - DOM マッチャーを使用する
• assert-visible-over-in-document - 可視性の確認には toBeVisible() を使用する
• assert-text-content - テキストの確認には toHaveTextContent() を使用する
• assert-have-value - 入力値の確認には toHaveValue() を使用する
• assert-accessible-description - toHaveAccessibleDescription() を使用する

6. コンポーネントのセットアップ（中）

• setup-wrapper-providers - プロバイダーには wrapper オプションを使用する
• setup-custom-render - プロバイダーを含むカスタムの render を作成する
• setup-mock-modules - モジュールレベルでモジュールをモックする
• setup-fake-timers - フェイクタイマーを使って userEvent を設定する
• setup-render-hook - フックのテストには renderHook を使用する

7. テスト構成（中）

• struct-arrange-act-assert - Arrange-Act-Assert パターンに従う
• struct-one-behavior-per-test - 1つのテストにつき1つの動作をテストする
• struct-descriptive-names - 内容がわかるテスト名を付ける
• struct-avoid-beforeeach-render - beforeEach 内での render() を避ける

8. デバッグ（低〜中）

• debug-screen-debug - DOM の確認には screen.debug() を使用する
• debug-logroles - 利用可能なロールの確認には logRoles を使用する
• debug-testing-playground - クエリには Testing Playground を使用する

9. アクセシビリティテスト（低）

• a11y-role-queries-verify - ロールクエリでアクセシビリティを検証する
• a11y-verify-focus - フォーカス管理をテストする
• a11y-test-aria-states - ARIA の状態とプロパティをテストする

使用方法

詳しい説明とコード例については、各リファレンスファイルを参照してください。

• セクションの定義 - カテゴリー構成と影響度レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルールのテンプレート