2025 年 3 月 27 日より、AOSP のビルドとコントリビューションには aosp-main ではなく android-latest-release を使用することをおすすめします。詳細については、AOSP の変更をご覧ください。
CTS デバイス インタラクション ヘルパー モジュール
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
Android 11 以降では、互換性テストスイート（CTS）デバイス インタラクション ヘルパー モジュールを使用すると、CTS テストで特定のデバイスのユーザー インターフェース（UI）を操作する方法をカスタマイズできます。つまり、Android 互換性定義ドキュメント（CDD）または API ドキュメントに記載されていない UI 要素の置き換えなどのアクションは、CTS に合格したまま行えます。
プロダクトを開発する際に Android UI をカスタマイズし、CTS に合格する必要がある OEM は、ヘルパー モジュールを実装できる場合があります。デフォルトの Android 実装を使用する場合、追加の作業は必要ありません。
ヘルパー モジュールの実装
UI をカスタマイズするための要件
UI の要件について、CDD モジュールまたはメインライン モジュールを確認します。目的の UI が CDD モジュールかメインライン モジュールでカバーされている場合、その UI はカスタマイズできません。
目的の UI を操作する CTS テストでヘルパー フレームワークを使用しない場合、その UI はカスタマイズできません。テストオーナーと協力して、UI を変更する前にテスト モジュールを変換してください。
それ以外の場合は、UI をカスタマイズできます。
実装ワークフロー
- 特定のプロダクトに合わせて UI をカスタマイズします。
- 既存の AOSP ヘルパー モジュールを、UI を操作する必要がある CTS テスト モジュールのサブクラスとして指定します。必要な操作は、カスタマイズ対象の UI に合わせて適切に置き換えます。置き換えは、変更の種類によって異なります。
- OEM サブクラスは、
com.[oem].cts.helpers などの OEM パッケージに含まれています。
- 各 OEM サブクラスの名前には、接頭辞
Default が付けられた AOSP 実装と区別する、共通の接頭辞が付けられます。
- 次に示すテストランナーの規則に従って、ヘルパーを APK に組み込みます。
Android.bp は、含まれているパッケージと同じ名前で android_test_helper_app を宣言する必要があります。- APK の
AndroidManifest.xml は、前の箇条書きで選択したクラス接頭辞の値を使用して、interaction-helpers-prefix というメタデータ プロパティを宣言する必要があります。
- アプリは、
cts-helpers-core、cts-helpers-interfaces、com.android.cts.helpers.aosp に依存する必要があります。OEM ヘルパーが関連するインターフェースすべてを完全に実装している場合、com.android.cts.helpers.aosp は省略可能です。
- APK の名前を含めるように、デバイス イメージの
ro.vendor.cts_interaction_helper_packages プロパティを設定します。ヘルパー実装を複数の APK に分割する必要がある場合、このプロパティにはパッケージのコロン区切りリストを含めることができます。
- CTS の Tradefed を実行しているとき、
testcases ディレクトリで APK が利用可能であることを確認します。必要に応じ、logcat メッセージを調べて、期待されるヘルパー実装クラスが選択されていることを確認します。
- （省略可能ですが強くおすすめします）ヘルパー実装を AOSP に送信するか、サードパーティ テストで使用できるようにします。
ヘルパー実装の例
たとえば、CtsPrintTestCases は、ICtsPrintHelper で定義されたインターフェースを持つヘルパーを期待します。AOSP 実装は com.android.cts.helpers.aosp.DefaultCtsPrintHelper と呼ばれます。
プリント UI をカスタマイズする場合は、DefaultCtsPrintHelper をサブクラス化する com.oem.cts.helpers.OemCtsPrintHelper を作成できます。Android.bp の android_test_helper_app は com.oem.cts.helpers という名前を付けられ、com.oem.cts.helpers.apk を生成し、AndroidManifest.xml で interaction-helpers-prefix を Oem として宣言します。
デバイス プロパティ ro.vendor.cts_interaction_helper_packages は com.oem.cts.helpers に設定されます。
リファレンス実装
リファレンス実装には、cts/libs/helpers のインターフェースと、cts/helpers のデフォルトの AOSP ヘルパーが含まれます。トップレベル インターフェースは cts/libs/helpers/core/src/com/android/cts/helpers/ICtsDeviceInteractionHelper.java に記載されています。
CTS テストをヘルパーに接続するために、テストオーナーは cts/libs/helpers/core/src/com/android/cts/helpers/DeviceInteractionHelperRule.java に記載されている @Rule 定義を使用できます。
フレームワークを使用する各 CTS モジュールと、その期待されるヘルパー動作は、cts/libs/helpers/core/src/com/android/cts/helpers で定義されたインターフェースに記載されています。
CTS テストの実行
ヘルパーなしのテスト
1 つのプロパティを除き、実行時、ヘルパーなしでテストするオプションはデバイスに存在しませんが、オプションで CTS テストがデバイスを操作する方法を変更します。ヘルパー実装なしで CTS を実行する必要がある場合、次の 2 つのオプションがあります。
- デバイスから
ro.vendor.cts_interaction_helper_packages プロパティを削除します。これにより、ヘルパーはそのビルドでまったく使用されなくなります。
- CTS を実行する前に、
testcases ディレクトリからヘルパー APK を削除します。これにより、APK が testcases に復元されるまで、実行でヘルパーが使用されなくなります。
デフォルト設定は、Tradefed 引数と ro.vendor.cts_interaction_helper_packages プロパティ コントロールを使用して変更できます。これはヘルパー APK の読み込み元です。
使用可能な各設定の期待される値または範囲については、下記をご覧ください。
ro.vendor.cts_interaction_helper_packages は、パッケージ名を含むコロン区切りの文字列です。OEM のヘルパー実装で有効なパッケージ選択であれば、任意の値を取ることができます。cts-tradefed は、--module-arg 'CtsPrintTestCases:{device-interaction-helper}property-name:debug.cts.hlp' などの 1 回のテスト実行で期待されるプロパティを一時的に変更する device-interaction-helper:property-name 引数を受け入れます。プロパティ名の値には、デバイスで設定した任意のプロパティを使用できます。プロパティの値は、上記の ro.vendor.cts_interaction_helper_packages プロパティと同じ制限に従います。
カスタマイズを伴うテスト
デフォルトでは、リファレンス実装はストック Android で CTS を渡します。パートナーの実装が、UI のカスタマイズを伴う CTS に合格することを確認します。カスタマイズした UI または機能をカバーする CTS モジュールを実行します。
CTS モジュールまたはヘルパーの中には、まだ一部のカスタマイズをサポートしていないものもあります。
- カスタマイズする UI を操作する CTS モジュールは、ヘルパー フレームワークを使用しない場合があります。CTS モジュールは、需要とテストオーナーの優先順位に基づいてヘルパー フレームワークに変換されることが期待されます。計画した機能をサポートするために CTS の変更をリクエストする場合と同様、変換がスケジュールどおりに行われるように、プロセスの早い段階で変換をリクエストします。
- 既存のヘルパーによって提供される関数は、実施するカスタマイズに完全には対応していない場合があります。ヘルパー関数は UI の依存関係を抽象化する必要があります。ヘルパー関数に間接的に UI の依存関係がある場合、CTS のバグと同様に扱うことができます。
このページのコンテンツやコードサンプルは、コンテンツ ライセンスに記載のライセンスに従います。Java および OpenJDK は Oracle および関連会社の商標または登録商標です。
最終更新日 2025-05-08 UTC。
[[["わかりやすい","easyToUnderstand","thumb-up"],["問題の解決に役立った","solvedMyProblem","thumb-up"],["その他","otherUp","thumb-up"]],[["必要な情報がない","missingTheInformationINeed","thumb-down"],["複雑すぎる / 手順が多すぎる","tooComplicatedTooManySteps","thumb-down"],["最新ではない","outOfDate","thumb-down"],["翻訳に関する問題","translationIssue","thumb-down"],["サンプル / コードに問題がある","samplesCodeIssue","thumb-down"],["その他","otherDown","thumb-down"]],["最終更新日 2025-05-08 UTC。"],[],[],null,["# CTS device interaction helper module\n\nFor Android 11 or higher, the Compatibility Test Suite\n(CTS) device interaction helper modules let you customize how certain CTS\ntests interact with the user interface (UI) on a specific device. This means\nthat actions, such as replacing a UI element that isn't covered by the\n[Android Compatibility Definition Document (CDD)](/docs/compatibility/cdd)\nor API docs, can be done while still passing CTS.\n\nOEMs who want to customize the Android UI during product development and need\nto pass CTS might be able to implement helper modules. If you use the default\nAndroid implementation, then no additional work is needed.\n\nImplementing helper modules\n---------------------------\n\n### Requirements to customize the UI\n\nCheck the CDD or Mainline modules for any UI requirements. If the desired UI is\ncovered by the CDD or Mainline modules, then that UI can't be customized.\n\nIf the CTS tests that interact with the desired UI don't use the\nhelper framework, then that UI can't be customized. Work\nwith the test owner to convert the test module before the UI can be changed.\n\nOtherwise, you can customize the UI.\n\n### Implementation workflow\n\n1. Customize the UI as needed for your specific product.\n2. Designate the existing AOSP helper modules as subclasses for the CTS test modules that need to interact with the UI. Replace the necessary interactions appropriately for the customized UI. Replacements vary depending on the type of changes.\n - The OEM subclasses are in an OEM package, such as `com.[oem].cts.helpers`.\n - Each OEM subclass is named with a common prefix that distinguishes it from the AOSP implementation, which has the prefix `Default`.\n3. Build the helpers into an APK following these test runner conventions.\n - `Android.bp` should declare `android_test_helper_app` with the same name as the contained package.\n - `AndroidManifest.xml` for the APK must declare a metadata property named `interaction-helpers-prefix` with the value of the class prefix chosen in the previous bullet point.\n - The app should depend on `cts-helpers-core`, `cts-helpers-interfaces`, and `com.android.cts.helpers.aosp`. If the OEM helpers fully implement all relevant interfaces, then `com.android.cts.helpers.aosp` is optional.\n4. Set the `ro.vendor.cts_interaction_helper_packages` property in the device image to include the name of the APK. If you need to separate your helper implementations across multiple APKs, this property can contain a colon-separated list of packages.\n5. Ensure that the APK is available in the `testcases` directory when running Tradefed for CTS. If needed, confirm that the expected helper implementation class is chosen by examining logcat messages.\n6. Optional, but highly recommended: Submit your helper implementation to AOSP or make it available for third-party testing.\n\n#### Example helper implementation\n\nFor example, `CtsPrintTestCases` expects a helper with the interface defined\nin `ICtsPrintHelper`. The AOSP implementation is called\n`com.android.cts.helpers.aosp.DefaultCtsPrintHelper`.\n\nIf you customize the print UI, you can create\n`com.oem.cts.helpers.OemCtsPrintHelper` that subclasses `DefaultCtsPrintHelper`.\n`android_test_helper_app` in `Android.bp` is named `com.oem.cts.helpers`,\nwhich produces `com.oem.cts.helpers.apk`,\nand declares `interaction-helpers-prefix` as `Oem` in `AndroidManifest.xml`.\n\nThe device property `ro.vendor.cts_interaction_helper_packages` is set to\n`com.oem.cts.helpers`.\n\n### Reference implementations\n\nReference implementations include interfaces under `cts/libs/helpers` and the\ndefault AOSP helpers under `cts/helpers`. The top-level interface is documented\nin\n`cts/libs/helpers/core/src/com/android/cts/helpers/ICtsDeviceInteractionHelper.java`.\n\nTo connect the CTS test to its helpers, test owners can use the `@Rule`\ndefinition documented in\n`cts/libs/helpers/core/src/com/android/cts/helpers/DeviceInteractionHelperRule.java`.\n\nEach CTS module that uses the framework and its expected helper\nbehavior is documented in an interface defined under\n`cts/libs/helpers/core/src/com/android/cts/helpers`.\n\nRunning CTS tests\n-----------------\n\n### Testing without helpers\n\nOther than one property, the option to test without helpers doesn't exist at\nruntime on the device, but optionally modifies how CTS tests interact with\nthe device. If you need to run CTS without the helper implementations, you\nhave two options:\n\n- Remove the `ro.vendor.cts_interaction_helper_packages` property from the device. This prevents the helpers from being used on that build entirely.\n- Remove the helper APK from the `testcases` directory before running CTS. This prevents the helpers from being used by any runs until the APK is restored to `testcases`.\n\nYou can alter the default settings with Tradefed arguments and the\n`ro.vendor.cts_interaction_helper_packages` property control, which is where\nthe helper APK is loaded from.\n\nSee the following for the expected values or ranges for each of the available\nsettings.\n\n- `ro.vendor.cts_interaction_helper_packages` is a colon-separated string containing package names. It can take any value that is a valid package choice for the OEM's helper implementation.\n- `cts-tradefed` accepts a `device-interaction-helper:property-name` argument that temporarily changes the expected property for one test run, such as `--module-arg 'CtsPrintTestCases:{device-interaction-helper}property-name:debug.cts.hlp'`. The value of the property name can be any property that you set on the device. The value of the property follows the same restrictions as the `ro.vendor.cts_interaction_helper_packages` property described above.\n\n### Testing with customizations\n\nBy default, reference implementations pass CTS on stock Android. Check that\npartner implementations pass CTS with UI customizations. Run whichever CTS\nmodules cover the UI or features you customized.\n\nCertain CTS modules or helpers might not support some customizations yet.\n\n- **A CTS module that interacts with the UI you want to customize might not\n use the helper framework.** CTS modules are expected to convert to the helper framework based on demand and the test owner priorities. File requests for conversion early in the process to ensure that the conversion gets on the schedule, similar to requesting CTS changes to support your planned features.\n- **Functions provided by an existing helper might not fully address the\n customizations you want to make.** Helper functions should abstract away UI dependencies. If a helper function indirectly has a UI dependency, this can be treated similarly to bugs in CTS."]]
