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

ข้อควรระวัง: เราจะไม่ดูแลรักษาปลั๊กอิน com.android.compose.screenshot แบบสแตนด์อโลนที่อธิบายไว้ในหน้านี้อีกต่อไป เราขอแนะนำให้ตั้งค่าการทดสอบภาพหน้าจอด้วยชุดโปรแกรมทดสอบ AGP โดยใช้ปลั๊กอิน Android Gradle (AGP) 9.5 ขึ้นไป หากต้องการเปลี่ยน ให้ดูหัวข้อย้ายข้อมูลโปรเจ็กต์ที่มีอยู่

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

ทักษะ Android

ดูใน GitHub

สร้างการทดสอบภาพหน้าจอ

ใช้testing-setup ทักษะ Android เพื่อพัฒนากลยุทธ์การทดสอบและสร้างการทดสอบภาพหน้าจอ

หากต้องการติดตั้งทักษะจาก Android CLI ให้เรียกใช้คำสั่งต่อไปนี้

android skills add testing-setup

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

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

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

รูปที่ 1 ตัวอย่างรายงาน HTML

การผสานรวม IDE

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

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

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

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

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

ข้อกำหนด

หมายเหตุ: ดูข้อกำหนดและวิธีการตั้งค่าสำหรับชุดโปรแกรมทดสอบ AGP ได้ที่ชุดโปรแกรมทดสอบ AGP

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

• Android Studio Panda 1 Canary 4 ขึ้นไป
• ปลั๊กอิน Android Gradle (AGP) เวอร์ชัน 9.0 ขึ้นไป
• ปลั๊กอิน Compose Preview Screenshot Testing เวอร์ชัน 0.0.1-alpha16 ขึ้นไป
• 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-alpha16 ขึ้นไป
• Kotlin เวอร์ชัน 1.9.20 ขึ้นไป เราขอแนะนำให้ใช้ Kotlin 2.0 ขึ้นไปเพื่อให้คุณใช้ปลั๊กอิน Gradle ของคอมไพเลอร์ Compose ได้
• JDK เวอร์ชัน 17 ขึ้นไป
• เปิดใช้ Compose สำหรับโปรเจ็กต์แล้ว เราขอแนะนำให้เปิดใช้ Compose โดยใช้ปลั๊กอิน Gradle ของคอมไพเลอร์ Compose

หมายเหตุ: หากใช้ปลั๊กอิน Gradle ของคอมไพเลอร์ Compose ไม่ได้ คุณสามารถเปิดใช้ Compose โดยประกาศทรัพยากร Dependency ในคอมไพเลอร์ Compose โดยตรง ตรวจสอบว่าคุณใช้ kotlinCompilerExtensionVersion เวอร์ชัน 1.5.4 ขึ้นไป

ตั้งค่า

ทั้งเครื่องมือที่ผสานรวมและงาน Gradle ที่เกี่ยวข้องจะอาศัยปลั๊กอิน Compose Preview Screenshot Testing โปรดทำตามขั้นตอนต่อไปนี้เพื่อตั้งค่าปลั๊กอิน

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. เพิ่มทรัพยากร Dependency 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)
      }
      

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

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

ดาวน์โหลด Android CLI

ลองใช้ Android CLI เพื่อแสดงผลตัวอย่าง Compose

ลองใช้ Android CLI หากคุณไม่ได้ใช้ Android Studio หรือต้องการดำเนินการจากบรรทัดคำสั่ง

ตัวอย่างเช่น ใช้คำสั่ง android studio render-compose-preview เมื่อต้องการแสดงผลตัวอย่าง Compose สำหรับการทดสอบภาพ

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)

หมายเหตุ: รูปภาพอ้างอิงจะตั้งชื่อด้วยการเชื่อมโยงชื่อที่สมบูรณ์ของฟังก์ชันทดสอบและแฮชของพารามิเตอร์ตัวอย่าง เช่น com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png

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

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

ใน IDE

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

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

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

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

android.compose.screenshot.maxHeapSize=4g

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

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

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

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

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