झलक दिखाने वाले स्क्रीनशॉट की टेस्टिंग कंपोज़ करें

चेतावनी: इस पेज पर बताए गए स्टैंडअलोन com.android.compose.screenshot प्लग इन का अब रखरखाव नहीं किया जाता. हमारा सुझाव है कि आप Android Gradle प्लगिन (AGP) 9.5 या इसके बाद के वर्शन का इस्तेमाल करके, AGP टेस्ट सुइट के साथ स्क्रीनशॉट टेस्ट सेट अप करें. स्विच करने के लिए, किसी मौजूदा प्रोजेक्ट को माइग्रेट करना लेख पढ़ें.

स्क्रीनशॉट टेस्टिंग, यह पुष्टि करने का एक असरदार तरीका है कि उपयोगकर्ताओं को आपका यूज़र इंटरफ़ेस (यूआई) कैसा दिखता है. Compose Preview Screenshot Testing टूल, कंपोज़ेबल की झलक की सुविधाओं और आसान तरीके को होस्ट-साइड स्क्रीनशॉट टेस्ट चलाने से मिलने वाले फ़ायदों के साथ जोड़ता है. Compose Preview Screenshot Testing को इस तरह डिज़ाइन किया गया है कि इसका इस्तेमाल करना, कंपोज़ेबल की झलक देखने जितना आसान हो.

Android स्किल

GitHub पर देखें

स्क्रीनशॉट टेस्ट बनाना

testing-setup Android स्किल का इस्तेमाल करके, टेस्टिंग की रणनीति बनाएं और स्क्रीनशॉट टेस्ट बनाएं.

Android के सीएलआई से स्किल इंस्टॉल करने के लिए, यह कमांड चलाएं:

android skills add testing-setup

स्क्रीनशॉट टेस्ट, अपने-आप होने वाला एक टेस्ट है. इसमें यूज़र इंटरफ़ेस (यूआई) के किसी हिस्से का स्क्रीनशॉट लिया जाता है. इसके बाद, उसकी तुलना पहले से मंज़ूर की गई रेफ़रंस इमेज से की जाती है. अगर इमेज मैच नहीं होती हैं, तो टेस्ट फ़ेल हो जाता है और एक एचटीएमएल रिपोर्ट जनरेट होती है. इससे आपको इमेज की तुलना करने और उनके बीच के अंतर का पता लगाने में मदद मिलती है.

Compose की झलक दिखाने वाले स्क्रीनशॉट की टेस्टिंग के टूल की मदद से, ये काम किए जा सकते हैं:

• मौजूदा या नए कंपोज़ेबल की झलक के लिए, स्क्रीनशॉट टेस्ट बनाने के लिए @PreviewTest का इस्तेमाल करें.
• उन कंपोज़ेबल की झलक से रेफ़रंस इमेज जनरेट करें.
• कोड में बदलाव करने के बाद, उन झलक में हुए बदलावों की पहचान करने वाली एचटीएमएल रिपोर्ट जनरेट करें.
• अपने टेस्ट को बड़े पैमाने पर करने के लिए, @Preview पैरामीटर, जैसे कि uiMode या fontScale और एक साथ कई झलक दिखाने वाले टूल (मल्टी प्रीव्यू) का इस्तेमाल करें.
• नए screenshotTest सोर्स सेट की मदद से, अपने टेस्ट को मॉड्यूल में बांटें.

पहली इमेज. उदाहरण के तौर पर दी गई एचटीएमएल रिपोर्ट.

आईडीई इंटिग्रेशन

Compose की झलक के लिए स्क्रीनशॉट टेस्टिंग टूल का इस्तेमाल करने के लिए, Gradle टास्क (updateScreenshotTest और validateScreenshotTest) को मैन्युअल तरीके से चलाया जा सकता है. हालांकि, Android Studio Otter 3 Feature Drop Canary 4 में, आईडीई के साथ पूरी तरह से इंटिग्रेशन की सुविधा उपलब्ध है. इससे आपको आईडीई में ही रेफ़रंस इमेज जनरेट करने, टेस्ट चलाने, और पुष्टि न होने की वजहों का विश्लेषण करने की सुविधा मिलती है. यहां कुछ मुख्य सुविधाओं के बारे में बताया गया है:

