กำหนดค่าสภาพแวดล้อมการทดสอบด้วย Testing API เวอร์ชัน 2

API การทดสอบ Compose เวอร์ชัน v2 (createComposeRule, createAndroidComposeRule, runComposeUiTest, runAndroidComposeUiTest ฯลฯ) เผยแพร่แล้วเพื่อปรับปรุงการควบคุมการดำเนินการ Coroutine การอัปเดตนี้ไม่ได้ทำซ้ำแพลตฟอร์ม API ทั้งหมด แต่จะอัปเดตเฉพาะ API ที่สร้างสภาพแวดล้อมการทดสอบเท่านั้น

API เวอร์ชัน 1 เลิกใช้งานแล้ว และเราขอแนะนำอย่างยิ่งให้ย้ายข้อมูลไปยัง API ใหม่ การย้ายข้อมูลจะช่วยยืนยันว่าการทดสอบของคุณสอดคล้องกับลักษณะการทำงานของโครูทีนมาตรฐานและหลีกเลี่ยงปัญหาความเข้ากันได้ในอนาคต ดูรายการ API เวอร์ชัน 1 ที่เลิกใช้งานแล้วได้ที่การแมป API

แม้ว่า API เวอร์ชัน 1 จะใช้ UnconfinedTestDispatcher แต่ API เวอร์ชัน 2 จะใช้ StandardTestDispatcher โดยค่าเริ่มต้นสำหรับ Composition ที่ทำงานอยู่ การเปลี่ยนแปลงนี้จะปรับลักษณะการทดสอบ Compose ให้สอดคล้องกับ API runTest มาตรฐาน และให้การควบคุมลำดับการดำเนินการ Coroutine อย่างชัดเจน

กำหนดค่าสภาพแวดล้อมการทดสอบ

API เวอร์ชัน 2 ของการทดสอบ Compose ใช้ ComposeUiTestConfig เพื่อปรับแต่งสภาพแวดล้อมการทดสอบ API ที่สร้างฟังก์ชันการตั้งค่าสำหรับการทดสอบ เช่น createComposeRule, runComposeUiTest และ API อื่นๆ ที่เกี่ยวข้องจะยอมรับ ComposeUiTestConfig ออบเจ็กต์การกำหนดค่านี้จะรวม API ที่เกี่ยวข้องกับสภาพแวดล้อม เช่น effectContext, runTestContext และ testTimeout ไว้ในออบเจ็กต์เดียว

โมเดลการกำหนดค่ายังจัดการ inputMode ด้วย Compose test v2 API จะบังคับใช้ InputMode.Touch โดยค่าเริ่มต้นเมื่อเริ่มการทดสอบแต่ละครั้ง เพื่อให้มั่นใจว่าผลลัพธ์จะเหมือนเดิมและป้องกันไม่ให้สถานะโหมดอินพุตรั่วไหลระหว่างการทดสอบ

ComposeUiTestConfig เป็นส่วนหนึ่งของ Compose Testing v2 API ซึ่งใช้ StandardTestDispatcher โดยค่าเริ่มต้น หากการทดสอบใช้ API เวอร์ชัน 1 โปรดดูย้ายข้อมูลไปยัง API การทดสอบเวอร์ชัน 2 ก่อนใช้ ComposeUiTestConfig

ย้ายข้อมูลไปยัง ComposeUiTestConfig

ภายในโอเวอร์โหลดสำหรับการสร้างฟังก์ชันการตั้งค่าในการทดสอบ โอเวอร์โหลดหลายรายการที่ยอมรับพารามิเตอร์การกำหนดค่าแต่ละรายการ เช่น effectContext, runTestContext หรือ testTimeout จะเลิกใช้งาน อัปเดตการทดสอบเพื่อใช้ ComposeUiTestConfig แทน ดังที่แสดงในตัวอย่างต่อไปนี้

โหมดป้อนข้อมูลเริ่มต้น

การทดสอบอาจล้มเหลวระหว่างการย้ายข้อมูลหากใช้โหมดการป้อนข้อมูลที่ไม่ใช่การสัมผัสซึ่งกำหนดค่าผ่าน API การวัดคุมก่อนที่การทดสอบจะเริ่มขึ้น ภายในฟังก์ชันการตั้งค่าสำหรับการทดสอบ ระบบจะบังคับใช้ InputMode.Touch โดยค่าเริ่มต้นเมื่อเริ่มการทดสอบแต่ละครั้งเพื่อความแน่นอนมากขึ้นและเพื่อป้องกันการรั่วไหลของสถานะ โดยจะลบล้างสถานะอุปกรณ์แอมเบียนท์และการตั้งค่าก่อนการทดสอบ

