نوشتن آزمایش پیش‌نمایش عکس صفحه

تست اسکرین‌شات روشی مؤثر برای تأیید چگونگی ظاهر رابط کاربری شما برای کاربران است. ابزار تست اسکرین‌شات پیش‌نمایش نوشتاری (Compose Preview Screenshot Testing) سادگی و ویژگی‌های پیش‌نمایش‌های ترکیبی را با مزایای بهره‌وری اجرای تست‌های اسکرین‌شات سمت میزبان ترکیب می‌کند. تست اسکرین‌شات پیش‌نمایش نوشتاری (Compose Preview Screenshot Testing) به گونه‌ای طراحی شده است که به آسانی پیش‌نمایش‌های ترکیبی باشد.

تست اسکرین‌شات، یک تست خودکار است که از یک بخش از رابط کاربری اسکرین‌شات می‌گیرد و سپس آن را با یک تصویر مرجع که قبلاً تأیید شده است، مقایسه می‌کند. اگر تصاویر مطابقت نداشته باشند، تست با شکست مواجه می‌شود و یک گزارش HTML تولید می‌کند تا به شما در مقایسه و یافتن تفاوت‌ها کمک کند.

با ابزار تست پیش‌نمایش تصویر (Pause Preview Screenshot Testing Tool)، می‌توانید:

• از @PreviewTest برای ایجاد تست‌های اسکرین‌شات برای پیش‌نمایش‌های ترکیبی موجود یا جدید استفاده کنید.
• تصاویر مرجع را از آن پیش‌نمایش‌های قابل ترکیب تولید کنید.
• یک گزارش HTML ایجاد کنید که تغییرات اعمال شده در آن پیش‌نمایش‌ها را پس از اعمال تغییرات در کد، مشخص کند.
• از پارامترهای @Preview ، مانند uiMode یا fontScale ، و پیش‌نمایش‌های چندگانه برای کمک به مقیاس‌بندی تست‌های خود استفاده کنید.
• تست‌های خود را با مجموعه منبع جدید screenshotTest ماژولار کنید.

الزامات

برای استفاده از تست پیش‌نمایش تصویر Compose، به موارد زیر نیاز دارید:

• افزونه‌ی اندروید Gradle نسخه‌ی ۸.۵.۰ یا بالاتر.
• کاتلین ۱.۹.۲۰ یا بالاتر. توصیه می‌کنیم از کاتلین ۲.۰ یا بالاتر استفاده کنید تا بتوانید از افزونه Compose Compiler Gradle استفاده کنید.
• JDK 23 یا پایین‌تر.

• فعال‌سازی Compose برای پروژه شما. توصیه می‌کنیم Compose را با استفاده از افزونه Compose Compiler Gradle فعال کنید.

راه‌اندازی

برای فعال کردن ابزار، مراحل زیر را دنبال کنید:

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-alpha11 را به پروژه‌ی خود اضافه کنید.
   1. افزونه را به فایل کاتالوگ‌های نسخه خود اضافه کنید:

                [versions]
                agp = "8.11.0-alpha06"
                kotlin = "2.1.20"
                screenshot = "0.0.1-alpha11"
      
                [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)
                }
              

پیش‌نمایش‌های ترکیبی را برای استفاده در تست‌های اسکرین‌شات تعیین کنید

برای تعیین پیش‌نمایش‌های ترکیبی که می‌خواهید برای تست‌های اسکرین‌شات استفاده کنید، پیش‌نمایش‌ها را با حاشیه‌نویسی @PreviewTest علامت‌گذاری کنید. پیش‌نمایش‌ها باید در مجموعه منبع جدید screenshotTest قرار داشته باشند، برای مثال app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt .

شما می‌توانید ترکیبات و/یا پیش‌نمایش‌های بیشتری، از جمله پیش‌نمایش‌های چندگانه، را در این فایل یا سایر فایل‌های ایجاد شده در همان مجموعه منبع اضافه کنید.

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

تولید تصاویر مرجع

پس از تنظیم یک کلاس آزمایشی، باید برای هر پیش‌نمایش، تصاویر مرجع ایجاد کنید. این تصاویر مرجع برای شناسایی تغییرات بعدی، پس از ایجاد تغییرات در کد، استفاده می‌شوند. برای تولید تصاویر مرجع برای آزمایش‌های پیش‌نمایش ترکیبی خود، وظیفه Gradle زیر را اجرا کنید:

