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

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

การทดสอบภาพหน้าจอเป็นการทดสอบอัตโนมัติที่จะถ่ายภาพหน้าจอของ 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 Preview Screenshot Testing เวอร์ชัน 0.0.1-alpha14 ขึ้นไป
• Kotlin เวอร์ชัน 2.2.10 ขึ้นไป
• JDK เวอร์ชัน 17 ขึ้นไป
• เปิดใช้ Compose สำหรับโปรเจ็กต์ เราขอแนะนำให้เปิดใช้ Compose โดยใช้ปลั๊กอิน Gradle ของคอมไพเลอร์ Compose

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

• ปลั๊กอิน Android Gradle (AGP) เวอร์ชัน 8.5.0 ขึ้นไป
• ปลั๊กอิน Compose Preview Screenshot Testing เวอร์ชัน 0.0.1-alpha14 ขึ้นไป
• Kotlin เวอร์ชัน 1.9.20 ขึ้นไป เราขอแนะนำให้ใช้ Kotlin 2.0 ขึ้นไปเพื่อให้ คุณใช้ปลั๊กอิน Gradle ของตัวคอมไพล์ Compose ได้
• 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-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. เพิ่มการอ้างอิง 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

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

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

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

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

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

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