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

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

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

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

• از @PreviewTest برای ایجاد تست‌های اسکرین‌شات برای پیش‌نمایش‌های ترکیبی موجود یا جدید استفاده کنید.
• Generate reference images from those composable previews.
• یک گزارش 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.
  • Unified run panel. Screenshot test results appear in the standard Run tool window. Tests are grouped by class and function, with pass or fail status clearly marked.
  • ابزار تفاوت بصری. وقتی آزمایشی با شکست مواجه می‌شود، تب Screenshot به شما امکان می‌دهد تصاویر مرجع ، واقعی و تفاوت را در کنار هم مقایسه کنید.
  • ویژگی‌های دقیق. تب ویژگی‌ها، فراداده‌هایی در مورد تست‌های ناموفق، از جمله درصد تطابق، ابعاد تصویر و پیکربندی پیش‌نمایش خاص مورد استفاده (برای مثال، uiMode یا fontScale ) ارائه می‌دهد.

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

الزامات

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

• Android Studio Panda 1 Canary 4 or higher.
• افزونه‌ی گریدل اندروید (AGP) نسخه‌ی ۹.۰ یا بالاتر.
• افزونه‌ی پیش‌نمایش نوشتن اسکرین‌شات برای تست، نسخه‌ی ۰.۰.۱-آلفا۱۴ یا بالاتر.
• Kotlin version 2.2.10 or higher.
• JDK version 17 or higher.
• فعال‌سازی Compose برای پروژه شما. توصیه می‌کنیم Compose را با استفاده از افزونه Compose Compiler Gradle فعال کنید.

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

• افزونه‌ی گریدل اندروید (AGP) نسخه‌ی ۸.۵.۰ یا بالاتر.
• افزونه‌ی پیش‌نمایش نوشتن اسکرین‌شات برای تست، نسخه‌ی ۰.۰.۱-آلفا۱۴ یا بالاتر.
• کاتلین نسخه ۱.۹.۲۰ یا بالاتر. توصیه می‌کنیم از کاتلین ۲.۰ یا بالاتر استفاده کنید تا بتوانید از افزونه Compose Compiler Gradle استفاده کنید.
• JDK version 17 or higher.
• فعال‌سازی 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. In your module-level build.gradle.kts file, add the plugin in the plugins {} block:

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. Add the screenshot-validation-api and ui-tooling dependencies.

   1. Add them to your version catalogs:

      [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. Add them to your module-level build.gradle.kts file:

      dependencies {
        screenshotTestImplementation(libs.screenshot.validation.api)
        screenshotTestImplementation(libs.androidx.ui.tooling)
      }
      

Designate composable previews to use for screenshot tests

برای تعیین پیش‌نمایش‌های ترکیبی که می‌خواهید برای تست‌های اسکرین‌شات استفاده کنید، پیش‌نمایش‌ها را با حاشیه‌نویسی @PreviewTest علامت‌گذاری کنید. پیش‌نمایش‌ها باید در مجموعه منبع جدید screenshotTest قرار داشته باشند، برای مثال:

app/src/screenshotTest/kotlin/com/example/yourapp/ ExamplePreviewScreenshotTest.kt

You can add more composables or previews, including multi-previews, in this file or other files created in the same source set.

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

Generate reference images

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

In the IDE

Click the gutter icon next to a @PreviewTest function and select Add/Update Reference Images . Select the previews in the dialog and click Add .

With the Gradle tasks

وظیفه Gradle زیر را اجرا کنید:

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

After the task completes, find the reference images in app/src/screenshotTestDebug/reference ( {module}/src/screenshotTest{Variant}/reference ).

Generate a test report

Once the reference images exist, generate a test report by following the instructions in this section for the IDE integration or for the Gradle tasks.

در IDE

Click the gutter icon next to a @PreviewTest function and select Run 'ScreenshotTests' .

If a test fails, click the test name in the Run panel. Select the Screenshot tab to inspect the image diff using the integrated zoom and pan controls.

With the Gradle tasks

Run the validate task to take a new screenshot and compare it with the reference image:

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

The verification task creates an HTML report at {module}/build/reports/screenshotTest/preview/{variant}/index.html .

عیب‌یابی

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

android.compose.screenshot.maxHeapSize=4g

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

• Kotlin Multiplatform (KMP): Both the IDE and the underlying plugin are engineered exclusively for Android projects. They don't support non-Android targets in KMP projects.

You can find the complete list of current known issues in the tool's issue tracker component . Report any other feedback and issues through the issue tracker .

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

For a full list of release updates, see the release notes .