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

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

android skills add testing-setup

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

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

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

การผสานรวม IDE

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

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

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

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

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

ข้อกำหนด

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

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

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

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

ตั้งค่า

ทั้งเครื่องมือแบบผสานรวมและงาน 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-alpha16 ลงในโปรเจ็กต์

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

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

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

      plugins {
          alias(libs.plugins.screenshot)
      }
      

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!")
    }
}

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

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

android studio render-compose-preview

ใน 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

การแก้ปัญหา

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

android.compose.screenshot.maxHeapSize=4g

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

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

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

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

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