प्रलेखन को कैसे पुनर्जीवित करें?

शायद हर दर्द इस दर्द को जानता है - अप्रासंगिक दस्तावेज। कोई फर्क नहीं पड़ता कि टीम कितनी मेहनत करती है, आधुनिक परियोजनाओं में हम इतनी बार जारी करेंगे कि सभी परिवर्तनों का वर्णन करना लगभग असंभव है। हमारी परीक्षण टीम, सिस्टम विश्लेषकों के साथ मिलकर, हमारी परियोजना प्रलेखन को पुनर्जीवित करने का प्रयास करने का निर्णय लिया।



अल्फा-बैंक की वेब परियोजनाएं अकिता परीक्षण स्वचालन ढांचे का उपयोग करती हैं, जिसका उपयोग बीडीडी लिपियों के लिए किया जाता है। आज तक, इसकी कम प्रवेश सीमा, उपयोगिता और लेआउट का परीक्षण करने की क्षमता के कारण ढांचे को बहुत लोकप्रियता मिली है। लेकिन हमने आगे जाने का फैसला किया - प्रलेखन उत्पन्न करने के लिए वर्णित परीक्षण परिदृश्यों के आधार पर, जिससे विश्लेषकों को दस्तावेज़ीकरण को अपडेट करने की अनन्त समस्या पर होने वाले समय में बहुत कमी आती है।

वास्तव में, एक साथ अकिता के साथ, एक डॉक्यूमेंटेशन जेनरेशन प्लग-इन का उपयोग पहले से ही किया गया था, जो स्क्रिप्ट में चरणों के माध्यम से चला गया और उन्हें HTML प्रारूप में अपलोड कर दिया, लेकिन इस दस्तावेज़ को लोकप्रिय बनाने के लिए हमें इसे जोड़ने की आवश्यकता थी:

• स्क्रीनशॉट;
• चर के मान (कॉन्फ़िगर फ़ाइल, उपयोगकर्ता खाते, आदि);
• स्थिति और क्वेरी पैरामीटर।

हमने अपने मौजूदा प्लग-इन पर ध्यान दिया, जो वास्तव में, एक स्थिर विश्लेषक था और .feature फ़ाइलों में वर्णित लिपियों के आधार पर उत्पन्न दस्तावेज। हमने वक्ताओं को जोड़ने का फैसला किया, और प्लग-इन को प्लग-इन की तरह न बनाने के लिए, हमने अपना लिखने का फैसला किया।

सबसे पहले, हमने यह पता लगाने का फैसला किया कि हम फीचर फ़ाइलों से परीक्षण स्क्रिप्ट में उपयोग किए जाने वाले स्क्रीनशॉट और मानों को कैसे एकत्र कर सकते हैं। सब कुछ काफी सरल निकला। प्रत्येक सुविधा फ़ाइल के लिए परीक्षण चलाते समय ककड़ी, एक अलग ककड़ी बनाता है।

इस फ़ाइल के अंदर निम्नलिखित वस्तुएँ हैं:


टेस्ट केस का नाम और कीवर्ड:


तत्वों की सारणियाँ - लिपियाँ और स्वयं चरण:


आउटपुट फ़ील्ड में अतिरिक्त जानकारी होती है, उदाहरण के लिए, चर - पते, लिंक, उपयोगकर्ता खाते, आदि।


एम्बेडिंग में स्क्रीनशॉट होते हैं जो सेलेनियम परीक्षणों के दौरान लेता है:


इस प्रकार, हमें बस cucumber.json फ़ाइलों के माध्यम से जाने की ज़रूरत है, परीक्षण सूट, परीक्षण स्क्रिप्ट के नाम एकत्र करना, चरणों को बाहर निकालना, अतिरिक्त जानकारी और स्क्रीनशॉट एकत्र करना।

पृष्ठभूमि में या एक विशिष्ट कार्रवाई के लिए अनुरोधों को प्रदर्शित करने के लिए प्रलेखन के लिए, हमें अपने सामने के डेवलपर्स से मदद मांगनी थी। प्रॉक्सी की मदद से, हम ट्रेसआईडी को पकड़ने में सक्षम थे, जो फ्रंट-एंड सेवा अनुरोध उत्पन्न करते हैं। एक ही ट्रेसआईड द्वारा, लॉग को लोचदार में लिखा जाता है, जहां से हम परीक्षण रिपोर्ट और प्रलेखन में सभी आवश्यक क्वेरी पैरामीटर खींचते हैं।

