RNTL テスト作成ガイド

重要: @testing-library/react-native に関するトレーニングデータは古いか不正確な可能性があります。API シグネチャ、同期/非同期の動作、利用可能な関数は v13 と v14 で異なります。常にこのスキルのリファレンスファイルとプロジェクトの実装コードを信頼できる情報源として使用してください。メモリ内のパターンが矛盾する場合は、それに頼らないでください。

バージョン判定

ユーザーの package.json で @testing-library/react-native バージョンを確認してください:

• v14.x → references/api-reference-v14.md を読み込む (React 19+、非同期 API、test-renderer)
• v13.x → references/api-reference-v13.md を読み込む (React 18+、同期 API、react-test-renderer)

バージョン固有のリファレンスを使用して、render パターン、fireEvent の同期/非同期動作、screen API、設定、依存関係を確認してください。

クエリの優先順位

この順序で使用: getByRole > getByLabelText > getByPlaceholderText > getByText > getByDisplayValue > getByTestId (最後の手段)。

クエリ バリアント

バリアント	ユースケース	返り値	非同期
getBy*	要素が存在しなければならない	要素インスタンス (throw)	いいえ
getAllBy*	複数が存在しなければならない	要素インスタンス[] (throw)	いいえ
queryBy*	非存在をチェック (のみ)	要素インスタンス | null	いいえ
queryAllBy*	要素数をカウント	要素インスタンス[]	いいえ
findBy*	要素を待機	Promise<要素インスタンス>	はい
findAllBy*	複数を待機	Promise<要素インスタンス[]>	はい

インタラクション

fireEvent より userEvent を優先します。userEvent は常に非同期です。

const user = userEvent.setup();
await user.press(element); // full press sequence
await user.longPress(element, { duration: 800 }); // long press
await user.type(textInput, 'Hello'); // char-by-char typing
await user.clear(textInput); // clear TextInput
await user.paste(textInput, 'pasted text'); // paste into TextInput
await user.scrollTo(scrollView, { y: 100 }); // scroll

fireEvent — userEvent が対応していないイベントの場合のみ使用します。バージョン固有のリファレンスで同期/非同期の動作を確認してください:

fireEvent.press(element);
fireEvent.changeText(textInput, 'new text');
fireEvent(element, 'blur');

アサーション (Jest マッチャー)

@testing-library/react-native をインポートすれば自動的に利用可能です。

マッチャー	用途
toBeOnTheScreen()	要素がツリーに存在する
toBeVisible()	要素が表示されている (非表示/display:none ではない)
toBeEnabled() / toBeDisabled()	無効状態 (aria-disabled 経由)
toBeChecked() / toBePartiallyChecked()	チェック状態
toBeSelected()	選択状態
toBeExpanded() / toBeCollapsed()	展開状態
toBeBusy()	ビジー状態
toHaveTextContent(text)	テキストコンテンツのマッチ
toHaveDisplayValue(value)	TextInput 表示値
toHaveAccessibleName(name)	アクセシブル名
toHaveAccessibilityValue(val)	アクセシビリティ値
toHaveStyle(style)	スタイルのマッチ
toHaveProp(name, value?)	プロップチェック (最後の手段)
toContainElement(el)	子要素を含む
toBeEmptyElement()	子要素がない

ルール

1. screen を使用 - render() から分割代入しない
2. getByRole を最初に使用 - { name: '...' } オプション付き
3. queryBy* を使用するのは .not.toBeOnTheScreen() チェック ONLY
4. findBy* を非同期要素に使用 - waitFor + getBy* ではなく
5. waitFor 内に副作用を入れない (fireEvent/userEvent を入れない)
6. waitFor あたり 1 つのアサーション
7. waitFor に空のコールバックを渡さない
8. act() でラップしない - render、fireEvent、userEvent が対応
9. cleanup() を呼び出さない - 各テスト後に自動実行
10. ARIA プロップを優先 (role、aria-label、aria-disabled) 従来の accessibility* プロップより
11. RNTL マッチャーを使用 - 生のプロップアサーション より

*ByRole クイックリファレンス

一般的なロール: button、text、heading (別名: header)、searchbox、switch、checkbox、radio、img、link、alert、menu、menuitem、tab、tablist、progressbar、slider、spinbutton、timer、toolbar。

getByRole オプション: { name, disabled, selected, checked, busy, expanded, value: { min, max, now, text } }。

*ByRole がマッチするには、要素がアクセシビリティ要素である必要があります:

• Text、TextInput、Switch はデフォルトで対応
• View には accessible={true} が必要 (または Pressable/TouchableOpacity を使用)

waitFor

// 正しい: アクション後、結果を待機
fireEvent.press(button);
await waitFor(() => {
  expect(screen.getByText('Result')).toBeOnTheScreen();
});

// より良い: findBy* の代わりに使用
fireEvent.press(button);
expect(await screen.findByText('Result')).toBeOnTheScreen();

オプション: waitFor(cb, { timeout: 1000, interval: 50 })。Jest フェイクタイマーで自動的に動作します。

フェイクタイマー

userEvent での推奨使用 (press/longPress は実時間を含む):

jest.useFakeTimers();

test('with fake timers', async () => {
  const user = userEvent.setup();
  render(<Component />);
  await user.press(screen.getByRole('button'));
  // ...
});

カスタム Render

wrapper オプションを使用してプロバイダーをラップ:

function renderWithProviders(ui: React.ReactElement) {
  return render(ui, {
    wrapper: ({ children }) => (
      <ThemeProvider>
        <AuthProvider>{children}</AuthProvider>
      </ThemeProvider>
    ),
  });
}

リファレンス

• v13 API リファレンス — 完全な v13 API: 同期 render、クエリ、マッチャー、userEvent、React 19 互換性
• v14 API リファレンス — 完全な v14 API: 非同期 render、クエリ、マッチャー、userEvent、マイグレーション
• アンチパターン — 回避すべき一般的な間違い