Kiểm thử ảnh chụp màn hình của tính năng xem trước trong Compose

Kiểm thử ảnh chụp màn hình là một cách hiệu quả để xác minh giao diện người dùng của bạn trông như thế nào đối với người dùng. Công cụ Kiểm thử ảnh chụp màn hình trong Bản xem trước của Compose kết hợp tính đơn giản và các tính năng của bản xem trước thành phần kết hợp với hiệu suất tăng lên khi chạy kiểm thử ảnh chụp màn hình phía máy chủ. Tính năng Kiểm thử ảnh chụp màn hình trong bản xem trước của Compose được thiết kế để dễ sử dụng như bản xem trước thành phần kết hợp.

android skills add testing-setup

Kiểm thử ảnh chụp màn hình là một quy trình kiểm thử tự động, chụp ảnh màn hình của một phần giao diện người dùng rồi so sánh ảnh đó với một hình ảnh tham khảo đã được phê duyệt trước đó. Nếu hình ảnh không khớp, kiểm thử sẽ không đạt và tạo báo cáo HTML để giúp bạn so sánh và tìm ra điểm khác biệt.

Với công cụ Kiểm thử ảnh chụp màn hình trong Bản xem trước của Compose, bạn có thể:

• Sử dụng @PreviewTest để tạo các hoạt động kiểm thử ảnh chụp màn hình cho bản xem trước composable hiện có hoặc mới.
• Tạo hình ảnh tham khảo từ các bản xem trước composable đó.
• Tạo báo cáo HTML xác định các thay đổi đối với những bản xem trước đó sau khi bạn thay đổi mã.
• Sử dụng các tham số @Preview, chẳng hạn như uiMode hoặc fontScale và nhiều bản xem trước để giúp bạn mở rộng quy mô thử nghiệm.
• Mô-đun hoá các hoạt động kiểm thử bằng nhóm tài nguyên screenshotTest mới.

Tích hợp IDE

Mặc dù bạn có thể sử dụng công cụ Kiểm thử ảnh chụp màn hình trong bản xem trước của Compose bằng cách chạy các tác vụ Gradle cơ bản (updateScreenshotTest và validateScreenshotTest) theo cách thủ công, nhưng Android Studio Otter 3 Feature Drop Canary 4 sẽ ra mắt một công cụ tích hợp IDE đầy đủ. Điều này cho phép bạn tạo hình ảnh tham khảo, chạy kiểm thử và phân tích lỗi xác thực hoàn toàn trong IDE. Sau đây là một số tính năng chính:

• Biểu tượng trong rãnh của trình chỉnh sửa. Giờ đây, bạn có thể chạy kiểm thử hoặc cập nhật hình ảnh tham khảo trực tiếp từ mã nguồn. Biểu tượng chạy màu xanh lục xuất hiện trong rãnh bên cạnh các thành phần kết hợp và lớp được chú thích bằng @PreviewTest.
  • Chạy kiểm thử ảnh chụp màn hình. Thực thi các kiểm thử dành riêng cho một hàm hoặc cho toàn bộ lớp.
  • Thêm hoặc cập nhật hình ảnh tham khảo. Kích hoạt quy trình cập nhật cụ thể cho phạm vi đã chọn.

• Quản lý tệp đối chiếu tương tác. Việc cập nhật hình ảnh tham khảo giờ đây an toàn và chi tiết hơn.
  • Hộp thoại tạo hình ảnh tham khảo mới. Thay vì chạy một tác vụ Gradle hàng loạt, một hộp thoại mới cho phép bạn trực quan hoá và chọn chính xác bản xem trước cần tạo hoặc cập nhật.
  • Xem trước các biến thể. Hộp thoại này liệt kê riêng từng biến thể xem trước (chẳng hạn như giao diện sáng hoặc giao diện tối, hoặc các thiết bị khác nhau), cho phép bạn chọn hoặc xoá các mục cụ thể trước khi tạo hình ảnh tạo sinh.

