آزمایش کردن نماگرفت پیش‌نمای Compose

آزمایش نماگرفت روشی مؤثر برای درستی‌سنجی ظاهر میانای کاربر برای کاربران است. ابزار Compose Preview Screenshot Testing سادگی و ویژگی‌های پیش‌نمایش‌های ترکیب‌پذیر را با بهره‌وری حاصل از اجرای آزمایش‌های نماگرفت سمت میزبان ترکیب می‌کند. «آزمایش نماگرفت پیش‌نمای Compose» طوری طراحی شده است که استفاده از آن به‌سادگی پیش‌نماهای قابل‌ساخت باشد.

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

با ابزار Compose Preview Screenshot Testing می‌توانید:

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

یکپارچه‌سازی IDE

While you can use the Compose Preview Screenshot Testing tool by running the underlying Gradle tasks (updateScreenshotTest and validateScreenshotTest) manually, Android Studio Otter 3 Feature Drop Canary 4 introduces a full IDE integration. این به شما امکان می‌دهد تصاویر مرجع تولید کنید، آزمایش‌ها را اجرا کنید، و شکست‌های اعتبارسنجی را کاملاً در IDE تجزیه‌وتحلیل کنید. در اینجا برخی‌از ویژگی‌های کلیدی آورده شده است:

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

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

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

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

الزامات

برای استفاده از «آزمایش کردن پیش‌نمای اسکرین‌شات Compose» ازطریق ادغام کامل IDE، پروژه شما باید شرایط زیر را داشته باشد:

  • ‫Android Studio Panda 1 Canary 4 یا بالاتر.
  • افزایه Android Gradle (AGP) نسخه ۹.۰ یا بالاتر.
  • نسخه افزایه Compose Preview Screenshot Testing 0.0.1-alpha16 یا بالاتر.
  • Kotlin نسخه ۲.۲.۱۰ یا بالاتر.
  • نسخه ۱۷ یا بالاتر JDK.
  • Compose برای پروژه‌تان فعال شد. توصیه می‌کنیم Compose را بااستفاده از افزونه Compose Compiler Gradle فعال کنید.

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

  • افزایه Android Gradle (AGP) نسخه ۸.۵.۰ یا بالاتر.
  • نسخه افزایه Compose Preview Screenshot Testing 0.0.1-alpha16 یا بالاتر.
  • Kotlin نسخه ۱.۹.۲۰ یا بالاتر. توصیه می‌کنیم از Kotlin نسخه ۲.۰ یا بالاتر استفاده کنید تا بتوانید از افزونه 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-alpha16 را به پروژه‌تان اضافه کنید.

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

      [versions]
agp = "9.0.0-rc03"
kotlin = "2.2.10"
screenshot = "0.0.1-alpha16"

[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

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

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 دنبال کنید.

در محیط توسعه یکپارچه

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

با تکالیف Gradle

تکلیف Gradle زیر را اجرا کنید:

  • Linux و macOS:‏ ./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
  • Windows: gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

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

تولید گزارش آزمایشی

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

در محیط توسعه یکپارچه

روی نماد حاشیه در کنار تابع @PreviewTest کلیک کنید و اجرای «ScreenshotTests» را انتخاب کنید.

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

با تکالیف Gradle

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

  • Linux و macOS:‏ ./gradlew validateDebugScreenshotTest (./gradlew :{module}:validate{Variant}ScreenshotTest)
  • Windows: gradlew validateDebugScreenshotTest (gradlew :{module}:validate{Variant}ScreenshotTest)

تکلیف درستی‌سنجی گزارش HTML در {module}/build/reports/screenshotTest/preview/{variant}/index.html ایجاد می‌کند.

عیب‌یابی

«آزمایش نماگرفت پیش‌نمای Compose» آزمایش‌های سمت میزبان را اجرا می‌کند که می‌تواند حافظه زیادی مصرف کند. می‌توانید حداکثر اندازه پشته را برای JVM آزمایشی با افزودن ویژگی زیر به فایل gradle.properties افزایش دهید:

android.compose.screenshot.maxHeapSize=4g

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

  • Kotlin Multiplatform (KMP): هم IDE و هم افزونه زیربنایی منحصراً برای پروژه‌های Android طراحی شده‌اند. آن‌ها از هدف‌های غیرAndroid در پروژه‌های KMP پشتیبانی نمی‌کنند.

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

به‌روزرسانی‌های نسخه پخش

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