テスト キットの注釈

テスト キットには、特定の形状またはデバイスの種類のためのテストを実行するために使用できるユーティリティ注釈が用意されています。 複数の形状を切り替える複雑なアプリ フローをテストする必要がある場合は、折りたたみ機能をシミュレートするか、代わりにスワイプ ジェスチャを使用する必要があります。

1 つの形状のみを使用するより単純なテストでは、注釈を使用して次のことができます。

• シングルスクリーン モードまたはデュアルスクリーン モードでテストを実行する
• 特定のターゲット デバイスでテストを実行する
• 特定のデバイスの向きでテストを実行する
• シミュレートされた折りたたみ機能を使用してテストを実行する

重要

これらの注釈は、FoldableTestRule と FoldableJUnit4ClassRunner でのみ機能します。 下の「テスト キット コンポーネント」セクションで、これらを注釈と共に使用する方法に関する情報を確認できます。

セットアップ

1. androidTest ディレクトリに新しいテスト クラス ファイルを作成します。 これは、後でテスト規則とテスト用にコード スニペットに追加する場所です。

2. 最上位の build.gradle ファイルに mavenCentral() リポジトリがあることを確認します。

   allprojects {
       repositories {
           google()
           mavenCentral()
       }
   }
   

3. 次の依存関係をモジュールレベル build.gradle ファイルに追加します (現在のバージョンは、ここに示されているものとは異なる場合があります)。

   ビュー

   androidTestImplementation "com.microsoft.device.dualscreen.testing:testing-kotlin:1.0.0-alpha4"
   androidTestImplementation "androidx.test.uiautomator:uiautomator:2.2.0"
   androidTestImplementation "androidx.test.espresso:espresso-core:3.4.0"
   androidTestImplementation "androidx.test:runner:1.4.0"
   androidTestImplementation "androidx.test:rules:1.4.0"
   

   Compose

   androidTestImplementation "com.microsoft.device.dualscreen.testing:testing-compose:1.0.0-alpha04"
   androidTestImplementation "androidx.test.uiautomator:uiautomator:2.2.0"
   androidTestImplementation "androidx.compose.ui:ui-test-junit4:1.1.1"
   

4. モジュールレベル build.gradle ファイルで、compileSdkVersion および targetSdkVersion が API 31 以降に設定されていることを確認します。

   android { 
       compileSdkVersion 31
   
       defaultConfig { 
           targetSdkVersion 31 
       } 
       ... 
   }
   

5. UI チェックを実行し、折りたたみ機能をシミュレートできる TestRule を作成します。 これを行うには、FoldableTestRule ルールと、ActivityScenarioRule または AndroidComposeTestRule の 2 つのルールを連結します。

   foldableRuleChain メソッドを使用してルール チェーンを作成することも、次の例に示すように独自のルール チェーンを作成することもできます。

   ビュー

   private val activityScenarioRule = activityScenarioRule<MainActivity>()
   private val foldableTestRule = FoldableTestRule()
   
   @get:Rule
   val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
   

   or

   private val uiDevice: UiDevice = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
   private val activityScenarioRule = activityScenarioRule<MainActivity>()
   private val foldableTestRule = FoldableTestRule()
   
   @get:Rule
   val testRule: TestRule = if (uiDevice.isSurfaceDuo()) {
       RuleChain.outerRule(activityScenarioRule).around(foldableTestRule)
   } else {
       RuleChain.outerRule(foldableTestRule).around(activityScenarioRule)
   }
   

   Compose

   private val composeTestRule = createAndroidComposeRule<MainActivity>()
   private val foldableTestRule = FoldableTestRule()
   
   @get:Rule
   val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)
   

   or

   protected val uiDevice: UiDevice = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
   private val composeTestRule = createAndroidComposeRule<MainActivity>()
   private val foldableTestRule = FoldableTestRule()
   
   @get:Rule
   val testRule: TestRule = if (uiDevice.isSurfaceDuo()) {
       RuleChain.outerRule(composeTestRule).around(foldableTestRule)
   } else {
       RuleChain.outerRule(foldableTestRule).around(composeTestRule)
   }
   

   独自のルール チェーンを作成する場合:

   • SurfaceDuo とSurfaceDuo2 の場合、ActivityScenarioRule は外側のルールにする必要があります。これは、アプリをスパン/スパン解除操作の前に開始する必要があるためです。
   • 他の折りたたみ型デバイスの場合は、アプリの起動前に FoldingFeature をモック化する必要があるため、FoldableTestRule を外側のルールにする必要があります。