หากต้องการแก้ไขปัญหานี้ ให้ระบุโหมดการป้อนข้อมูลที่จำเป็นใน ComposeUiTestConfig ดังนี้

class FocusTest {
    @get:Rule
    val rule = createComposeRule(
        config = ComposeUiTestConfig(inputMode = InputMode.Keyboard)
    )

    @Test
    fun testFocus() {}
}

หากต้องการกำหนดค่าโหมดอินพุตสำหรับกรอบการทดสอบแต่ละรายการแทนคลาสการทดสอบทั้งหมด ให้ส่ง ComposeUiTestConfig ไปยัง runComposeUiTest ดังนี้

class FocusTest {
    @Test
    fun testTouchMode() = runComposeUiTest {
        // Runs with the default InputMode.Touch
    }

    @Test
    fun testKeyboardMode() = runComposeUiTest(
        ComposeUiTestConfig(inputMode = InputMode.Keyboard)
    ) {
        // Runs with InputMode.Keyboard
    }
}

ดูปัญหาอื่นๆ เกี่ยวกับการย้ายข้อมูลและวิธีแก้ไขได้ที่หัวข้อสาเหตุที่พบบ่อยของการไม่ผ่านการตรวจสอบและวิธีแก้ไข

ย้ายข้อมูลไปยัง API การทดสอบ v2

เมื่ออัปเกรดเป็น API เวอร์ชัน 2 โดยทั่วไปคุณจะใช้ค้นหา + แทนที่เพื่ออัปเดตการนําเข้าแพ็กเกจและใช้การเปลี่ยนแปลง Dispatcher ใหม่ได้

หรือขอความช่วยเหลือจาก Gemini ให้ทำการย้ายข้อมูลไปยัง Compose Testing API เวอร์ชัน 2 โดยใช้พรอมต์ต่อไปนี้

ย้ายข้อมูลจาก API การทดสอบ v1 ไปยัง API การทดสอบ v2

พรอมต์นี้จะใช้คู่มือนี้เพื่อย้ายข้อมูลไปยัง API การทดสอบ v2

Migrate to Compose testing v2 APIs using the official
migration guide.

การใช้พรอมต์ AI

พรอมต์ AI มีไว้เพื่อใช้ภายใน Gemini ใน Android Studio

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Gemini ใน Studio ได้ที่ https://developer.android.com/studio/gemini/overview

ใช้ตารางต่อไปนี้เพื่อแมป API เวอร์ชัน 1 ที่เลิกใช้งานแล้วกับ API เวอร์ชัน 2 ที่ใช้แทน

เลิกใช้งานแล้ว (v1)

การเปลี่ยนทดแทน (v2)

androidx.compose.ui.test.junit4.createComposeRule

androidx.compose.ui.test.junit4.v2.createComposeRule

androidx.compose.ui.test.junit4.createAndroidComposeRule

androidx.compose.ui.test.junit4.v2.createAndroidComposeRule

androidx.compose.ui.test.junit4.createEmptyComposeRule

androidx.compose.ui.test.junit4.v2.createEmptyComposeRule

androidx.compose.ui.test.junit4.AndroidComposeTestRule

androidx.compose.ui.test.junit4.v2.AndroidComposeTestRule

androidx.compose.ui.test.runComposeUiTest

androidx.compose.ui.test.v2.runComposeUiTest

androidx.compose.ui.test.runAndroidComposeUiTest

androidx.compose.ui.test.v2.runAndroidComposeUiTest

androidx.compose.ui.test.runEmptyComposeUiTest

androidx.compose.ui.test.v2.runEmptyComposeUiTest

androidx.compose.ui.test.AndroidComposeUiTestEnvironment

androidx.compose.ui.test.v2.AndroidComposeUiTestEnvironment

ความเข้ากันได้แบบย้อนหลังและข้อยกเว้น

ตอนนี้เราเลิกใช้งาน API v1 ที่มีอยู่แล้ว แต่ยังคงใช้ UnconfinedTestDispatcher เพื่อคงลักษณะการทำงานที่มีอยู่และป้องกันการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

