با شروع از Android Gradle Plugin (AGP) 9.5.0-alpha03 و موتور تست تصویر پیشنمایش Compose 0.0.1-alpha16 ، تست تصویر با چارچوب مجموعههای تست بومی AGP یکپارچه شده است.
این رویکرد جایگزین افزونهی مستقل اسکرینشات ( com.android.compose.screenshot ) میشود. ما به دلایل زیر استفاده از مجموعههای تست AGP را توصیه میکنیم:
- چرخه حیات وظیفه بومی Gradle : تستهای اسکرینشات مستقیماً در چرخه حیات تست استاندارد Gradle و AGP ادغام میشوند و باعث بهبود جداسازی وظیفه و قابلیت اطمینان اجرای تست میشوند.
- پشتیبانی از مجموعههای چند متغیره و سفارشی : شما میتوانید چندین مجموعه تست اسکرینشات مجزا (مانند
screenshotTest،uiTestsیاsmokeTests) را در یک ماژول واحد ایجاد کنید و انواع ساخت خاص (مانندdemoDebugیاrelease) را هدف قرار دهید، نه اینکه به یک مجموعه منبع از پیش پیکربندی شده محدود شوید. - عملکرد ساخت و جداسازی بهبود یافته : مجموعههای تست AGP از تبدیلهای مصنوعی داخلی (مانند استخراج زمان اجرای Layoutlib) و بارگذاری کلاس ایزوله، با پشتیبانی کامل از ذخیرهسازی پیکربندی Gradle و جداسازی پروژه، استفاده میکنند.
الزامات
برای استفاده از Compose Screenshot Testing با مجموعههای آزمایشی، مطمئن شوید که محیط شما الزامات زیر را برآورده میکند:
- اندروید استودیو Rabbit 1 Canary 4 یا بالاتر.
- افزونهی گریدل اندروید (AGP) نسخهی ۹.۵.۰-alpha03 یا بالاتر.
- موتور تصویرسازی صفحه (Compose Screenshot Engine) نسخه ۰.۰.۱-alpha16 یا بالاتر.
- JDK نسخه ۱۷ یا بالاتر.
- فعالسازی Compose برای پروژه شما. توصیه میکنیم Compose را با استفاده از افزونه Compose Compiler Gradle فعال کنید.
راهاندازی و پیکربندی
برای پیکربندی تست تصویر صفحه Compose با مجموعههای تست، مراحل زیر را انجام دهید:
۱. پرچمهای آزمایشی را فعال کنید
در فایل gradle.properties ریشه پروژه خود، تست اسکرینشات و پشتیبانی از مجموعه تست را فعال کنید:
android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true
۲. مجموعه تست را در فایل build.gradle.kts پیکربندی کنید
در فایل build.gradle.kts ماژول خود، یک مجموعه تست اسکرینشات را در بلوک 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")
}
}
}
}
۳. مجموعه منبع آزمایشی را ایجاد کنید
یک دایرکتوری مجموعه منبع اختصاصی مطابق با نام مجموعه خود ایجاد کنید:
{module}/src/{suiteName}/kotlin/
برای مثال، برای مجموعهای به نام screenshotTest :
feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt
۴. تستهای پیشنمایش قابل ترکیب را تعریف کنید
حاشیهنویسی کامپوننتها با استفاده از @PreviewTest و @Preview استاندارد یا حاشیهنویسیهای چند پیشنمایشی:
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)
}
}
تستهای اسکرینشات را اجرا کنید
مجموعههای تست AGP بر اساس نام مجموعه، هدف و انواع آن، وظایف اختصاصی Gradle را تولید میکنند.
۱. تصاویر مرجع را تولید یا بهروزرسانی کنید
پیشنمایشهای قابل ترکیب را رندر کنید و تصاویر مرجع طلایی خط پایه را ذخیره کنید:
- لینوکس و macOS :
./gradlew update{SuiteName}{Target}{Variant}TestSuite(برای مثال،./gradlew updateScreenshotTestDefaultDemoDebugTestSuite) - ویندوز :
gradlew updateScreenshotTestDefaultDemoDebugTestSuite
تصاویر مرجع در آدرس زیر تولید و ذخیره میشوند:
{module}/src/{suiteName}{Target}{Variant}/reference/
۲. تأیید و اجرای تستها
اسکرینشاتهای جدید را رندر کنید و آنها را با تصاویر مرجع مقایسه کنید:
- لینوکس و macOS :
./gradlew test{SuiteName}{Target}{Variant}TestSuite(برای مثال،./gradlew testScreenshotTestDefaultDemoDebugTestSuite) - ویندوز :
gradlew testScreenshotTestDefaultDemoDebugTestSuite
بررسی گزارشهای آزمایش
اگر تفاوتی تشخیص داده شود یا تستها با شکست مواجه شوند، AGP یک گزارش تست HTML تولید میکند.
- محل گزارش :
{module}/build/reports/tests/{taskName}/index.html(برای مثال،app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)
گزارش بهروز شده شامل موارد زیر است:
- کارت فراداده سربرگ : نام آزمون، روش پیشنمایش، نوع، مجموعه و نشان وضعیت را نمایش میدهد.
- دستهبندی خطا : به وضوح خطاهای
Reference Image Missing،Image Size MismatchیاPixel Mismatchبا ردیابیهای پشته قابل کپی علامتگذاری میکند. - تفاوت بصری پویا : تغییرات ظریف را با شدت کمتر و تغییرات عمده را با تأکید بر کنتراست بالا برجسته میکند تا از بلعیدن عناصر تو در تو جلوگیری شود.
مهاجرت از افزونه مستقل قدیمی
برای مهاجرت از افزونهی اسکرینشات مستقل قدیمی به مجموعههای آزمایشی AGP، پیکربندی Gradle و دستورات وظیفهی آن را بهروزرسانی کنید.
مقایسه پیکربندی DSL برای ساخت
افزونه مستقل قدیمی (منسوخ شده)
// 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")
}
مجموعههای تست AGP (توصیه میشود)
// 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")
}
}
}
}
نگاشت وظایف و مسیرها
| مفهوم | تنظیمات قدیمی (منسوخ شده) | مجموعههای تست AGP (توصیه میشود) |
|---|---|---|
| وظیفه بهروزرسانی | ./gradlew updateDebugScreenshotTest | ./gradlew update{SuiteName}{Target}{Variant}TestSuite |
| وظیفه تست | ./gradlew validateDebugScreenshotTest | ./gradlew test{SuiteName}{Target}{Variant}TestSuite |
| مسیر مرجع | src/screenshotTestDebug/reference | src/{suiteName}{Target}{Variant}/reference |
| مسیر گزارش | build/reports/screenshotTest/debug/ | build/reports/tests/{taskName}/ |