• Trình xem kết quả kiểm thử và trình xem khác biệt tích hợp. Xem kết quả mà không cần rời khỏi IDE.
  • Bảng điều khiển chạy hợp nhất. Kết quả kiểm thử ảnh chụp màn hình sẽ xuất hiện trong cửa sổ công cụ Run (Chạy) tiêu chuẩn. Các bài kiểm thử được nhóm theo lớp và hàm, đồng thời trạng thái đạt hoặc không đạt được đánh dấu rõ ràng.
  • Công cụ so sánh trực quan. Khi một kiểm thử không thành công, thẻ Screenshot (Ảnh chụp màn hình) cho phép bạn so sánh các hình ảnh Reference (Tham chiếu), Actual (Thực tế) và Diff (Khác biệt) cạnh nhau.
  • Thuộc tính chi tiết. Thẻ Attributes (Thuộc tính) cung cấp siêu dữ liệu về các thử nghiệm không thành công, bao gồm tỷ lệ phần trăm khớp, kích thước hình ảnh và cấu hình xem trước cụ thể được sử dụng (ví dụ: uiMode hoặc fontScale).

• Phạm vi kiểm thử linh hoạt. Giờ đây, bạn có thể thực thi các chương trình kiểm thử ảnh chụp màn hình với nhiều phạm vi ngay trong Chế độ xem dự án. Nhấp chuột phải vào một mô-đun, thư mục, tệp hoặc lớp để chạy kiểm thử ảnh chụp màn hình dành riêng cho lựa chọn đó.

Yêu cầu

Để sử dụng tính năng Kiểm thử ảnh chụp màn hình trong bản xem trước của Compose thông qua việc tích hợp đầy đủ IDE, dự án của bạn phải đáp ứng các yêu cầu sau:

• Android Studio Panda 1 Canary 4 trở lên.
• Trình bổ trợ Android cho Gradle (AGP) phiên bản 9.0 trở lên.
• Trình bổ trợ Thử nghiệm ảnh chụp màn hình trong bản xem trước của Compose phiên bản 0.0.1-alpha16 trở lên.
• Kotlin phiên bản 2.2.10 trở lên.
• JDK phiên bản 17 trở lên.
• Đã bật Compose cho dự án của bạn. Bạn nên bật Compose bằng Trình bổ trợ Gradle của trình biên dịch Compose.

Nếu bạn chỉ muốn sử dụng các tác vụ Gradle cơ bản mà không cần tích hợp IDE, thì các yêu cầu như sau:

• Trình bổ trợ Android cho Gradle (AGP) phiên bản 8.5.0 trở lên.
• Trình bổ trợ Thử nghiệm ảnh chụp màn hình trong bản xem trước của Compose phiên bản 0.0.1-alpha16 trở lên.
• Kotlin phiên bản 1.9.20 trở lên. Bạn nên sử dụng Kotlin 2.0 trở lên để có thể dùng trình bổ trợ Compose Compiler cho Gradle.
• JDK phiên bản 17 trở lên.
• Đã bật Compose cho dự án của bạn. Bạn nên bật Compose bằng Trình bổ trợ Gradle của trình biên dịch Compose.

Thiết lập

Cả công cụ tích hợp và các tác vụ Gradle cơ bản đều dựa vào trình bổ trợ Kiểm thử ảnh chụp màn hình của tính năng Xem trước trong Compose. Để thiết lập plugin, hãy thực hiện theo các bước sau:

1. Bật thuộc tính thử nghiệm trong tệp gradle.properties của dự án.

   android.experimental.enableScreenshotTest=true
   

2. Trong khối android {} của tệp build.gradle.kts ở cấp mô-đun, hãy bật cờ thử nghiệm để sử dụng nhóm tài nguyên screenshotTest.

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