ข้อยกเว้นเพียงอย่างเดียวที่ลักษณะการทำงานเริ่มต้นมีการเปลี่ยนแปลงมีดังนี้

ตัวกระจายการทดสอบเริ่มต้นที่ใช้สำหรับการเรียกใช้ Composition ในคลาส AndroidComposeUiTestEnvironment ได้เปลี่ยนจาก UnconfinedTestDispatcher เป็น StandardTestDispatcher ซึ่งจะส่งผลต่อกรณีที่คุณสร้างอินสแตนซ์โดยใช้คอนสตรัคเตอร์ หรือคลาสย่อย AndroidComposeUiTestEnvironment และเรียกใช้คอนสตรัคเตอร์นั้น

การเปลี่ยนแปลงที่สำคัญ: ผลกระทบต่อการดำเนินการ Coroutine

ความแตกต่างหลักระหว่าง API เวอร์ชัน 1 และเวอร์ชัน 2 คือวิธีจัดส่ง Coroutine ดังนี้

  • v1 API (UnconfinedTestDispatcher): เมื่อเปิดใช้งานโครูทีน ระบบจะดำเนินการทันทีในเทรดปัจจุบัน ซึ่งมักจะเสร็จสิ้นก่อนที่บรรทัดถัดไปของโค้ดทดสอบจะทำงาน การดำเนินการทันทีนี้อาจบดบังปัญหาด้านเวลาหรือภาวะแข่งขันที่เกิดขึ้นจริงโดยไม่ตั้งใจ ซึ่งจะเกิดขึ้นในแอปพลิเคชันที่ใช้งานจริง ซึ่งต่างจากลักษณะการทำงานในเวอร์ชันที่ใช้งานจริง
  • v2 APIs (StandardTestDispatcher): เมื่อเปิดใช้งานโครูทีน ระบบจะจัดคิวและไม่ดำเนินการจนกว่าการทดสอบจะเลื่อนนาฬิกาเสมือนอย่างชัดเจน API ทดสอบ Compose มาตรฐาน (เช่น waitForIdle()) จัดการการซิงค์นี้อยู่แล้ว ดังนั้นการทดสอบส่วนใหญ่ที่ใช้ API มาตรฐานเหล่านี้จึงควรทำงานต่อไปได้โดยไม่ต้องทำการเปลี่ยนแปลงใดๆ

สาเหตุที่พบบ่อยของการไม่ผ่านการตรวจสอบและวิธีแก้ไข

หากการทดสอบไม่สำเร็จหลังจากอัปเกรดเป็น v2 แสดงว่าการทดสอบอาจมีรูปแบบต่อไปนี้

  • ความล้มเหลว: คุณเปิดใช้งานงาน (เช่น ViewModel โหลดข้อมูล) แต่การยืนยันล้มเหลวทันทีเนื่องจากข้อมูลยังอยู่ในสถานะ "กำลังโหลด"
  • สาเหตุ: เมื่อใช้ API เวอร์ชัน 2 ระบบจะจัดคิวโครูทีนแทนที่จะดำเนินการทันที งานอยู่ในคิวแต่ไม่ได้ทำงานจริงก่อนที่จะมีการตรวจสอบผลลัพธ์
  • วิธีแก้ไข: เลื่อนเวลาอย่างชัดเจน คุณต้องบอกผู้มอบหมายงาน v2 อย่างชัดเจนว่าควรทำงานเมื่อใด

แนวทางก่อนหน้า

ใน v1 งานจะเริ่มและเสร็จสิ้นทันที ใน v2 โค้ดต่อไปนี้จะทำงานไม่สำเร็จเนื่องจาก loadData() ยังไม่ได้ทำงานจริง

// In v1, this launched and finished immediately.
viewModel.loadData()

// In v2, this fails because loadData() hasn't actually run yet!
assertEquals(Success, viewModel.state.value)

ใช้ waitForIdle หรือ runOnIdle เพื่อดำเนินการกับงานที่อยู่ในคิวก่อนที่จะยืนยัน

ตัวเลือกที่ 1: การใช้ waitForIdle จะเลื่อนเวลาไปจนกว่า UI จะไม่มีการใช้งาน ซึ่งเป็นการยืนยันว่าโครูทีนทำงานแล้ว

viewModel.loadData()

// Explicitly run all queued tasks.
composeTestRule.waitForIdle()