6. Espresso を使ってビューをテストする場合、デバイスでアニメーションを無効にしてください。

テスト キットのコンポーネント

重要

次の注釈の使用を開始する前に、FoldableTestRule と FoldableJUnit4ClassRunner のセクションを参照してください。

SingleScreenTest/DualScreenTest

シングルスクリーンまたはデュアルスクリーン モードでテストを実行する場合は、テスト メソッドまたはテスト クラスにこの注釈を追加します。 さらに、orientation パラメーターを使用して、指定したデバイスの向きでテストを実行できます。 orientation パラメーターは次の値を取ることができます。UiAutomation.ROTATION_FREEZE_0、UiAutomation.ROTATION_FREEZE_90、UiAutomation.ROTATION_FREEZE_180、UiAutomation.ROTATION_FREEZE_270

ビュー

@RunWith(FoldableJUnit4ClassRunner::class)
@SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()
    
    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

Compose

@RunWith(FoldableJUnit4ClassRunner::class)
@SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @SingleScreenTest(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

MockFoldingFeature

折りたたみ機能を目的のデータでモックする場合は、この注釈をテスト メソッドまたはテスト クラスに使用します。

• windowBounds パラメーターは、FoldingFeature を含む表示領域を表す座標の配列です (例: [左、上、右、下])。 windowBounds の幅と高さは 0 より大きい値でなければなりません。 既定では、独自の windowBounds 値を定義しない場合、表示領域全体が使用されます。具体的には、[0, 0, uiDevice.displayWidth, uiDevice.displayHeight] となります。

• center パラメーターは、方向に対して補完的な折りたたみの中心です。 HORIZONTAL 折りたたみの場合、これは y 軸で、VERTICAL 折りたたみの場合は x 軸です。 既定値は -1 です。 このパラメーターが指定されていない場合は、指定された windowBounds に応じて、windowBounds.centerY() または windowBounds.centerX() として orientation パラメーターに基づいて計算されます。

• size パラメーターは、折りたたみの小さい方の次元です。 大きい方の次元が、常にウィンドウ全体をカバーします。 既定値は 0 です。

• state パラメーターは、折りたたみの状態を表します。 使用可能な値は FoldingFeatureState.HALF_OPENED と FoldingFeatureState.FLAT です。 既定値は FoldingFeatureState.HALF_OPENED です。 視覚的なサンプルとリファレンスについては、公式ドキュメントの「形状」セクションを参照してください。

• orientation パラメーターは折りたたみの方向です。 使用可能な値は FoldingFeatureOrientation.HORIZONTAL と FoldingFeatureOrientation.VERTICAL です。 既定値は FoldingFeatureOrientation.HORIZONTAL です。

ビュー

@RunWith(FoldableJUnit4ClassRunner::class)
@MockFoldingFeature(
    size = 2, 
    state = FoldingFeatureState.FLAT, 
    orientation = FoldingFeatureOrientation.HORIZONTAL
)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @MockFoldingFeature(
        size = 2, 
        state = FoldingFeatureState.FLAT,
        orientation = FoldingFeatureOrientation.HORIZONTAL
    )
    fun sampleTestMethod() {
    }
}

Compose

@RunWith(FoldableJUnit4ClassRunner::class)
@MockFoldingFeature(
    windowBounds = [0, 0, 1768, 2208],
    center = 0,
    size = 2,
    state = FoldingFeatureState.HALF_OPENED,
    orientation = FoldingFeatureOrientation.HORIZONTAL
)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @MockFoldingFeature(
        windowBounds = [0, 0, 1768, 2208],
        center = 0,
        size = 2,
        state = FoldingFeatureState.HALF_OPENED,
        orientation = FoldingFeatureOrientation.HORIZONTAL
    )
    fun sampleTestMethod() {
    }
}

TargetDevices

指定したデバイスでのみテストを実行する場合、または一部のデバイスを無視する場合は、この注釈をテスト メソッドまたはテスト クラスに使用します。

• devices パラメーターは目的のデバイスの配列であり、ignoreDevices パラメーターは無視するデバイスの配列です。

  使用例: @TargetDevices(devices = [DeviceModel.SurfaceDuo, DeviceModel.SurfaceDuo2]), @TargetDevices(ignoreDevices = [DeviceModel.SurfaceDuo])

  両方のパラメーターを同時に使用することはできません。

デバイス モデルに使用できる値:

• DeviceModel.SurfaceDuo - SurfaceDuo1 デバイスまたはエミュレーターの表現

