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

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

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

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

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

การผสานรวม IDE

แม้ว่าคุณจะใช้เครื่องมือการทดสอบภาพหน้าจอของ Compose Preview ได้โดยการเรียกใช้ฟังก์ชัน Gradle พื้นฐาน (updateScreenshotTest และ validateScreenshotTest) ด้วยตนเอง แต่ Android Studio Otter 3 Feature Drop Canary 4 ได้นำเสนอการผสานรวม IDE อย่างเต็มรูปแบบ ซึ่งช่วยให้คุณสร้างรูปภาพอ้างอิง เรียกใช้การทดสอบ และวิเคราะห์ความล้มเหลวในการตรวจสอบความถูกต้องทั้งหมดภายใน IDE ได้ ฟีเจอร์หลักบางอย่างมีดังนี้

• ไอคอนรางในเอดิเตอร์ ตอนนี้คุณสามารถเรียกใช้การทดสอบหรืออัปเดตรูปภาพอ้างอิงจากซอร์สโค้ดได้โดยตรง ไอคอนเรียกใช้สีเขียวจะปรากฏในรางข้างๆ คอมโพสได้และคลาสที่มีคำอธิบายประกอบด้วย @PreviewTest
  • เรียกใช้การทดสอบภาพหน้าจอ เรียกใช้การทดสอบสำหรับฟังก์ชันเดียวหรือทั้งคลาสโดยเฉพาะ
  • เพิ่มหรืออัปเดตรูปภาพอ้างอิง ทริกเกอร์โฟลว์การอัปเดตสำหรับขอบเขตที่เลือกโดยเฉพาะ

• การจัดการการอ้างอิงแบบอินเทอร์แอกทีฟ ตอนนี้การอัปเดตรูปภาพอ้างอิงมีความปลอดภัยและละเอียดมากขึ้น
  • กล่องโต้ตอบการสร้างรูปภาพอ้างอิงใหม่ กล่องโต้ตอบใหม่ช่วยให้คุณเห็นภาพและเลือกการแสดงตัวอย่างที่จะสร้างหรืออัปเดตได้อย่างแม่นยำ แทนที่จะเรียกใช้ฟังก์ชัน Gradle แบบกลุ่ม
  • รูปแบบการแสดงตัวอย่าง กล่องโต้ตอบจะแสดงรูปแบบการแสดงตัวอย่างทั้งหมด (เช่น ธีมสว่างหรือธีมมืด หรืออุปกรณ์ต่างๆ) แยกกัน ซึ่งช่วยให้คุณเลือกหรือยกเลิกการเลือกรายการที่ต้องการก่อนที่จะสร้างรูปภาพได้

• ผลการทดสอบและเครื่องมือดูความแตกต่างที่ผสานรวม ดูผลลัพธ์ได้โดยไม่ต้องออกจาก IDE
  • แผงเรียกใช้แบบรวม ผลการทดสอบภาพหน้าจอจะปรากฏในหน้าต่างเครื่องมือเรียกใช้ มาตรฐาน ระบบจะจัดกลุ่มการทดสอบตามคลาสและฟังก์ชัน โดยจะระบุสถานะผ่านหรือไม่ผ่านอย่างชัดเจน
  • เครื่องมือเปรียบเทียบแบบภาพ เมื่อการทดสอบล้มเหลว แท็บภาพหน้าจอ จะช่วยให้คุณ เปรียบเทียบรูปภาพ อ้างอิง จริง และ ความแตกต่าง เคียงข้างกันได้
  • แอตทริบิวต์โดยละเอียด แท็บแอตทริบิวต์ จะแสดงข้อมูลเมตาเกี่ยวกับการทดสอบที่ล้มเหลว ซึ่งรวมถึงเปอร์เซ็นต์การจับคู่ ขนาดรูปภาพ และการกำหนดค่าการแสดงตัวอย่างที่เฉพาะเจาะจงที่ใช้ (เช่น uiMode หรือ fontScale)

• การกำหนดขอบเขตการทดสอบที่ยืดหยุ่น ตอนนี้คุณสามารถเรียกใช้การทดสอบภาพหน้าจอที่มีขอบเขตต่างๆ ได้โดยตรงจากมุมมองโปรเจ็กต์ คลิกขวาที่โมดูล ไดเรกทอรี ไฟล์ หรือคลาสเพื่อเรียกใช้การทดสอบภาพหน้าจอสำหรับรายการที่เลือกโดยเฉพาะ

ข้อกำหนด

หากต้องการใช้การทดสอบภาพหน้าจอของ Compose Preview ผ่านการผสานรวม IDE อย่างเต็มรูปแบบ โปรเจ็กต์ของคุณต้องเป็นไปตามข้อกำหนดต่อไปนี้

• Android Studio Panda 1 Canary 4 ขึ้นไป
• ปลั๊กอิน Android Gradle (AGP) เวอร์ชัน 9.0 ขึ้นไป
• ปลั๊กอินการทดสอบภาพหน้าจอของ Compose Preview เวอร์ชัน 0.0.1-alpha14 ขึ้นไป
• Kotlin เวอร์ชัน 2.2.10 ขึ้นไป
• JDK เวอร์ชัน 17 ขึ้นไป
• เปิดใช้ Compose สำหรับโปรเจ็กต์ เราขอแนะนำให้เปิดใช้ Compose โดยใช้ ปลั๊กอิน Compose Compiler Gradle

