Kiểm thử ảnh chụp màn hình bằng bộ kiểm thử

Kể từ Trình bổ trợ Android cho Gradle (AGP) 9.5.0-alpha03 và công cụ Kiểm thử ảnh chụp màn hình của Bản xem trước Compose 0.0.1-alpha16, tính năng kiểm thử ảnh chụp màn hình được tích hợp với khung bộ kiểm thử gốc của AGP.

Phương pháp này sẽ thay thế trình bổ trợ ảnh chụp màn hình độc lập (com.android.compose.screenshot). Bạn nên áp dụng bộ kiểm thử AGP vì những lý do sau:

• Vòng đời tác vụ Gradle gốc: Các bài kiểm thử ảnh chụp màn hình tích hợp trực tiếp vào vòng đời kiểm thử Gradle và AGP tiêu chuẩn, giúp cải thiện khả năng cô lập tác vụ và độ tin cậy khi thực thi kiểm thử.
• Hỗ trợ nhiều biến thể và bộ kiểm thử tuỳ chỉnh: Bạn có thể tạo nhiều bộ kiểm thử ảnh chụp màn hình riêng biệt (chẳng hạn như screenshotTest, uiTests hoặc smokeTests) trong một mô-đun duy nhất và nhắm đến các biến thể bản dựng cụ thể (chẳng hạn như demoDebug hoặc release), thay vì bị giới hạn ở một nhóm tài nguyên được định cấu hình trước duy nhất.
• Cải thiện hiệu suất và khả năng cô lập bản dựng: Bộ kiểm thử AGP sử dụng các biến đổi cấu phần phần mềm tích hợp (chẳng hạn như trích xuất thời gian chạy Layoutlib) và tính năng tải lớp riêng biệt, với khả năng hỗ trợ đầy đủ cho tính năng Nhớ đệm cấu hình Gradle và Phân tách dự án.

Yêu cầu

Để sử dụng Compose Screenshot Testing với các bộ kiểm thử, hãy đảm bảo môi trường của bạn đáp ứng các yêu cầu sau:

• Android Studio Rabbit 1 Canary 4 trở lên.
• Trình bổ trợ Android cho Gradle (AGP) phiên bản 9.5.0-alpha03 trở lên.
• Compose Screenshot Engine phiên bản 0.0.1-alpha16 trở lên.
• JDK phiên bản 17 trở lên.
• Compose được bật cho dự án của bạn. Bạn nên bật Compose bằng trình bổ trợ Compose Compiler Gradle.

Thiết lập và cấu hình

Để định cấu hình kiểm thử ảnh chụp màn hình Compose bằng bộ kiểm thử, hãy hoàn tất các bước sau:

1. Bật cờ thử nghiệm

Trong tệp gradle.properties gốc của dự án, hãy bật tính năng kiểm thử ảnh chụp màn hình và hỗ trợ bộ kiểm thử:

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. Định cấu hình bộ kiểm thử trong tệp build.gradle.kts

Trong tệp build.gradle.kts của mô-đun, hãy xác định một bộ kiểm thử ảnh chụp màn hình trong khối testOptions:

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. Tạo nhóm tài nguyên kiểm thử

Tạo một thư mục nhóm tài nguyên chuyên dụng khớp với tên bộ của bạn:

{module}/src/{suiteName}/kotlin/

Ví dụ: đối với một bộ có tên là screenshotTest:

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. Xác định các kiểm thử xem trước thành phần kết hợp

Chú giải các thành phần kết hợp bằng @PreviewTest và chú giải @Preview chuẩn hoặc chú giải nhiều bản xem trước:

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

Chạy kiểm thử ảnh chụp màn hình

Bộ kiểm thử AGP tạo các tác vụ Gradle chuyên dụng dựa trên tên bộ kiểm thử, mục tiêu và các biến thể của bạn.

1. Tạo hoặc cập nhật hình ảnh tham khảo

Kết xuất bản xem trước thành phần kết hợp và lưu trữ hình ảnh tham chiếu cơ sở vàng:

• Linux và macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (ví dụ: ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Hình ảnh tham khảo được tạo và lưu tại:

{module}/src/{suiteName}{Target}{Variant}/reference/

2. Xác minh và chạy kiểm thử

Kết xuất ảnh chụp màn hình mới và so sánh với hình ảnh tham chiếu:

• Linux và macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (ví dụ: ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Kiểm tra báo cáo thử nghiệm

Nếu phát hiện thấy sự khác biệt hoặc kiểm thử không đạt, AGP sẽ tạo một báo cáo kiểm thử HTML.

• Vị trí báo cáo:{module}/build/reports/tests/{taskName}/index.html (ví dụ: app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Báo cáo mới cập nhật bao gồm:

• Thẻ siêu dữ liệu tiêu đề: Hiển thị tên kiểm thử, phương thức xem trước, biến thể, bộ kiểm thử và huy hiệu trạng thái.
• Phân loại lỗi: Gắn cờ rõ ràng Reference Image Missing, Image Size Mismatch hoặc Pixel Mismatch bằng các dấu vết ngăn xếp có thể sao chép.
• So sánh trực quan linh hoạt: Làm nổi bật những điểm sửa đổi nhỏ với cường độ thấp hơn và những thay đổi lớn với điểm nhấn có độ tương phản cao để ngăn chặn việc nuốt phần tử lồng nhau.

Di chuyển từ trình bổ trợ độc lập cũ

Để di chuyển từ trình bổ trợ chụp ảnh màn hình độc lập cũ sang bộ kiểm thử AGP, hãy cập nhật cấu hình Gradle và các lệnh tác vụ.

So sánh DSL cấu hình bản dựng

Plugin độc lập cũ (không dùng nữa)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

Bộ thử nghiệm AGP (nên dùng)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

Ánh xạ các nhiệm vụ và đường dẫn