React Nativeモバイルエディター - React Native統合テストガイド（React Native Integration Test Guide）

統合テストとは何ですか？
統合テストの構造
セットアップ
レンダリング
- スコープ付きコンポーネントアプローチの使用
- 全体のエディターアプローチの使用
要素のクエリ
- findクエリの使用
- withinクエリ
イベントの発火
正しい要素の動作を期待する
クリーンアップ
ヘルパー
一般的なフロー
ツール
- アクセシビリティインスペクターの使用
一般的な落とし穴と注意点
- waitFor関数の前にawaitを省略した場合の偽陽性

統合テストとは何ですか？

統合テストは、異なる部分がグループとしてテストされるテストの一種として定義されます。私たちの場合、テストしたい部分は、特定のブロックまたはエディターロジックのレンダリングに必要な異なるコンポーネントです。最終的には、これらはユニットテストと非常に似ており、Jestライブラリを使用して同じコマンドで実行されます。主な違いは、統合テストでは、エディターが異なるコンポーネントをどのようにレンダリングするかをテストするために特定のライブラリreact-native-testing-libraryを使用することです。

統合テストの構造

テストは以下の部分で構成できます：

セットアップ
レンダリング
要素のクエリ
イベントの発火
正しい要素の動作を期待する
クリーンアップ

次のセクションでは、一般的なタスクの例やヒントも含めています：

ヘルパー
一般的なフロー
ツール
一般的な落とし穴と注意点

セットアップ

この部分は通常、Jestのコールバック[beforeAll]と[beforeEach]を使用してカバーされます。目的は、ブロックの登録やロジックの一部をモックするなど、テストが必要とするすべてを準備することです。

すべてのコアブロックが利用可能であることを期待する場合の一般的なパターンの例を示します：

beforeAll( () => {
   // Register all core blocks
   registerCoreBlocks();
} );

レンダリング

テストロジックを導入する前に、テストしたいコンポーネントをレンダリングする必要があります。スコープ付きコンポーネントを使用するか、全体のエディターアプローチを使用するかによって、この部分は異なります。

スコープ付きコンポーネントアプローチの使用