• DeviceModel.SurfaceDuo2 - SurfaceDuo2 デバイスおよびエミュレーターの表現

• DeviceModel.HorizontalFoldIn - 6.7" horizontal Fold-In デバイスおよびエミュレーターの表現

• DeviceModel.FoldInOuterDisplay - 外部ディスプレイ デバイスを備えた 7.6" Fold-In とエミュレーターの表現

• DeviceModel.FoldOut - 8" FoldOut デバイスおよびエミュレーターの表現

• DeviceModel.Other - その他の折りたたみ型デバイスとエミュレーターの表現

ビュー

@RunWith(FoldableJUnit4ClassRunner::class)
@TargetDevices(devices = [DeviceModel.SurfaceDuo])
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @TargetDevices(devices = [DeviceModel.SurfaceDuo])
    fun sampleTestMethod() {
    }
}

Compose

@RunWith(FoldableJUnit4ClassRunner::class)
@TargetDevices(devices = [DeviceModel.SurfaceDuo])
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @TargetDevices(devices = [DeviceModel.SurfaceDuo])
    fun sampleTestMethod() {
    }
}

DeviceOrientation

指定したデバイスの向きでテストを実行する場合は、この注釈をテスト メソッドまたはテスト クラスに使用します。

• orientation パラメーターはデバイスの向きを表し、次の値を持つことができます。UiAutomation.ROTATION_FREEZE_0、UiAutomation.ROTATION_FREEZE_90､UiAutomation.ROTATION_FREEZE_180、UiAutomation.ROTATION_FREEZE_270

ビュー

@RunWith(FoldableJUnit4ClassRunner::class)
@DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val activityScenarioRule = activityScenarioRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(activityScenarioRule, foldableTestRule)
    
    @Test
    @DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

Compose

@RunWith(FoldableJUnit4ClassRunner::class)
@DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    fun sampleTestMethod() {
    }
}

or

@RunWith(FoldableJUnit4ClassRunner::class)
class TestSample {
    private val composeTestRule = createAndroidComposeRule<MainActivity>()
    private val foldableTestRule = FoldableTestRule()

    @get:Rule
    val testRule: TestRule = foldableRuleChain(composeTestRule, foldableTestRule)

    @Test
    @DeviceOrientation(orientation = UiAutomation.ROTATION_FREEZE_180)
    fun sampleTestMethod() {
    }
}

FoldableTestRule

FoldableTestRule は、@SingleScreenTest、@DualScreenTest、@MockFoldingFeature、@DeviceOrientation の注釈と共に使用する必要があるカスタムの TestRule です。 このテスト ルールをこれらと一緒に使用していない場合、注釈は機能しません。 この TestRule は、リフレクションを使用してこれらの注釈とパラメーターを取得し、目的の形状とデバイスの向きでテストを実行します。

FoldableJUnit4ClassRunner

FoldableJUnit4ClassRunner は、@SingleScreenTest、@DualScreenTest、@MockFoldingFeature、@DeviceOrientation、@TargetDevices の注釈と共に使用する必要があるカスタムの AndroidJUnit4ClassRunner です。 このランナーは、注釈のパラメーターを検証します。 現在のデバイスがターゲット デバイスの一覧にない場合、または無視するデバイスの一覧にある場合、テストは無視されます。 この Runner が使用されない場合、注釈は検証されず、@TargetDevices 注釈には効果はありません。

注釈の制約

• @SingleScreenTest、@DualScreenTest、@MockFoldingFeature を同時に使うことはできません。 たとえば、同じメソッドまたは同じテスト クラスに @SingleScreenTest と @DualScreenTest 両方の注釈を付けることはできません。

• @TargetDevices.devices と @TargetDevices.ignoreDevices を同時に使うことはできません。 たとえば、同じメソッドやテスト クラスに @TargetDevices(devices = [DeviceModel.SurfaceDuo, DeviceModel.SurfaceDuo2], ignoreDevices = [DeviceModel.Other]) という注釈を付けることはできません。

  正しい使用法: @TargetDevices(devices = [DeviceModel.SurfaceDuo]) または @TargetDevices(ignoreDevices = [DeviceModel.SurfaceDuo])

• @MockFoldingFeature.windowBounds は、表示ウィンドウの左、上、右、下の座標を表す 4 つの要素の配列である必要があります。 たとえば、次のように使用することはできません。@MockFoldingFeature(windowBounds = [0, 0, 0]) や @MockFoldingFeature(windowBounds = [0, 0, 0, 0, 0])。