始める前に
TIP: このガイドは、すでにコンポーネントハーネスの概要ガイドを読んでいることを前提としています。コンポーネントハーネスの使用が初めての場合は、まずそちらをお読みください。
テスト環境のサポートを追加するのはどのような場合ですか？
以下の環境でコンポーネントハーネスを使用するには、Angular CDKの2つの組み込み環境を使用できます。
- 単体テスト
- WebDriverエンドツーエンドテスト
サポートされているテスト環境を使用するには、コンポーネントのハーネスを作成するガイドをお読みください。
それ以外の場合、他の環境のサポートを追加するには、DOM要素との対話方法と、その環境でDOMの対話がどのように機能するかを定義する必要があります。詳細については、引き続きお読みください。
CDKのインストール
Component Dev Kit (CDK)は、コンポーネントを構築するための動作プリミティブのセットです。コンポーネントハーネスを使用するには、まずnpmから@angular/cdkをインストールします。これは、Angular CLIを使用してターミナルから実行できます。
ng add @angular/cdk
TestElement実装の作成 {#creating-a-testelement-implementation}
すべてのテスト環境はTestElement実装を定義する必要があります。TestElementインターフェースは、DOM要素の環境に依存しない表現の役割を果たします。これにより、ハーネスは基盤となる環境に関係なくDOM要素と対話できます。一部の環境ではDOM要素との同期的な対話がサポートされていないため（例: WebDriver）、すべてのTestElementメソッドは非同期であり、操作の結果をPromiseで返します。
TestElementは、blur()、click()、getAttribute()など、基盤であるDOMと対話するための多数のメソッドを提供します。メソッドの完全なリストについては、TestElement APIリファレンスページを参照してください。
TestElementインターフェースは、主にHTMLElementで利用可能なメソッドに似たメソッドで構成されています。ほとんどのテスト環境には同様のメソッドが存在するため、それらのメソッドの実装は非常に簡単です。ただし、sendKeysメソッドを実装する際に注意すべき重要な違いは、TestKey enumのキーコードがテスト環境で使用されるキーコードと異なる可能性があることです。環境の作成者は、TestKeyコードから特定のテスト環境で使用されるコードへのマッピングを維持する必要があります。
Angular CDKのUnitTestElementとSeleniumWebDriverElementの実装は、このインターフェースの実装の良い例として機能します。
HarnessEnvironmentの実装を作成する
テスト作成者は、テストで使用するコンポーネントハーネスインスタンスを作成するためにHarnessEnvironmentを使用します。HarnessEnvironmentは、新しい環境のための具象サブクラスを作成するために拡張されなければならない抽象クラスです。新しいテスト環境をサポートする場合、すべての抽象メンバーに具象実装を追加するHarnessEnvironmentサブクラスを作成します。
HarnessEnvironmentにはジェネリック型パラメータHarnessEnvironment<E>があります。このパラメータEは、環境の生要素型を表します。例えば、このパラメータは単体テスト環境ではElementです。
以下は、実装する必要がある抽象メソッドです。
| Method | Description |
|---|---|
abstract getDocumentRoot(): E |
環境のルート要素（例: document.body）を取得します。 |
abstract createTestElement(element: E): TestElement |
指定された生要素のTestElementを作成します。 |
abstract createEnvironment(element: E): HarnessEnvironment |
指定された生要素をルートとするHarnessEnvironmentを作成します。 |
abstract getAllRawElements(selector: string): Promise<E[]> |
環境のルート要素の下にある、指定されたセレクターに一致するすべての生要素を取得します。 |
abstract forceStabilize(): Promise<void> |
NgZoneが安定したときに解決するPromiseを取得します。さらに、該当する場合、NgZoneに安定化を指示します（例: fakeAsyncテストでflush()を呼び出す）。 |
abstract waitForTasksOutsideAngular(): Promise<void> |
NgZoneの親ゾーンが安定したときに解決するPromiseを取得します。 |
欠落しているメソッドを実装することに加えて、このクラスはテスト作成者がComponentHarnessインスタンスを取得する方法を提供する必要があります。保護されたコンストラクターを定義し、HarnessLoaderインスタンスを返すloaderという静的メソッドを提供する必要があります。これにより、テスト作成者はSomeHarnessEnvironment.loader().getHarness(...)のようなコードを記述できます。特定の環境のニーズに応じて、クラスはいくつかの異なる静的メソッドを提供したり、引数を渡すことを要求したりする場合があります。（例: TestbedHarnessEnvironmentのloaderメソッドはComponentFixtureを取り、クラスはdocumentRootLoaderとharnessForFixtureという追加の静的メソッドを提供します）。
Angular CDKのTestbedHarnessEnvironmentとSeleniumWebDriverHarnessEnvironmentの実装は、このインターフェースの実装の良い例として役立ちます。
自動での変更検知のハンドリング
manualChangeDetectionと並列APIをサポートするために、お使いの環境は自動での変更検知ステータス用のハンドラーをインストールする必要があります。
お使いの環境が自動での変更検知ステータスのハンドリングを開始したい場合、handleAutoChangeDetectionStatus(handler)を呼び出すことができます。ハンドラー関数は、isDisabledとonDetectChangesNow()の2つのプロパティを持つAutoChangeDetectionStatusを受け取ります。詳細については、AutoChangeDetectionStatus APIリファレンスページを参照してください。
お使いの環境が自動での変更検知ステータスのハンドリングを停止したい場合、stopHandlingAutoChangeDetectionStatus()を呼び出すことができます。