หากต้องการใช้เฉพาะฟังก์ชัน Gradle พื้นฐานโดยไม่มีการผสานรวม IDE ข้อกำหนดมีดังนี้

• ปลั๊กอิน Android Gradle (AGP) เวอร์ชัน 8.5.0 ขึ้นไป
• ปลั๊กอินการทดสอบภาพหน้าจอของ Compose Preview เวอร์ชัน 0.0.1-alpha14 ขึ้นไป
• Kotlin เวอร์ชัน 1.9.20 ขึ้นไป เราขอแนะนำให้ใช้ Kotlin 2.0 ขึ้นไปเพื่อให้คุณใช้ปลั๊กอิน Compose Compiler Gradle ได้
• JDK เวอร์ชัน 17 ขึ้นไป
• เปิดใช้ Compose สำหรับโปรเจ็กต์ เราขอแนะนำให้เปิดใช้ Compose โดยใช้ ปลั๊กอิน Compose Compiler Gradle

ตั้งค่า

ทั้งเครื่องมือที่ผสานรวมและฟังก์ชัน Gradle พื้นฐานต่างก็ต้องใช้ปลั๊กอินการทดสอบภาพหน้าจอของ Compose Preview โปรดทำตามขั้นตอนต่อไปนี้เพื่อตั้งค่าปลั๊กอิน

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

   android.experimental.enableScreenshotTest=true
   

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

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

3. เพิ่มปลั๊กอิน com.android.compose.screenshot เวอร์ชัน 0.0.1-alpha14 ลงในโปรเจ็กต์

   1. เพิ่มปลั๊กอินลงในไฟล์แคตตาล็อกเวอร์ชัน

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.1.20"
      screenshot = "0.0.1-alpha14"
      
      [plugins]
      screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
      

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

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. เพิ่มทรัพยากร Dependency screenshot-validation-api และ ui-tooling

   1. เพิ่มทรัพยากร Dependency เหล่านี้ลงในแคตตาล็อกเวอร์ชัน

      [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. เพิ่มทรัพยากร Dependency เหล่านี้ลงในไฟล์ build.gradle.kts ระดับโมดูล

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

กำหนดการแสดงตัวอย่างที่สร้างได้ที่จะใช้สำหรับการทดสอบภาพหน้าจอ

หากต้องการกำหนดการแสดงตัวอย่างที่สร้างได้ที่จะใช้สำหรับการทดสอบภาพหน้าจอ ให้ทำเครื่องหมายการแสดงตัวอย่างด้วยคำอธิบายประกอบ @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!")
    }
}

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

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

ใน IDE

คลิกไอคอนรางข้างฟังก์ชัน @PreviewTest แล้วเลือกเพิ่ม/อัปเดตรูปภาพอ้างอิง เลือกการแสดงตัวอย่างในกล่องโต้ตอบ แล้วคลิกเพิ่ม

ด้วยฟังก์ชัน Gradle

เรียกใช้งาน Gradle ต่อไปนี้

• 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)

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

เมื่อมีรูปภาพอ้างอิงแล้ว ให้สร้างรายงานการทดสอบโดยทำตามวิธีการในส่วนนี้สำหรับการผสานรวม IDE หรือสำหรับฟังก์ชัน Gradle

ใน IDE

คลิกไอคอนรางข้างฟังก์ชัน @PreviewTest แล้วเลือกเรียกใช้ 'ScreenshotTests'

หากการทดสอบล้มเหลว ให้คลิกชื่อการทดสอบในแผงเรียกใช้ เลือกแท็บภาพหน้าจอ เพื่อตรวจสอบความแตกต่างของรูปภาพโดยใช้การควบคุมการซูมและการเลื่อนที่ผสานรวม

ด้วยฟังก์ชัน Gradle

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

• 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

การแก้ปัญหา

การทดสอบภาพหน้าจอของ Compose Preview จะเรียกใช้การทดสอบฝั่งโฮสต์ ซึ่งอาจใช้หน่วยความจำมาก คุณสามารถเพิ่มขนาดฮีปสูงสุดสำหรับ JVM ของการทดสอบได้โดยเพิ่มพร็อพเพอร์ตี้ต่อไปนี้ลงในไฟล์ gradle.properties

android.compose.screenshot.maxHeapSize=4g

ปัญหาที่ทราบแล้ว

• Kotlin Multiplatform (KMP): ทั้ง IDE และปลั๊กอินพื้นฐานได้รับการออกแบบมาสำหรับโปรเจ็กต์ Android โดยเฉพาะ จึงไม่รองรับเป้าหมายที่ไม่ใช่ Android ในโปรเจ็กต์ KMP

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

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

ดูรายการการอัปเดตการเผยแพร่ทั้งหมดได้ที่ บันทึกประจำรุ่น