react-testing-library

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

AI エージェントと LLM 向けに設計された、Testing Library を使った React コンポーネントの包括的なテストガイドです。影響度に基づいてテストの作成とコードレビューを導く、9 つのカテゴリーにわたる 43 のルールを収録しています。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• 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 - 手動の 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-jest-dom-matchers - jest-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 - 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	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報