เขียนการทดสอบภาพหน้าจอตัวอย่าง

การทดสอบภาพหน้าจอเป็นวิธีที่มีประสิทธิภาพในการยืนยันว่า UI ของคุณมีลักษณะอย่างไรสำหรับผู้ใช้ เครื่องมือทดสอบภาพหน้าจอของตัวอย่าง Compose ผสานความเรียบง่ายและฟีเจอร์ของตัวอย่างที่ใช้ Compose เข้ากับ การเพิ่มประสิทธิภาพของการทดสอบภาพหน้าจอฝั่งโฮสต์ ตัวอย่าง Compose การทดสอบภาพหน้าจอออกแบบมาให้ใช้งานง่ายเหมือนกับตัวอย่างที่เขียนด้วย Compose ได้

การทดสอบภาพหน้าจอเป็นการทดสอบอัตโนมัติที่จะถ่ายภาพหน้าจอของ UI จากนั้นจะเปรียบเทียบกับรูปภาพอ้างอิงที่ได้รับอนุมัติก่อนหน้านี้ หากรูปภาพไม่ตรงกัน การทดสอบจะล้มเหลวและสร้างรายงาน HTML เพื่อช่วยคุณ เปรียบเทียบและค้นหาความแตกต่าง

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

• ใช้ @PreviewTest เพื่อสร้างการทดสอบภาพหน้าจอสำหรับตัวอย่างที่ใช้ได้ที่มีอยู่หรือตัวอย่างใหม่
• สร้างรูปภาพอ้างอิงจากตัวอย่างที่ประกอบได้เหล่านั้น
• สร้างรายงาน HTML ที่ระบุการเปลี่ยนแปลงตัวอย่างเหล่านั้นหลังจากที่คุณ ทำการเปลี่ยนแปลงโค้ด
• ใช้พารามิเตอร์ @Preview เช่น uiMode หรือ fontScale และการแสดงตัวอย่างหลายรายการ เพื่อช่วยคุณขยายการทดสอบ
• แยกส่วนการทดสอบด้วยscreenshotTestชุดแหล่งข้อมูลใหม่

ข้อกำหนด

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

• ปลั๊กอิน Android Gradle 8.5.0-beta01 ขึ้นไป
• Kotlin 1.9.20 ขึ้นไป เราขอแนะนำให้ใช้ Kotlin 2.0 ขึ้นไปเพื่อให้คุณใช้ปลั๊กอิน Gradle ของตัวคอมไพล์ Compose ได้
• JDK 23 หรือต่ำกว่า เครื่องมือนี้ไม่รองรับ JDK 24 ขึ้นไปเนื่องจากต้องใช้ Java Security Manager ซึ่งถูกนำออกใน JDK เวอร์ชันใหม่กว่า

• เปิดใช้ Compose สำหรับโปรเจ็กต์ เราขอแนะนำให้เปิดใช้ Compose โดยใช้ปลั๊กอิน Gradle ของคอมไพเลอร์ Compose

ตั้งค่า

หากต้องการเปิดใช้เครื่องมือ ให้ทำตามขั้นตอนต่อไปนี้

1. เพิ่มปลั๊กอิน com.android.compose.screenshot เวอร์ชัน 0.0.1-alpha10 ลงในโปรเจ็กต์
1. เพิ่มปลั๊กอินลงในไฟล์แคตตาล็อกเวอร์ชันของคุณ

   [versions]
   agp = "8.11.0-alpha06"
   kotlin = "2.1.20"
   screenshot = "0.0.1-alpha10"
   
   [plugins]
   screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}

2. ในไฟล์ build.gradle.kts ระดับโมดูล ให้เพิ่มปลั๊กอินในบล็อก plugins {} ดังนี้

   plugins {
       alias(libs.plugins.screenshot)
   }

2. เปิดใช้พร็อพเพอร์ตี้เวอร์ชันทดลองในไฟล์ gradle.properties ของโปรเจ็กต์

   android.experimental.enableScreenshotTest=true

3. ในบล็อก android {} ของไฟล์ระดับโมดูล build.gradle.kts ให้เปิดใช้ Flag การทดลองเพื่อใช้ชุดแหล่งข้อมูล screenshotTest

   android {
       experimentalProperties["android.experimental.enableScreenshotTest"] = true
   }
   

4. เพิ่มการอ้างอิง screenshot-validation-api และ ui-tooling
   1. เพิ่มลงในแคตตาล็อกเวอร์ชันของคุณโดยทำดังนี้

      [libraries]
      screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot"}
      androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}

   2. เพิ่มลงในไฟล์ build.gradle.kts ระดับโมดูล

      dependencies {
        screenshotTestImplementation(libs.screenshot.validation.api)
        screenshotTestImplementation(libs.androidx.ui.tooling)
      }

กำหนดตัวอย่างที่เขียนด้วย Compose เพื่อใช้สำหรับการทดสอบภาพหน้าจอ