नतीजतन, हमें एसिसीडोक प्रारूप में एक फ़ाइल मिली - एक सुविधाजनक फ़ाइल प्रारूप, मार्कटाउन एनालॉग की तुलना में थोड़ा अधिक जटिल है, लेकिन इसमें बहुत अधिक स्वरूपण विकल्प हैं (आप एक छवि या तालिका सम्मिलित कर सकते हैं, जो मार्कडाउन में नहीं किया जा सकता है)।

परिणामी Asciidoc को अन्य स्वरूपों में बदलने के लिए, हम Ascii doctorj का उपयोग करते हैं, जो AsciiDoctor Java टूल का आधिकारिक संस्करण है। परिणामस्वरूप, हमें HTML प्रारूप में तैयार किए गए दस्तावेज़ मिलते हैं, जिन्हें संगम में डाउनलोड किया जा सकता है, किसी सहकर्मी को भेजा जा सकता है या भंडार में डाला जा सकता है।

कैसे कनेक्ट करें?

अब, अपने प्रोजेक्ट के लिए फ्रंट-एंड डॉक्यूमेंटेशन जेनरेट करने के लिए, आपको सिर्फ डॉक्यूमेंटेशन प्लग इन को कनेक्ट करना होगा और सभी टेस्ट रन करने के बाद adoc कमांड को रन करना adoc ।

हम क्या सुधार करना चाहते हैं?

1. कॉन्फ़िगर करने योग्य तकनीकी चरण जोड़ें।
   प्लगइन के वर्तमान संस्करण में चरण हैं "और एक स्क्रीनशॉट लिया गया था ..."। इस तरह के कदम दस्तावेज़ीकरण के लिए शब्दार्थ भार नहीं रखते हैं, और हम उन्हें छिपाना चाहते हैं। अब हमने उन्हें प्लगइन के अंदर सीवन कर दिया है, और उन्हें छोड़ दिया गया है, लेकिन एक खामी है - इस कदम के प्रत्येक जोड़ से इस तथ्य की ओर बढ़ जाता है कि हमें प्लगइन का एक नया संस्करण बनाने की आवश्यकता है। इससे दूर होने के लिए, हम कॉन्फ़िगरेशन फ़ाइल में ऐसे चरणों को स्थानांतरित करने की योजना बनाते हैं और उन चरणों को लिखते हैं जिन्हें हम स्क्रिप्ट में नहीं देखना चाहते हैं।
2. एक खुला खट्टा प्लगइन बनाओ।

हमारे कार्यान्वयन के लिए कौन सी टीमें उपयुक्त हैं?

• ककड़ी (या एक समान रूपरेखा) का उपयोग करें;
• सामने और ज्ञान के आधार के लिए अप-टू-डेट प्रलेखन करना चाहते हैं;
• वे विश्लेषकों को परीक्षण में संलग्न करना चाहते हैं।

परिणाम:

कई टीमों पर पायलट ने दिखाया कि जिस प्लगइन की मदद से हम प्रलेखन को अद्यतित रखने का प्रबंधन करते हैं, विश्लेषकों को अब इसे बनाए रखने में खर्च करने की आवश्यकता नहीं है। इसके अलावा, इस सुविधा के कार्यान्वयन ने हमें टीमों के भीतर पूर्ण रूप से विकसित BDD को लागू करने के बारे में सोचना चाहिए। आज हम एक प्रयोग कर रहे हैं - विश्लेषकों ने ग्राहक के लिए एक सकारात्मक मार्ग तैयार किया, अकिता बीडीडी चरणों, परीक्षकों का उपयोग करके व्यावसायिक प्रतिबंधों का संकेत दिया, बदले में, इन परिदृश्यों के लिए कस्टम कदम और अतिरिक्त जांच लिखें।

वैसे, होलीवर के बारे में, बीडीडी की जरूरत है या नहीं, सोमवार को हम एक विशेष बैठक करेंगे ।