react-native-testing

React Native Testing Library

@testing-library/react-native v13 および v14 の詳細な API リファレンスです。

対象範囲： Jest と RNTL を使用したユニットテストおよびコンポーネントテストです。実機やシミュレーターでエンドツーエンドの UI フローをテストする場合は、Maestro を使用してください。宣言的な YAML フローでコードは不要です。ビルド済みアプリに対して実行します。RNTL と Maestro は相互補完するものであり、代替ではありません。

重要： API のシグネチャ、同期／非同期の動作、および利用可能な関数は、v13 と v14 で異なります。記憶しているパターンに頼らず、必ずプロジェクトの package.json を確認し、対応するバージョンのリファレンスを読み込んでください。

バージョンの検出

package.json の @testing-library/react-native を確認してください。

• v14.x → reference-v14-api を読み込みます（React 19 以降、非同期 API、test-renderer）
• v13.x → reference-v13-api を読み込みます（React 18 以降、同期 API、react-test-renderer）

主なリファレンス

トピック	説明	リファレンス
基本パターン	クエリの優先順位、render／screen、userEvent と fireEvent、waitFor、11 の基本ルール	core-patterns
v13 API（React 18）	同期 render、すべてのメソッド一覧、同期 fireEvent、React 19 互換シム	reference-v13-api
v14 API（React 19）	非同期 render、await ベースの API、削除された API、v13 から v14 への移行用 codemod	reference-v14-api
アンチパターン	誤ったクエリ、waitFor の誤用、不要な act、分割代入、await の付け忘れ	best-practices-anti-patterns

主な推奨事項

• クエリには必ず screen を使用してください。render() から分割代入しないでください。
• 最初に getByRole を使用してください。{ name: '...' } オプションを指定します（アクセシビリティに最も配慮した方法です）。
• 非同期の要素には findBy* を使用してください。waitFor と getBy* の組み合わせは使わないでください。
• fireEvent より userEvent を優先してください。より現実的な操作をシミュレートできます。
• queryBy* は要素が存在しないことを検証する場合にのみ使用してください（.not.toBeOnTheScreen()）。
• v14：すべての API で必ず await を付けてください（render、fireEvent、act を含む）。