カバーブロックをレンダリングする例（[https://github.com/WordPress/gutenberg/blob/86cd187873984f80ddeeec3e82454b486dd1860f/packages/block-library/src/cover/test/edit.native.js#L82-L91]から抽出）：

// This import points to the index file of the block
import { metadata, settings, name } from '../index';
...
const setAttributes = jest.fn();
const attributes = {
   backgroundType: IMAGE_BACKGROUND_TYPE,
   focalPoint: { x: '0.25', y: '0.75' },
   hasParallax: false,
   overlayColor: { color: '#000000' },
   url: 'mock-url',
};
...
// Simplified tree to render Cover edit within slot
const CoverEdit = ( props ) => (
   <SlotFillProvider>
   <BlockEdit isSelected name={ name } clientId={ 0 } { ...props } />
   <BottomSheetSettings isVisible />
   </SlotFillProvider>
);
const { getByText, findByText } = render(
   <CoverEdit
   attributes={ {
   ...attributes,
   url: undefined,
   backgroundType: undefined,
   } }
   setAttributes={ setAttributes }
   />
);

全体のエディターアプローチの使用

ボタンブロックをレンダリングする例（[https://github.com/WordPress/gutenberg/blob/9201906891a68ca305daf7f8b6cd006e2b26291e/packages/block-library/src/buttons/test/edit.native.js#L32-L39]から抽出）：

const initialHtml = `<!-- wp:buttons -->
<div class="wp-block-buttons"><!-- wp:button {"style":{"border":{"radius":"5px"}}} -->
<div class="wp-block-button"><a class="wp-block-button__link" style="border-radius:5px" >Hello</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons -->`;
const { getByLabelText } = initializeEditor( {
   initialHtml,
} );

要素のクエリ

コンポーネントがレンダリングされたら、それらをクエリする時間です。このトピックに関する重要な注意点は、ユーザーの視点からテストする必要があるということです。これは、理想的には、ユーザーがアクセスできるテキストやアクセシビリティラベルなどの要素でクエリする必要があることを意味します。

クエリする際は、次の優先順位に従う必要があります：

1. getByText：テキストによるクエリは、ユーザーの視点からできる最も近いフローです。テキストは、要素を特定するための視覚的手がかりです。
2. getByLabelText：場合によっては、テキストを提供しない要素をクエリしたいので、この場合はアクセシビリティラベルにフォールバックできます。
3. getByTestId：前のオプションのいずれも適合しない場合、または依存できる視覚的要素がない場合は、特定のテストIDにフォールバックする必要があります。これは、[testID]属性を使用して定義できます（例については[https://github.com/WordPress/gutenberg/blob/e5b387b19ffc50555f52ea5f0b415ab846896def/packages/block-editor/src/components/block-types-list/index.native.js#L80]を参照）。

以下は、いくつかの例です：

const mediaLibraryButton = getByText( 'WordPress Media Library' );

const missingBlock = getByLabelText( /Unsupported Block\. Row 1/ );

const radiusSlider = getByTestId( 'Slider Border Radius' );

これらのクエリには、プレーンな文字列または正規表現を渡すことができます。正規表現は、文字列の一部をクエリするのに最適です（例：アクセシビリティラベルにUnsupported Block. Row 1を含む任意の要素）。.のような特殊文字はエスケープする必要があります。

findクエリの使用

コンポーネントをレンダリングしたりイベントを発火させたりした後、潜在的な状態の更新により副作用が発生する可能性があるため、探している要素がまだレンダリングされていない場合があります。この場合、要素が利用可能になるのを待つ必要があり、その目的のために、find*バージョンのクエリ関数を使用できます。これらは内部でwaitForを使用し、要素が表示されたかどうかを定期的にチェックします。

以下は、いくつかの例です：

const mediaLibraryButton = await findByText( 'WordPress Media Library' );

const missingBlock = await findByLabelText( /Unsupported Block\. Row 1/ );

const radiusSlider = await findByTestId( 'Slider Border Radius' );

ほとんどの場合、find*関数を使用しますが、要素が利用可能になるのを待つ必要があるクエリに制限することが重要です。

withinクエリ

他の要素に含まれる要素をwithin関数を介してクエリすることも可能です。以下はその例です：

const missingBlock = await findByLabelText( /Unsupported Block\. Row 1/ );
const translatedTableTitle = within( missingBlock ).getByText( 'Tabla' );

イベントの発火

要素をクエリすることと同じくらい重要なのは、ユーザーのインタラクションをシミュレートするためにイベントをトリガーすることです。その目的のために、fireEvent関数を使用できます（ドキュメント）。

プレスイベントの例：

プレスイベント：

fireEvent.press( settingsButton );

任意のタイプのイベント、カスタムイベントをトリガーすることもできます。以下の例では、スライダーコンポーネントのonValueChangeイベントをトリガーする方法を示しています（コードリファレンス：

カスタムイベント – onValueChange：

fireEvent( heightSlider, 'valueChange', '50' );

正しい要素の動作を期待する

要素をクエリし、イベントを発火させた後、ロジックが期待通りに機能することを確認する必要があります。その目的のために、ユニットテストで使用するのと同じexpect関数を使用できます。要素が定義されていること、有効なReact要素であること、可視であることを確認するために、カスタムtoBeVisibleマッチャーを使用することをお勧めします。

以下はその例です：

const translatedTableTitle = within( missingBlock ).getByText( 'Tabla' );
expect( translatedTableTitle ).toBeVisible();

さらに、エディター全体をレンダリングする際に、HTML出力が期待通りであるかどうかも確認できます：

expect( getEditorHtml() ).toBe(
   '<!-- wp:spacer {"height":50} -->\n<div style="height:50px" aria-hidden="true" class="wp-block-spacer"></div>\n<!-- /wp:spacer -->'
);

クリーンアップ

最後に、次のテストに影響を与える可能性のある変更をクリーンアップする必要があります。以下は、すべてのブロックを登録解除することを含む、ブロック登録後の典型的なクリーンアップの例です：

afterAll( () => {
   // Clean up registered blocks
   getBlockTypes().forEach( ( block ) => {
   unregisterBlockType( block.name );
   } );
} );

ヘルパー

ネイティブバージョンの統合テストを簡単に書くための精神で、このREADMEにヘルパー関数のリストがあります。

一般的なフロー

ブロックをクエリする

ブロックをクエリする一般的な方法は、そのアクセシビリティラベルによるものです。以下はその例です：

const spacerBlock = await waitFor( () =>
   getByLabelText( /Spacer Block\. Row 1/ )
);

ブロックのアクセシビリティラベルに関する詳細情報は、関数getAccessibleBlockLabelのコードを確認できます。

ブロックを追加する

段落ブロックを挿入する方法の例を示します：

// Open the inserter menu
fireEvent.press( await findByLabelText( 'Add block' ) );
const blockList = getByTestId( 'InserterUI-Blocks' );
// onScroll event used to force the FlatList to render all items
fireEvent.scroll( blockList, {
   nativeEvent: {
   contentOffset: { y: 0, x: 0 },
   contentSize: { width: 100, height: 100 },
   layoutMeasurement: { width: 100, height: 100 },
   },
} );
// Insert a Paragraph block
fireEvent.press( await findByText( `Paragraph` ) );

ブロック設定を開く

ブロックを選択した後、「設定を開く」ボタンをタップすることでブロック設定にアクセスできます。以下はその例です：

fireEvent.press( block );
const settingsButton = await findByLabelText( 'Open Settings' );
fireEvent.press( settingsButton );

スコープ付きコンポーネントアプローチの使用

スコープ付きコンポーネントアプローチを使用する場合、最初にSlotFillProviderとBottomSheetSettingsをレンダリングする必要があります（isVisibleプロパティを渡してボトムシートを表示させることに注意してください）。

<SlotFillProvider>
   <BlockEdit isSelected name={ name } clientId={ 0 } { ...props } />
   <BottomSheetSettings isVisible />
</SlotFillProvider>

例を参照してください：

カバーブロック

FlatListアイテム


以下は、挿入メニューでブロックリストをレンダリングするために使用されるFlatListの例です：  
``````bash
const blockList = getByTestId( 'InserterUI-Blocks' );
// onScroll event used to force the FlatList to render all items
fireEvent.scroll( blockList, {
   nativeEvent: {
   contentOffset: { y: 0, x: 0 },
   contentSize: { width: 100, height: 100 },
   layoutMeasurement: { width: 100, height: 100 },
   },
} );
`

スライダー

ボトムシートにあるスライダーは、testIDを使用してクエリする必要があります：

const radiusSlider = await findByTestId( 'Slider Border Radius' );
fireEvent( radiusSlider, 'valueChange', '30' );

スライダーのtestIDは「スライダー」+ラベルです。したがって、「ボーダー半径」というラベルのスライダーの場合、testIDは「スライダーボーダー半径」となります。

内部ブロックの選択

ブロックを追加する際の注意点は、内部ブロックを含む場合、これらの内部ブロックはレンダリングされないことです。以下の例は、ボタンブロックがその内部ボタンブロックをレンダリングする方法を示しています（buttonsBlockとしてボタンブロックへの参照をすでに取得していると仮定します）：

const innerBlockListWrapper = await within( buttonsBlock ).findByTestId(
   'block-list-wrapper'
);
fireEvent( innerBlockListWrapper, 'layout', {
   nativeEvent: {
   layout: {
   width: 100,
   },
   },
} );
const buttonInnerBlock = await within( buttonsBlock ).findByLabelText(
   /Button Block\. Row 1/
);
fireEvent.press( buttonInnerBlock );

ツール

アクセシビリティインスペクターの使用

要素の識別子を見つけるのに問題がある場合は、Xcodeのアクセシビリティインスペクターを使用することをお勧めします。ほとんどの識別子はクロスプラットフォームであるため、テストはデフォルトでAndroidで実行されますが、アクセシビリティインスペクターを使用して正しい識別子を見つけることができます。

Xcodeアクセシビリティインスペクターアプリのスクリーンショット。スクリーンショットは、デバイスのドロップダウンで正しいターゲットを選択し、ターゲットモードを有効にし、画面要素をタップした後にアクセシビリティラベルを見つける方法を示しています

一般的な落とし穴と注意点

waitFor関数の前にawaitを省略した場合の偽陽性

 <a name="waitfor-timeout"></a>
### waitForタイムアウト
`````waitFor`````関数のデフォルトタイムアウトは1000msに設定されているため、これまでのところ、この値はテストしているすべてのレンダーロジックに十分です。ただし、テスト中に要素のレンダリングにもっと時間がかかることに気付いた場合は、増やす必要があります。  
 <a name="replace-current-ui-unit-tests"></a>
### 現在のUIユニットテストの置き換え
一部のコンポーネントには、コンポーネントのレンダリングをカバーするユニットテストがすでにありますが、必須ではありません。これらの場合、統合テストへの移行の可能性を分析することが望ましいです。  
両方を保持する必要がある場合は、名前の衝突を避けるために、統合テストファイルに「integration」という単語を追加します。以下はその例です：[packages/block-library/src/missing/test/edit-integration.native.js](https://github.com/WordPress/gutenberg/blob/9201906891a68ca305daf7f8b6cd006e2b26291e/packages/block-library/src/missing/test/edit-integration.native.js)。  
 <a name="platform-selection"></a>
### プラットフォームの選択
デフォルトでは、すべてのテストはJestでAndroidプラットフォームを使用して実行されるため、異なるプラットフォームに関連する特定の動作をテストする必要がある場合は、プラットフォームテストファイルをサポートする必要があります。  
プラットフォームオブジェクトによって制御されるロジックのみをテストする必要がある場合は、次のコードを使用してモジュールをモックできます（この場合、プラットフォームをiOSに変更します）：  
``````bash
jest.mock( 'Platform', () => {
   const Platform = jest.requireActual( 'Platform' );
   Platform.OS = 'ios';
   Platform.select = jest.fn().mockImplementation( ( select ) => {
   const value = select[ Platform.OS ];
   return ! value ? select.default : value;
   } );
   return Platform;
} );
`