การทดสอบภาพหน้าจอด้วยชุดทดสอบ

ตั้งแต่ปลั๊กอิน Android Gradle (AGP) 9.5.0-alpha03 และเครื่องมือทดสอบภาพหน้าจอของตัวอย่าง Compose 0.0.1-alpha16 เป็นต้นไป ระบบจะผสานรวมการทดสอบภาพหน้าจอเข้ากับเฟรมเวิร์กชุดทดสอบดั้งเดิมของ AGP

แนวทางนี้จะแทนที่ปลั๊กอินภาพหน้าจอแบบสแตนด์อโลน (com.android.compose.screenshot) เราขอแนะนำให้ใช้ชุดทดสอบ AGP ด้วยเหตุผลต่อไปนี้

• วงจรของงาน Gradle ดั้งเดิม: การทดสอบภาพหน้าจอจะผสานรวมโดยตรงกับวงจรการทดสอบ Gradle และ AGP มาตรฐาน ซึ่งจะช่วยปรับปรุงการแยกงานและความน่าเชื่อถือในการดำเนินการทดสอบ
• รองรับชุดทดสอบหลายเวอร์ชันและชุดทดสอบที่กำหนดเอง: คุณสามารถสร้างชุดทดสอบภาพหน้าจอที่แตกต่างกันหลายชุด (เช่น screenshotTest, uiTests หรือ smokeTests) ภายในโมดูลเดียว และกำหนดเป้าหมายไปยังตัวแปรบิลด์ที่เฉพาะเจาะจง (เช่น demoDebug หรือ release) แทนที่จะจำกัดไว้ที่ชุดซอร์สที่กำหนดค่าไว้ล่วงหน้าชุดเดียว
• ประสิทธิภาพการสร้างและการแยกที่ดียิ่งขึ้น: ชุดการทดสอบ AGP ใช้ การแปลงอาร์ติแฟกต์ในตัว (เช่น การแยกเวลาเรียกใช้ Layoutlib) และ การโหลดคลาสแบบแยก โดยรองรับการแคชการกำหนดค่า Gradle และการแยกโปรเจ็กต์อย่างเต็มรูปแบบ

ข้อกำหนด

หากต้องการใช้การทดสอบภาพหน้าจอ Compose กับชุดทดสอบ โปรดตรวจสอบว่าสภาพแวดล้อมเป็นไปตามข้อกำหนดต่อไปนี้

• Android Studio Rabbit 1 Canary 4 ขึ้นไป
• ปลั๊กอิน Android Gradle (AGP) เวอร์ชัน 9.5.0-alpha03 ขึ้นไป
• Compose Screenshot Engine เวอร์ชัน 0.0.1-alpha16 ขึ้นไป
• JDK เวอร์ชัน 17 ขึ้นไป
• เปิดใช้ Compose สำหรับโปรเจ็กต์ เราขอแนะนำให้เปิดใช้ Compose โดยใช้ ปลั๊กอิน Gradle ของตัวคอมไพล์ Compose

การตั้งค่าและการกำหนดค่า

หากต้องการกำหนดค่าการทดสอบภาพหน้าจอ Compose ด้วยชุดการทดสอบ ให้ทำตาม ขั้นตอนต่อไปนี้

1. เปิดใช้ Flag ทดลอง

ในไฟล์ gradle.properties รูทของโปรเจ็กต์ ให้เปิดใช้การทดสอบภาพหน้าจอและ การรองรับชุดโปรแกรมทดสอบโดยทำดังนี้

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. กำหนดค่าชุดโปรแกรมทดสอบในไฟล์ build.gradle.kts

ในไฟล์ build.gradle.kts ของโมดูล ให้กำหนดชุดโปรแกรมทดสอบภาพหน้าจอภายในบล็อก testOptions ดังนี้

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. สร้างชุดซอร์สทดสอบ

สร้างไดเรกทอรีชุดซอร์สเฉพาะที่ตรงกับชื่อชุดโปรแกรมของคุณ

{module}/src/{suiteName}/kotlin/

เช่น สำหรับชุดที่ชื่อ screenshotTest

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. กำหนดการทดสอบตัวอย่างที่เขียนด้วย Compose

ใส่คำอธิบายประกอบให้กับ Composable ด้วย @PreviewTest และ @Preview มาตรฐานหรือ คำอธิบายประกอบแบบหลายตัวอย่าง

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

เรียกใช้การทดสอบภาพหน้าจอ

ชุดทดสอบ AGP จะสร้างงาน Gradle เฉพาะตามชื่อชุดทดสอบ เป้าหมาย และตัวแปร

1. สร้างหรืออัปเดตรูปภาพอ้างอิง

แสดงตัวอย่างคอมโพเนนต์ที่เขียนด้วย Compose ได้และจัดเก็บรูปภาพอ้างอิงพื้นฐานที่ถูกต้อง

• Linux และ macOS ./gradlew update{SuiteName}{Target}{Variant}TestSuite (เช่น ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

ระบบจะสร้างและบันทึกรูปภาพอ้างอิงไว้ที่

{module}/src/{suiteName}{Target}{Variant}/reference/

2. ยืนยันและทำการทดสอบ

แสดงภาพหน้าจอใหม่และเปรียบเทียบกับรูปภาพอ้างอิง

• Linux และ macOS ./gradlew test{SuiteName}{Target}{Variant}TestSuite (เช่น ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

ตรวจสอบรายงานการทดสอบ

หากตรวจพบความแตกต่างหรือการทดสอบไม่สำเร็จ AGP จะสร้างรายงานการทดสอบ HTML

• รายงานตำแหน่ง {module}/build/reports/tests/{taskName}/index.html (เช่น app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

รายงานที่อัปเดตประกอบด้วยข้อมูลต่อไปนี้

• การ์ดข้อมูลเมตาของส่วนหัว: แสดงชื่อการทดสอบ วิธีแสดงตัวอย่าง ตัวแปร ชุดการทดสอบ และป้ายสถานะ
• การจัดหมวดหมู่ข้อผิดพลาด: แจ้งReference Image Missing, Image Size Mismatch หรือ Pixel Mismatch อย่างชัดเจนพร้อมสแต็กเทรซที่คัดลอกได้
• การเปรียบเทียบภาพแบบไดนามิก: ไฮไลต์การแก้ไขเล็กๆ น้อยๆ ด้วยความเข้มต่ำ และการเปลี่ยนแปลงที่สำคัญด้วยการเน้นคอนทราสต์สูงเพื่อป้องกันการกลืนองค์ประกอบ ที่ซ้อนกัน

ย้ายข้อมูลจากปลั๊กอินแบบสแตนด์อโลนเดิม

หากต้องการย้ายข้อมูลจากปลั๊กอินภาพหน้าจอแบบสแตนด์อโลนเดิมไปยังชุดทดสอบ AGP ให้อัปเดตการกำหนดค่า Gradle และคำสั่งงาน

การเปรียบเทียบ DSL ของการกำหนดค่าบิวด์

ปลั๊กอินแบบสแตนด์อโลนเดิม (เลิกใช้งานแล้ว)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

ชุดการทดสอบ AGP (แนะนำ)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

การแมปงานและเส้นทาง