• لینوکس و macOS: ./gradlew updateDebugScreenshotTest ( ./gradlew :{module}:update{Variant}ScreenshotTest )
• ویندوز: gradlew updateDebugScreenshotTest ( gradlew :{module}:update{Variant}ScreenshotTest )

پس از اتمام کار، تصاویر مرجع را در app/src/screenshotTestDebug/reference ( {module}/src/screenshotTest{Variant}/reference ) پیدا کنید.

ایجاد گزارش آزمایش

پس از وجود تصاویر مرجع، وظیفه اعتبارسنجی را اجرا کنید تا یک تصویر جدید از صفحه گرفته شود و با تصویر مرجع مقایسه شود:

• لینوکس و macOS: ./gradlew validateDebugScreenshotTest ( ./gradlew :{module}:validate{Variant}ScreenshotTest )
• ویندوز: gradlew validateDebugScreenshotTest ( gradlew :{module}:validate{Variant}ScreenshotTest )

وظیفه تأیید، یک گزارش HTML در {module}/build/reports/screenshotTest/preview/{variant}/index.html ایجاد می‌کند.

مشکلات شناخته شده

می‌توانید فهرست فعلی مشکلات شناخته‌شده را در مؤلفه‌ی ردیاب مشکلات این ابزار پیدا کنید. هرگونه بازخورد و مشکل دیگری را از طریق ردیاب مشکلات گزارش دهید.

انتشار به‌روزرسانی‌ها

۰.۰.۱-آلفا۱۱

این نسخه معرفی می‌کند:

• سازگاری با افزونه‌ی اندروید گریدل (AGP) نسخه ۸.۱۳.
• پشتیبانی از تجزیه فایل‌های XML drawables با مقادیر اعشاری صرف نظر از زبان دستگاه میزبان اضافه شد.
• برای یک ماشین میزبان که از JDK 24 یا بالاتر استفاده می‌کند، JDK سازگار (11-23) در صورت نصب بودن، انتخاب خواهد شد.

۰.۰.۱-آلفا۱۰

این نسخه معرفی می‌کند:

• از این نسخه، باید تمام توابع پیش‌نمایش خود را با حاشیه‌نویسی @PreviewTest علامت‌گذاری کنید. پیش‌نمایش‌های بدون این حاشیه‌نویسی اجرا نخواهند شد.

• دایرکتوری تصویر مرجع از {module}/src/{variant}/screenshotTest/reference به {module}/src/screenshotTest{Variant}/reference تغییر یافته است. این کار برای اطمینان از این است که تصاویر مرجع تولید شده بخشی از کد عملیاتی نباشند و با ساختار دایرکتوری سایر انواع تست هم‌تراز شوند.

• وظیفه {variant}PreviewScreenshotRender حذف شده است. رندر تصویر به موتور تست JUnit منتقل شده است.

• وظیفه update{Variant}ScreenshotTest تصاویر رندر جدید را قبل از به‌روزرسانی با تصاویر مرجع مقایسه می‌کند. این وظیفه فقط تصاویری را به‌روزرسانی می‌کند که تفاوت‌هایشان بیشتر از یک آستانه مشخص شده باشد. پرچم خط فرمان --updateFilter حذف شد.

۰.۰.۱-alpha06

این نسخه معرفی می‌کند:

آستانه تفاوت تصویر: این تنظیم آستانه سراسری جدید به شما امکان می‌دهد کنترل دقیق‌تری بر مقایسه تصاویر داشته باشید. برای پیکربندی، build.gradle.kts ماژول خود را به‌روزرسانی کنید:

android {
    testOptions {
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

این آستانه برای تمام تست‌های اسکرین‌شات تعریف‌شده در ماژول اعمال خواهد شد.

• رفع اشکالات: برخی از اشکالات رندرکننده Compose و پشتیبانی از compose خالی اضافه شد
• بهبود عملکرد: الگوریتم تشخیص تفاوت تصویر به‌روزرسانی شد تا سریع‌تر شود