• एडिटर में गटर आइकॉन. अब सीधे सोर्स कोड से टेस्ट चलाए जा सकते हैं या रेफ़रंस इमेज अपडेट की जा सकती हैं @PreviewTest से एनोटेट किए गए कंपोज़ेबल और क्लास के बगल में मौजूद गटर में, हरे रंग के रन आइकॉन दिखते हैं.
  • स्क्रीनशॉट टेस्ट चलाएं. किसी एक फ़ंक्शन या पूरी क्लास के लिए टेस्ट चलाएं.
  • रेफ़रंस के लिए इमेज जोड़ें या अपडेट करें. चुने गए स्कोप के लिए, अपडेट फ़्लो को ट्रिगर करें.

• रेफ़रंस को इंटरैक्टिव तरीके से मैनेज करने की सुविधा. रेफ़रंस इमेज को अपडेट करना अब ज़्यादा सुरक्षित है. साथ ही, इसमें ज़्यादा जानकारी शामिल की जा सकती है.
  • रेफ़रंस के लिए नई इमेज जनरेट करने का डायलॉग बॉक्स. एक साथ कई Gradle टास्क चलाने के बजाय, एक नया डायलॉग बॉक्स आपको यह देखने और चुनने की सुविधा देता है कि आपको कौनसी झलक जनरेट या अपडेट करनी है.
  • वैरिएशन की झलक देखें. डायलॉग बॉक्स में, झलक के सभी वैरिएशन (जैसे, गहरे रंग वाली थीम या हल्के रंग वाली थीम या अलग-अलग डिवाइस) अलग-अलग दिखते हैं. इससे आपको इमेज जनरेट करने से पहले, कुछ आइटम चुनने या हटाने की सुविधा मिलती है.

• इंटिग्रेट किए गए टेस्ट के नतीजे और डिफ़ व्यूअर. IDE से बाहर निकले बिना नतीजे देखें.
  • यूनिफ़ाइड रन पैनल. स्क्रीनशॉट टेस्ट के नतीजे, स्टैंडर्ड Run टूल विंडो में दिखते हैं. टेस्ट को क्लास और फ़ंक्शन के हिसाब से ग्रुप किया जाता है. साथ ही, पास या फ़ेल होने की स्थिति को साफ़ तौर पर मार्क किया जाता है.
  • विज़ुअल डिफ़ टूल. जब कोई टेस्ट फ़ेल हो जाता है, तो स्क्रीनशॉट टैब की मदद से, रेफ़रंस, असल, और डिफ़ इमेज की तुलना साथ-साथ की जा सकती है.
  • ज़्यादा जानकारी वाले एट्रिब्यूट. एट्रिब्यूट टैब में, फ़ेल हुए टेस्ट का मेटाडेटा मिलता है. इसमें मैच होने का प्रतिशत, इमेज के डाइमेंशन, और इस्तेमाल किए गए प्रीव्यू टूल का कॉन्फ़िगरेशन (उदाहरण के लिए, uiMode या fontScale) शामिल होता है.

• टेस्ट के स्कोप को ज़रूरत के हिसाब से तय किया जा सकता है. अब सीधे प्रोजेक्ट व्यू से, अलग-अलग स्कोप के साथ स्क्रीनशॉट टेस्ट किए जा सकते हैं. किसी मॉड्यूल, डायरेक्ट्री, फ़ाइल या क्लास पर राइट क्लिक करें, ताकि सिर्फ़ उसके लिए स्क्रीनशॉट टेस्ट चलाए जा सकें.

