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

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

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

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

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

ادغام IDE

در حالی که می‌توانید با اجرای دستی وظایف Gradle ( updateScreenshotTest و validateScreenshotTest ) از ابزار Compose Preview Screenshot Testing استفاده کنید، Android Studio Otter 3 Feature Drop Canary 4 یکپارچه‌سازی کامل با IDE را معرفی می‌کند. این به شما امکان می‌دهد تصاویر مرجع ایجاد کنید، تست‌ها را اجرا کنید و خطاهای اعتبارسنجی را کاملاً درون IDE تجزیه و تحلیل کنید. در اینجا برخی از ویژگی‌های کلیدی آورده شده است:

  • آیکون‌های حاشیه‌ای درون ویرایشگر. اکنون می‌توانید تست‌ها را اجرا کنید یا تصاویر مرجع را مستقیماً از کد منبع به‌روزرسانی کنید. آیکون‌های سبز رنگ اجرا در حاشیه کنار composableها و کلاس‌های حاشیه‌نویسی شده با @PreviewTest ظاهر می‌شوند.
    • اجرای تست‌های اسکرین‌شات. اجرای تست‌ها به طور خاص برای یک تابع یا برای کل یک کلاس.
    • تصاویر مرجع را اضافه یا به‌روزرسانی کنید. جریان به‌روزرسانی را به‌طور خاص برای محدوده انتخاب‌شده فعال کنید.

  • مدیریت تعاملی منابع. به‌روزرسانی تصاویر منابع اکنون ایمن‌تر و جزئی‌تر شده است.
    • پنجره‌ی جدید تولید تصویر مرجع. به جای اجرای یک وظیفه‌ی Gradle به صورت دسته‌ای، یک پنجره‌ی جدید به شما امکان می‌دهد پیش‌نمایش‌ها را برای تولید یا به‌روزرسانی، تجسم و انتخاب کنید.
    • پیش‌نمایش تغییرات. این کادر محاوره‌ای تمام تغییرات پیش‌نمایش (مانند حالت روشن یا تاریک یا دستگاه‌های مختلف) را به‌صورت جداگانه فهرست می‌کند و به شما امکان می‌دهد قبل از تولید تصاویر، موارد خاص را علامت بزنید یا علامت آنها را بردارید.

  • نتایج تست یکپارچه و نمایشگر تفاوت‌ها. مشاهده نتایج بدون ترک IDE.
    • پنل اجرای یکپارچه. نتایج تست اسکرین‌شات در پنجره استاندارد ابزار اجرا ظاهر می‌شوند. تست‌ها بر اساس کلاس و تابع گروه‌بندی می‌شوند و وضعیت قبولی یا ردی آنها به وضوح مشخص شده است.
    • ابزار تفاوت بصری. وقتی آزمایشی با شکست مواجه می‌شود، تب Screenshot به شما امکان می‌دهد تصاویر مرجع ، واقعی و تفاوت را در کنار هم مقایسه کنید.
    • ویژگی‌های دقیق. تب ویژگی‌ها، فراداده‌هایی در مورد تست‌های ناموفق، از جمله درصد تطابق، ابعاد تصویر و پیکربندی پیش‌نمایش خاص مورد استفاده (برای مثال، uiMode یا fontScale ) ارائه می‌دهد.

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

الزامات

برای استفاده از Compose Preview Screenshot Testing از طریق یکپارچه‌سازی کامل IDE، پروژه شما باید شرایط زیر را داشته باشد:

  • اندروید استودیو پاندا ۱ قناری ۴ یا بالاتر.
  • افزونه‌ی گریدل اندروید (AGP) نسخه‌ی ۹.۰ یا بالاتر.
  • افزونه‌ی پیش‌نمایش نوشتن اسکرین‌شات نسخه ۰.۰.۱-alpha۱۳ یا بالاتر.
  • کاتلین نسخه ۱.۹.۲۰ یا بالاتر. توصیه می‌کنیم از کاتلین ۲.۰ یا بالاتر استفاده کنید تا بتوانید از افزونه Compose Compiler Gradle استفاده کنید.
  • JDK نسخه ۱۷ یا بالاتر.
  • فعال‌سازی Compose برای پروژه شما. توصیه می‌کنیم Compose را با استفاده از افزونه Compose Compiler Gradle فعال کنید.

