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

تست اسکرین‌شات روشی مؤثر برای تأیید چگونگی ظاهر رابط کاربری شما برای کاربران است. ابزار تست اسکرین‌شات پیش‌نمایش نوشتاری، سادگی و ویژگی‌های پیش‌نمایش‌های ترکیبی را با مزایای بهره‌وری اجرای تست‌های اسکرین‌شات سمت میزبان ترکیب می‌کند. تست اسکرین‌شات پیش‌نمایش نوشتاری به گونه‌ای طراحی شده است که به سادگی پیش‌نمایش‌های ترکیبی باشد.

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

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

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

ادغام 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) نسخه‌ی ۹.۰ یا بالاتر.
• افزونه‌ی پیش‌نمایش نوشتن اسکرین‌شات برای تست، نسخه‌ی ۰.۰.۱-آلفا۱۴ یا بالاتر.
• کاتلین نسخه ۲.۲.۱۰ یا بالاتر.
• JDK نسخه ۱۷ یا بالاتر.
• فعال‌سازی Compose برای پروژه شما. توصیه می‌کنیم Compose را با استفاده از افزونه Compose Compiler Gradle فعال کنید.

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

• افزونه‌ی گریدل اندروید (AGP) نسخه‌ی ۸.۵.۰ یا بالاتر.
• افزونه‌ی پیش‌نمایش نوشتن اسکرین‌شات برای تست، نسخه‌ی ۰.۰.۱-آلفا۱۴ یا بالاتر.
• کاتلین نسخه ۱.۹.۲۰ یا بالاتر. توصیه می‌کنیم از کاتلین ۲.۰ یا بالاتر استفاده کنید تا بتوانید از افزونه 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-alpha14 را به پروژه‌ی خود اضافه کنید.

   1. افزونه را به فایل کاتالوگ‌های نسخه خود اضافه کنید:

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.1.20"
      screenshot = "0.0.1-alpha14"
      
      [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 پشتیبانی نمی‌کنند.

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

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

برای مشاهده لیست کامل به‌روزرسانی‌های منتشر شده، به یادداشت‌های انتشار مراجعه کنید.