ज़रूरी शर्तें

ध्यान दें: एजीपी टेस्ट सुइट की ज़रूरी शर्तों और सेटअप के निर्देशों के लिए, एजीपी टेस्ट सुइट देखें.

आईडीई के साथ पूरी तरह इंटिग्रेट करके, Compose की झलक के स्क्रीनशॉट की जांच करने की सुविधा का इस्तेमाल करने के लिए, आपके प्रोजेक्ट को ये ज़रूरी शर्तें पूरी करनी होंगी:

• Android Studio Panda 1 Canary 4 या इसके बाद का वर्शन.
• Android Gradle प्लगिन (एजीपी) का वर्शन 9.0 या इसके बाद का वर्शन.
• Compose Preview Screenshot Testing प्लगिन का वर्शन 0.0.1-alpha16 या इसके बाद का वर्शन.
• Kotlin का 2.2.10 या इसके बाद का वर्शन.
• JDK का वर्शन 17 या इसके बाद का वर्शन.
• आपके प्रोजेक्ट के लिए Compose की सुविधा चालू हो. हमारा सुझाव है कि आप Compose कंपाइलर Gradle प्लग इन का इस्तेमाल करके, Compose को चालू करें.

अगर आपको आईडीई इंटिग्रेशन के बिना, सिर्फ़ Gradle टास्क का इस्तेमाल करना है, तो ये ज़रूरी शर्तें पूरी करनी होंगी:

• Android Gradle प्लगिन (एजीपी) का वर्शन 8.5.0 या इसके बाद का वर्शन.
• Compose Preview Screenshot Testing प्लगिन का वर्शन 0.0.1-alpha16 या इसके बाद का वर्शन.
• Kotlin का 1.9.20 या इसके बाद का वर्शन. हमारा सुझाव है कि आप Kotlin 2.0 या इसके बाद के वर्शन का इस्तेमाल करें, ताकि Compose कंपाइलर Gradle प्लगिन का इस्तेमाल किया जा सके.
• JDK का वर्शन 17 या इसके बाद का वर्शन.
• आपके प्रोजेक्ट के लिए Compose की सुविधा चालू हो. हमारा सुझाव है कि आप Compose कंपाइलर Gradle प्लग इन का इस्तेमाल करके, Compose को चालू करें.

ध्यान दें: अगर Compose कंपाइलर Gradle प्लग इन का इस्तेमाल नहीं किया जा सकता, तो सीधे Compose कंपाइलर पर डिपेंडेंसी का एलान करके, Compose को चालू किया जा सकता है. पक्का करें कि आपके पास kotlinCompilerExtensionVersion का 1.5.4 या इसके बाद का वर्शन हो.

सेटअप

इंटिग्रेट किया गया टूल और Gradle टास्क, दोनों ही Compose Preview Screenshot Testing प्लग इन पर निर्भर करते हैं. प्लग इन सेट अप करने के लिए, यह तरीका अपनाएं:

1. अपने प्रोजेक्ट की gradle.properties फ़ाइल में, एक्सपेरिमेंटल प्रॉपर्टी को चालू करें.

   android.experimental.enableScreenshotTest=true
   

2. screenshotTest सोर्स सेट का इस्तेमाल करने के लिए, मॉड्यूल-लेवल की build.gradle.kts फ़ाइल के android {} ब्लॉक में, एक्सपेरिमेंट के तौर पर उपलब्ध फ़्लैग को चालू करें.

   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

इस फ़ाइल या इसी सोर्स सेट में बनाई गई अन्य फ़ाइलों में, ज़्यादा कंपोज़ेबल या झलक जोड़ी जा सकती हैं. इनमें एक साथ कई झलक दिखाने वाला टूल (मल्टी प्रीव्यू) भी शामिल है.

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 टास्क के लिए हैं.

Android का सीएलआई

Android का सीएलआई डाउनलोड करना

Compose की झलक रेंडर करने के लिए, Android का सीएलआई आज़माना