اگر فقط می‌خواهید از وظایف Gradle اصلی بدون ادغام IDE استفاده کنید، الزامات به شرح زیر است:

  • اندروید استودیو پاندا ۱ قناری ۴ یا بالاتر.
  • افزونه‌ی گریدل اندروید (AGP) نسخه‌ی ۸.۵.۰ یا بالاتر.
  • افزونه‌ی پیش‌نمایش نوشتن اسکرین‌شات نسخه ۰.۰.۱-alpha۱۳ یا بالاتر.
  • کاتلین نسخه ۱.۹.۲۰ یا بالاتر. توصیه می‌کنیم از کاتلین ۲.۰ یا بالاتر استفاده کنید تا بتوانید از افزونه Compose Compiler Gradle استفاده کنید.
  • JDK نسخه ۱۷ یا بالاتر.
  • فعال‌سازی Compose برای پروژه شما. توصیه می‌کنیم Compose را با استفاده از افزونه Compose Compiler Gradle فعال کنید.

راه‌اندازی

هم ابزار یکپارچه و هم وظایف اساسی 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-alpha13 را به پروژه‌ی خود اضافه کنید.
    1. افزونه را به فایل کاتالوگ‌های نسخه خود اضافه کنید: 
                [versions]
          agp = "9.0.0-rc03"
          kotlin = "2.1.20"
          screenshot = "0.0.1-alpha13"

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

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

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

در IDE

روی نماد حاشیه کنار تابع @PreviewTest کلیک کنید و گزینه Add/Update Reference Images را انتخاب کنید. پیش‌نمایش‌های مورد نظر را در کادر محاوره‌ای انتخاب کرده و روی Add کلیک کنید.

با وظایف Gradle

وظیفه 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 ) پیدا کنید.

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

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

در IDE

روی آیکون ناودانی کنار تابع @PreviewTest کلیک کنید و گزینه‌ی «اجرای '...ScreenshotTests'» را انتخاب کنید.

اگر آزمایشی با شکست مواجه شد، روی نام آزمایش در پنل اجرا کلیک کنید. برای بررسی تفاوت تصویر با استفاده از کنترل‌های بزرگنمایی و حرکت افقی، تب Screenshot را انتخاب کنید.

با وظایف Gradle

دستور validate را اجرا کنید تا یک اسکرین‌شات جدید گرفته شود و با تصویر مرجع مقایسه شود:

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

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

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

  • کاتلین چندسکویی (KMP): هم IDE و هم افزونه‌ی اصلی منحصراً برای پروژه‌های اندروید طراحی شده‌اند. آن‌ها از اهداف غیراندرویدی در پروژه‌های KMP پشتیبانی نمی‌کنند.
  • تغییر نام توابع: تغییر نام تابعی که با @PreviewTest حاشیه‌نویسی شده است، ارتباط آن با تصاویر مرجع موجود را از بین می‌برد. در این صورت، باید تصاویر مرجع را برای نام جدید تابع، دوباره تولید کنید .

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

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

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

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

  • سازگاری با JDK 17 یا بالاتر.
  • رفع اشکالات و بهبود ادغام با اندروید استودیو.

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

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

  • سازگاری با افزونه‌ی اندروید گریدل (AGP) نسخه ۹.۰
  • پشتیبانی از اجرای تست‌های اسکرین‌شات در JDK 24 و بالاتر.
  • پشتیبانی از پیکربندی حداکثر اندازه heap.
  • رفع مشکلات رندرینگ و بهبود پایداری تست.
  • گزارش‌دهی بهبود یافته تا شامل درصد اختلاف و سایر فراداده‌های مربوط به تصاویر جدید و مرجع باشد.

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

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

  • سازگاری با افزونه‌ی اندروید گریدل (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 خالی اضافه شد
  • بهبود عملکرد: الگوریتم تشخیص تفاوت تصویر به‌روزرسانی شد تا سریع‌تر شود