3. Thêm trình bổ trợ com.android.compose.screenshot, phiên bản 0.0.1-alpha16 vào dự án của bạn.

   1. Thêm trình bổ trợ vào tệp danh mục phiên bản:

      [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. Trong tệp build.gradle.kts cấp mô-đun, hãy thêm trình bổ trợ vào khối plugins {}:

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. Thêm các phần phụ thuộc screenshot-validation-api và ui-tooling.

   1. Thêm các phần phụ thuộc đó vào danh mục phiên bản:

      [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. Thêm các phần phụ thuộc này vào tệp build.gradle.kts cấp mô-đun:

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

Chỉ định bản xem trước composable để dùng cho các hoạt động kiểm thử ảnh chụp màn hình

Để chỉ định bản xem trước composable mà bạn muốn dùng cho các bài kiểm thử ảnh chụp màn hình, hãy đánh dấu các bản xem trước bằng chú thích @PreviewTest. Bản xem trước phải nằm trong nhóm tài nguyên screenshotTest mới, ví dụ:

app/src/screenshotTest/kotlin/com/example/yourapp/ ExamplePreviewScreenshotTest.kt

Bạn có thể thêm các thành phần kết hợp hoặc bản xem trước khác, bao gồm cả nhiều bản xem trước, vào tệp này hoặc các tệp khác được tạo trong cùng một nhóm tài nguyên.

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

Tạo hình ảnh tham khảo

Sau khi thiết lập lớp kiểm thử, bạn cần tạo hình ảnh tham khảo cho mỗi bản xem trước. Những hình ảnh tham khảo này được dùng để xác định các thay đổi sau này, sau khi bạn thay đổi mã. Để tạo hình ảnh tham khảo cho các chương trình kiểm thử ảnh chụp màn hình của bản xem trước composable, hãy làm theo hướng dẫn trong phần này về việc tích hợp IDE hoặc các tác vụ Gradle.

android studio render-compose-preview

Trong IDE

Nhấp vào biểu tượng máng xối bên cạnh hàm @PreviewTest rồi chọn Add/Update Reference Images (Thêm/Cập nhật hình ảnh tham khảo). Chọn bản xem trước trong hộp thoại rồi nhấp vào Thêm.

Với các tác vụ Gradle

Chạy tác vụ Gradle sau:

• Linux và macOS: ./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
• Windows: gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

Sau khi hoàn tất tác vụ, hãy tìm hình ảnh tham khảo trong app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Tạo báo cáo thử nghiệm

Sau khi có hình ảnh tham khảo, hãy tạo báo cáo kiểm thử bằng cách làm theo hướng dẫn trong phần này để tích hợp IDE hoặc cho các tác vụ Gradle.

Trong IDE

Nhấp vào biểu tượng trong rãnh bên cạnh hàm @PreviewTest rồi chọn Run 'ScreenshotTests' (Chạy "ScreenshotTests").

Nếu một kiểm thử không thành công, hãy nhấp vào tên kiểm thử trong bảng điều khiển Run (Chạy). Chọn thẻ Screenshot (Ảnh chụp màn hình) để kiểm tra sự khác biệt về hình ảnh bằng các chế độ điều khiển thu phóng và kéo tích hợp.

Với các tác vụ Gradle

Chạy tác vụ xác thực để chụp ảnh màn hình mới và so sánh ảnh đó với hình ảnh tham khảo:

• Linux và macOS: ./gradlew validateDebugScreenshotTest (./gradlew :{module}:validate{Variant}ScreenshotTest)
• Windows: gradlew validateDebugScreenshotTest (gradlew :{module}:validate{Variant}ScreenshotTest)

Nhiệm vụ xác minh sẽ tạo một báo cáo HTML tại {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Khắc phục sự cố

Tính năng Kiểm thử ảnh chụp màn hình trong bản xem trước của Compose chạy các chương trình kiểm thử phía máy chủ lưu trữ, có thể tốn nhiều bộ nhớ. Bạn có thể tăng kích thước vùng nhớ khối xếp tối đa cho JVM kiểm thử bằng cách thêm thuộc tính sau vào tệp gradle.properties:

android.compose.screenshot.maxHeapSize=4g

Vấn đề đã biết

• Kotlin Multiplatform (KMP): Cả IDE và trình bổ trợ cơ bản đều được thiết kế riêng cho các dự án Android. Các thư viện này không hỗ trợ mục tiêu không phải Android trong các dự án KMP.

Bạn có thể tìm thấy danh sách đầy đủ các vấn đề đã biết hiện tại trong thành phần trình theo dõi sự cố của công cụ. Báo cáo mọi ý kiến phản hồi và vấn đề khác thông qua trình theo dõi sự cố.

Nội dung cập nhật trong bản phát hành

Để xem danh sách đầy đủ các bản cập nhật, hãy xem ghi chú phát hành.