अगर Android Studio का इस्तेमाल नहीं किया जा रहा है या आपको कमांड लाइन से काम करना पसंद है, तो Android का सीएलआई आज़माएं.

उदाहरण के लिए, विज़ुअल टेस्टिंग के लिए कंपोज़ की झलक रेंडर करने के लिए, android studio render-compose-preview कमांड का इस्तेमाल करें.

android studio render-compose-preview

आईडीई में

@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) में देखें.

ध्यान दें: रेफ़रंस के लिए इस्तेमाल की जाने वाली इमेज के नाम, टेस्ट फ़ंक्शन के पूरी तरह से क्वालिफ़ाइड नाम और झलक के पैरामीटर के हैश को जोड़कर बनाए जाते हैं. उदाहरण के लिए, com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png.

टेस्ट रिपोर्ट जनरेट करना

रेफ़रंस इमेज मौजूद होने के बाद, टेस्ट रिपोर्ट जनरेट करें. इसके लिए, आईडीई इंटिग्रेशन या Gradle टास्क के लिए, इस सेक्शन में दिए गए निर्देशों का पालन करें.

आईडीई में

@PreviewTest फ़ंक्शन के बगल में मौजूद गटर आइकॉन पर क्लिक करें. इसके बाद, 'ScreenshotTests' चलाएं को चुनें.

अगर कोई टेस्ट फ़ेल हो जाता है, तो Run पैनल में टेस्ट के नाम पर क्लिक करें. इंटिग्रेट किए गए ज़ूम और पैन कंट्रोल का इस्तेमाल करके, इमेज में अंतर की जांच करने के लिए, स्क्रीनशॉट टैब को चुनें.

ध्यान दें: @PreviewTest के साथ एनोटेट किए गए किसी फ़ंक्शन का नाम बदलने पर, रेफ़रंस के लिए इस्तेमाल की जा रही मौजूदा इमेज के साथ उसका असोसिएशन टूट जाता है. ऐसे में, आपको फ़ंक्शन के नए नाम के लिए, रेफ़रंस इमेज फिर से जनरेट करनी होंगी.

Gradle टास्क की मदद से

नया स्क्रीनशॉट लेने और रेफ़रंस इमेज से उसकी तुलना करने के लिए, पुष्टि करने वाला टास्क चलाएं:

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

पुष्टि करने की प्रोसेस, {module}/build/reports/screenshotTest/preview/{variant}/index.html पर एक एचटीएमएल रिपोर्ट बनाती है.

समस्या का हल

कंपोज़ की झलक वाले स्क्रीनशॉट की जांच करने की सुविधा, होस्ट-साइड टेस्ट चलाती है. इनमें ज़्यादा मेमोरी की ज़रूरत पड़ सकती है. टेस्ट जेवीएम के लिए, हीप के साइज़ की ज़्यादा से ज़्यादा सीमा को बढ़ाया जा सकता है. इसके लिए, अपनी gradle.properties फ़ाइल में यह प्रॉपर्टी जोड़ें:

android.compose.screenshot.maxHeapSize=4g

पहले से मालूम समस्याएं

• Kotlin Multiplatform (KMP): आईडीई और इसमें मौजूद प्लगिन, दोनों को खास तौर पर Android प्रोजेक्ट के लिए डिज़ाइन किया गया है. ये KMP प्रोजेक्ट में, Android के अलावा अन्य टारगेट के साथ काम नहीं करते.

इस टूल के समस्या ट्रैकर कॉम्पोनेंट में, आपको मौजूदा समस्याओं की पूरी सूची मिल सकती है. Issue Tracker की मदद से, किसी अन्य समस्या की शिकायत करें और सुझाव/राय दें.

रिलीज़ अपडेट

रिलीज़ से जुड़े अपडेट की पूरी सूची देखने के लिए, प्रॉडक्ट की जानकारी देखें.