หากต้องการระบุตัวอย่างที่ใช้ร่วมกันได้ซึ่งคุณต้องการใช้สำหรับการทดสอบภาพหน้าจอ ให้ทำเครื่องหมาย ตัวอย่างด้วยคำอธิบายประกอบ @PreviewTest ตัวอย่างต้องอยู่ในscreenshotTestชุดแหล่งข้อมูลใหม่ เช่น app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt

คุณเพิ่ม Composable และ/หรือตัวอย่างได้อีก รวมถึงตัวอย่างหลายรายการใน ไฟล์นี้หรือไฟล์อื่นๆ ที่สร้างในชุดแหล่งที่มาเดียวกัน

package com.example.yourapp

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

@PreviewTest
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
    MyApplicationTheme {
        Greeting("Android!")
    }
}

สร้างรูปภาพอ้างอิง

หลังจากตั้งค่าชั้นเรียนทดสอบแล้ว คุณจะต้องสร้างรูปภาพอ้างอิงสำหรับตัวอย่างแต่ละรายการ ระบบจะใช้รูปภาพอ้างอิงเหล่านี้เพื่อระบุการเปลี่ยนแปลงในภายหลังหลังจากที่คุณ ทำการเปลี่ยนแปลงโค้ด หากต้องการสร้างรูปภาพอ้างอิงสำหรับการทดสอบภาพหน้าจอของตัวอย่างที่ประกอบได้ ให้เรียกใช้ Gradle Task ต่อไปนี้

• Linux และ macOS: ./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
• Windows: gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

หลังจากงานเสร็จสมบูรณ์ ให้ค้นหารูปภาพอ้างอิงใน app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference)

สร้างรายงานการทดสอบ

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

• Linux และ macOS: ./gradlew validateDebugScreenshotTest (./gradlew :{module}:validate{Variant}ScreenshotTest)
• Windows: gradlew validateDebugScreenshotTest (gradlew :{module}:validate{Variant}ScreenshotTest)

งานการยืนยันจะสร้างรายงาน HTML ที่ {module}/build/reports/screenshotTest/preview/{variant}/index.html

ปัญหาที่ทราบ

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

การอัปเดตการเผยแพร่

บันทึกประจำรุ่นและการเปลี่ยนแปลงสำหรับเวอร์ชันที่ใช้งานอยู่

0.0.1-alpha10

รุ่นนี้มีฟีเจอร์ใหม่ดังนี้

• ตั้งแต่เวอร์ชันนี้เป็นต้นไป คุณต้องทำเครื่องหมายฟังก์ชันเวอร์ชันตัวอย่างทั้งหมดด้วย @PreviewTest ระบบจะไม่ดำเนินการกับตัวอย่างที่ไม่มีคำอธิบายประกอบ

• เปลี่ยนไดเรกทอรีรูปภาพอ้างอิงจาก {module}/src/{variant}/screenshotTest/reference เป็น {module}/src/screenshotTest{Variant}/reference เพื่อให้มั่นใจว่ารูปภาพอ้างอิงที่สร้างขึ้นจะไม่เป็นส่วนหนึ่งของโค้ดที่ใช้งานจริง และเพื่อให้สอดคล้องกับโครงสร้างไดเรกทอรีของการทดสอบประเภทอื่นๆ

• ระบบจะนำงาน {variant}PreviewScreenshotRender ออก การแสดงรูปภาพจะ ย้ายไปอยู่ใน JUnit Test Engine

• update{Variant}ScreenshotTest งานจะเปรียบเทียบรูปภาพที่แสดงผลใหม่กับ รูปภาพอ้างอิงก่อนที่จะอัปเดต โดยจะอัปเดตรูปภาพที่มีความแตกต่างมากกว่าเกณฑ์ที่ระบุเท่านั้น นำแฟล็ก --updateFilter commandline ออกแล้ว

0.0.1-alpha06

รุ่นนี้มีฟีเจอร์ใหม่ดังนี้

เกณฑ์ความแตกต่างของรูปภาพ: การตั้งค่าเกณฑ์ส่วนกลางใหม่นี้จะช่วยให้คุณ ควบคุมการเปรียบเทียบภาพหน้าจอได้ละเอียดยิ่งขึ้น หากต้องการกำหนดค่า ให้อัปเดต build.gradle.kts ของโมดูลดังนี้

android {
    testOptions {
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

ระบบจะใช้เกณฑ์นี้กับการทดสอบภาพหน้าจอทั้งหมดที่กำหนดไว้ในโมดูล

• การแก้ไขข้อบกพร่อง: แก้ไขข้อบกพร่องของโปรแกรมแสดงผล Compose บางอย่างและเพิ่มการรองรับการเขียนที่ว่างเปล่า
• การปรับปรุงประสิทธิภาพ: อัปเดตอัลกอริทึมการเปรียบเทียบรูปภาพให้เร็วขึ้น