assertEquals(Success, viewModel.state.value)

ตัวเลือกที่ 2: การใช้ runOnIdle จะเรียกใช้โค้ดบล็อกในเธรด UI หลังจากที่ UI ไม่มีการใช้งาน

viewModel.loadData()

// Run the assertion after the UI is idle.
composeTestRule.runOnIdle {
    assertEquals(Success, viewModel.state.value)
}

การซิงค์ข้อมูลด้วยตนเอง

ในสถานการณ์ที่เกี่ยวข้องกับการซิงค์ข้อมูลด้วยตนเอง เช่น เมื่อปิดใช้การเลื่อนหัวข้ออัตโนมัติ การเปิดใช้โครูทีนจะไม่ส่งผลให้มีการดำเนินการทันทีเนื่องจากนาฬิกาทดสอบหยุดชั่วคราว หากต้องการเรียกใช้โครูทีนในคิวโดยไม่เลื่อนนาฬิกาเสมือน ให้ใช้ API runCurrent() ซึ่งจะเรียกใช้งานที่กำหนดเวลาไว้สำหรับเวลาเสมือนปัจจุบัน

composeTestRule.mainClock.scheduler.runCurrent()

runCurrent() จะทำงานที่รอดำเนินการขณะที่รักษาเวลาเสมือนปัจจุบันไว้ ซึ่งต่างจาก waitForIdle() ที่จะเลื่อนนาฬิกาทดสอบไปจนกว่า UI จะเสถียร ลักษณะการทำงานนี้ช่วยให้สามารถยืนยันสถานะระดับกลางได้ ซึ่งจะข้ามไปหากนาฬิกาเลื่อนไปยังสถานะไม่มีการใช้งาน

ระบบจะแสดงตัวจัดกำหนดการทดสอบที่อยู่เบื้องหลังซึ่งใช้ในสภาพแวดล้อมการทดสอบ คุณสามารถใช้ตัวจัดกำหนดการนี้ร่วมกับ Kotlin runTest API เพื่อซิงค์นาฬิกาทดสอบได้

ย้ายข้อมูลไปยัง runComposeUiTest

หากคุณใช้ Compose Test API ร่วมกับ Kotlin runTest API เราขอแนะนำอย่างยิ่งให้เปลี่ยนไปใช้ runComposeUiTest

แนวทางก่อนหน้า

การใช้ createComposeRule ร่วมกับ runTest จะสร้างนาฬิกาแยกกัน 2 เรือน โดยเรือนหนึ่งสำหรับ Compose และอีกเรือนหนึ่งสำหรับขอบเขตโครูทีนทดสอบ การกำหนดค่านี้อาจบังคับให้คุณซิงค์เครื่องมือจัดกำหนดการทดสอบด้วยตนเอง

@get:Rule
val composeTestRule = createComposeRule()

@Test
fun testWithCoroutines() {
    composeTestRule.setContent {
        var status by remember { mutableStateOf("Loading...") }
        LaunchedEffect(Unit) {
            delay(1000)
            status = "Done!"
        }
        Text(text = status)
    }

    // NOT RECOMMENDED
    // Fails: runTest creates a new, separate scheduler.
    // Advancing time here does NOT advance the compose clock.
    // To fix this without migrating, you would need to share the scheduler
    // by passing 'composeTestRule.mainClock.scheduler' to runTest.
    runTest {
        composeTestRule.onNodeWithText("Loading...").assertIsDisplayed()
        advanceTimeBy(1000)
        composeTestRule.onNodeWithText("Done!").assertIsDisplayed()
    }
}

runComposeUiTest API จะเรียกใช้บล็อกการทดสอบภายในขอบเขต runTest ของตัวเองโดยอัตโนมัติ นาฬิกาทดสอบจะซิงค์กับสภาพแวดล้อม Compose คุณจึงไม่ต้องจัดการตัวจัดตารางเวลาด้วยตนเองอีกต่อไป

    @Test
    fun testWithCoroutines() = runComposeUiTest {
        setContent {
            var status by remember { mutableStateOf("Loading...") }
            LaunchedEffect(Unit) {
                delay(1000)
                status = "Done!"
            }
            Text(text = status)
        }

        onNodeWithText("Loading...").assertIsDisplayed()
        mainClock.advanceTimeBy(1000 + 16 /* Frame buffer */)
        onNodeWithText("Done!").assertIsDisplayed()
    }
}