ساخت پلاگین نقص سفارشی

افزونه های نقص TestRail برای ادغام TestRail با ابزارهای ردیابی اشکال و اشکال شخص ثالث مفید هستند. TestRail با اسکریپت های پلاگین آماده برای ادغام با بسیاری از ابزارهای محبوب ارائه می شود. با این اوصاف، پلاگین‌های نقصی که با TestRail ارسال می‌شوند برای کار با تنظیمات استاندارد ابزارهای ردیابی نقص طراحی شده‌اند و می‌توانید افزونه‌های نقص را برای نیازهای خود سفارشی کنید.

اگر ابزار ردیابی نقص خود را سفارشی کرده اید (مثلاً با افزودن فیلدهای سفارشی مورد نیاز جدید) یا می خواهید رفتار یکپارچه سازی نقص را تغییر دهید، می توانید افزونه های نقص را سفارشی کنید یا حتی افزونه های جدیدی بسازید. سفارشی کردن پلاگین های نقص یا ساخت افزونه های جدید می تواند برای سناریوهای زیر مفید باشد:

• شما ابزار ردیابی نقص خود را طوری پیکربندی کرده‌اید که به فیلدهای سفارشی اضافی نیاز دارد و می‌خواهید آن فیلدها را به نقص فشار گفتگو
• می‌خواهید رفتار افزونه‌های نقص پیش‌فرض را تغییر دهید (به عنوان مثال اضافه کردن نقشه کاربر، افزودن اطلاعات اضافی به گزارش‌های اشکال ارسال شده، و غیره)
• شما از یک ابزار سفارشی/هنوز پشتیبانی نشده استفاده می کنید و می خواهید برای آن ابزار یکپارچه سازی کنید.

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

شروع کردن #

پلاگین های نقص در PHP توسعه داده شده اند و هنگام سفارشی سازی یا ساخت افزونه نقص خود باید درک اولیه ای از PHP داشته باشید. در صورت داشتن هر گونه سوال خاص با تیم پشتیبانی Gurock Software تماس بگیرید.

دو دایرکتوری وجود دارد که در آن TestRail به دنبال پلاگین های معیوب در هنگام اولیه سازی برنامه می گردد. دایرکتوری اول جایی است که TestRail افزونه های پیش فرض داخلی خود را نیز ذخیره می کند. شما هرگز نباید اسکریپت های افزونه را در این فهرست اضافه کنید یا تغییر دهید، زیرا این فایل ها با به روز رسانی TestRail لغو می شوند:

<TestRail>/app/plugins/defects

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

<TestRail>/custom/defects

فایل های افزونه #

افزونه نقص یک اسکریپت ساده PHP است که کلاسی را پیاده سازی می کند که توسط TestRail برای برقراری ارتباط با ابزار ردیابی نقص استفاده می شود. برای سفارشی کردن یا ایجاد پلاگین نقص خود، می توانید یک اسکریپت آماده برای استفاده را از فهرست برنامه ذکر شده در بالا در پوشه افزونه نقص سفارشی کپی کنید و نام فایل را تغییر دهید. همچنین می توانید با اسکلت اسکریپت زیر شروع کنید.

به عنوان مثال، اگر می خواهید افزونه نقص Jira TestRail را سفارشی کنید، فایل را از آن کپی کنید <TestRail>/app/plugins/defects به <TestRail>/custom/defects. همچنین باید نام فایل را تغییر دهید، زیرا TestRail از نام فایل افزونه نقص به عنوان شناسه منحصر به فرد (کلاس) آن استفاده می کند. به عنوان مثال، می توانید نام فایل را به Jira_ExampleInc.php به طوری که شامل نام سازمان شما یا نام ابزار سفارشی است که می خواهید TestRail را با آن ادغام کنید. لطفاً به بخش بعدی در مورد نحوه تنظیم نام کلاس نقص برای مطابقت با نام فایل مراجعه کنید.

اصول پلاگین #

افزونه نقص یک کلاس PHP ساده است که روش های خاصی را پیاده سازی می کند که TestRail برای برقراری ارتباط با ابزار ردیابی نقص فراخوانی می کند. TestRail از نام فایل اسکریپت به عنوان شناسه منحصر به فرد اسکریپت استفاده می کند. نام کلاس افزونه باید بر اساس نام فایل باشد. به عنوان مثال، اگر فایل اسکریپت افزونه نام دارد Jira.php، نام کلاس افزونه باید فراخوانی شود Jira_defect_plugin.

هر کلاس افزونه نقص باید TestRail را گسترش دهد Defect_plugin کلاس پایه اسکلت کلاس زیر تمام متدهای پایه را پیاده سازی می کند و متدها و آرگومان های اصلی را توضیح می دهد.

// MyPlugin.php
class MyPlugin_defect_plugin extends Defect_plugin
{
  // Get Meta
  //
  // Expected to return meta data for this plugin such as Author,
  // Version, Description and supported plugin capabilities.
  public function get_meta()
  {
  }
 
  // Validate Config
  //
  // Validates the plugin configuration that is entered in the site
  // or project settings. Expected to throw a ValidationException
  // in case the passed configuration does not validate.
  public function validate_config($config)
  {
  }
 
  // Configure
  //
  // Passes the configuration for the plugin as specified in the
  // site or project settings (as string).
  public function configure($config)
  {
  }
 
  // Prepare Push
  //
  // Signals if the plugin requires/supports a form to submit the
  // defect. Returns 'false' to signal that no form is required.
  // Otherwise the plugin should return the form description that
  // is used to render the form and display it to the user.
  public function prepare_push($context)
  {
  }
 
  // Prepare Field
  //
  // Called for each field of the push form to gather the field
  // data for the form. The plugin can return default values or
  // available options for the field (in case of a dropdown
  // box, for example), among other values.
  public function prepare_field($context, $input, $field)
  {
  }
 
  // Validate Push
  //
  // Called before the actual push attempt is processed (in case
  // the plugin uses a custom form). Useful for adding custom
  // validation functionality for the form that is not covered by
  // TestRail itself. Expected to throw a ValidationException in
  // case the passed input of the custom form does not validate.
  public function validate_push($context, $input)
  {
  }
 
  // Push
  //
  // Executes the actual push request by adding a new case to the
  // defect tracker. Expected to return the new defect ID (as
  // string or integer).
  public function push($context, $input)
  {
  }
 
  // Lookup
  //
  // Looks up the defect/issue/case with the given ID and returns
  // its properties as key/value array. The following return values
  // are required:
  // 
  // id:           The ID of the defect (usually the same as the
  //               passed ID)
  // title:        The title/summary of the defect
  // status_id:    The status ID of the defect. Possible values
  //               are:
  //               - GI_DEFECTS_STATUS_OPEN
  //               - GI_DEFECTS_STATUS_RESOLVED
  //               - GI_DEFECTS_STATUS_CLOSED
  // status:       The status as text
  // 	             
  //
  // The following properties are optional:
  //
  // url:          The full HTTP url to view the defect
  // description:  The description of the defect (supports HTML,
  //               the plugin is responsible for providing well-
  //               formed and valid HTML and must escape data
  //               that is not expected to be rendered as HTML).
  // attributes:   A key/value list of additional attributes.
  //               The value also supports HTML with the same
  //               implications as for the description.
  public function lookup($defect_id)
  {
  }
}

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

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

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

پلاگین خود را بسازید #

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

قبل از شروع کار با افزونه جدید، مهم است که توجه داشته باشیم که TestRail تمام رشته‌ها و متن‌ها را در رمزگذاری UTF-۸ انتظار دارد (و ارائه می‌کند). این بدان معنی است که تمام رشته ها و متن هایی که به TestRail برمی گردانید (یا از آن دریافت می کنید) باید در UTF-۸ کدگذاری شوند. اگر کاراکترهای غیرغربی را پردازش می کنید، این امر به ویژه وارد می شود، اما باید این را برای کاراکترهای ویژه غیر ASCII و غیره نیز در نظر بگیرید.

ایجاد فایل #

اولین قدم برای ایجاد یک افزونه نقص جدید، ایجاد فایل اسکریپت واقعی است. ما فایل را فراخوانی می کنیم Bugs.php برای این مثال و قرار دادن آن در فهرست پلاگین نقص سفارشی TestRail (<TestRail>/custom/defects). اگر قصد دارید از یک افزونه نقص موجود استفاده کنید (همه افزونه های نقص پیش فرض با کد منبع کامل ارائه می شوند و می توانید آنها را در <TestRail>/app/plugins/defects دایرکتوری)، مطمئن شوید که آن را در فهرست پلاگین نقص سفارشی کپی کرده و نام آن را تغییر دهید. پلاگین نقص اصلی ما برای Bugz به این شکل است (توجه داشته باشید که ما آن را نمی بندیم <?php تگ باز کردن در انتهای فایل؛ این یک ترفند برای جلوگیری از خطوط خالی در انتهای فایل است که ممکن است خروجی هدر PHP را خراب کند:

class Bugs_defect_plugin extends Defect_plugin
{
}

برگرداندن متا دیتا #

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

{
  return array(
    'author' => 'Example Inc.',
    'version' => '1.0',
    'description' => 'Bugs defect plugin for TestRail',
    'can_push' => false,
    'can_lookup' => false,
    'default_config' => 
      "; Please configure your Bugs connection below\n" .
      "[connection]\n" .
      "address=http:///\n" .
      "user=testrail\n" .
      "password=secret"
  );
}

به خصوص مهم هستند can_push و can_lookup خواص این ویژگی‌ها به TestRail می‌گویند که کدام قابلیت‌ها توسط افزونه نقص پیاده‌سازی می‌شوند. در حالی که فقط وجود دارد فشار دهید و جستجو در حال حاضر، این امکان وجود دارد که قابلیت‌های جدیدی در نسخه‌های آتی TestRail اضافه شود.

را default_config ملک نیز در اینجا جالب است. پلاگین های نقص را می توان به صورت جهانی در TestRail در زیر پیکربندی کرد اداره > تنظیمات سایت یا در هر پروژه تحت اداره > پروژه ها. هنگامی که یک مدیر یک افزونه را پیکربندی می کند، پیکربندی پیش فرض همانطور که در آن مشخص شده است default_config در قسمت متن پیکربندی بارگذاری می شود.

پیکربندی #

یک افزونه نقص معمولاً به برخی تنظیمات پیکربندی مانند آدرس ردیاب نقص، نام کاربری و رمز عبور و گزینه های مشابه نیاز دارد. هنگامی که یک مدیر یک افزونه نقص را در TestRail پیکربندی می کند، یک فیلد متنی برای وارد کردن تنظیمات پیکربندی استفاده می شود. این به افزونه ها اجازه می دهد تا از قالب پیکربندی خود استفاده کنند، زیرا یک فیلد متنی از نمادهای مختلف (مانند گزینه های INI، XML و غیره) پشتیبانی می کند.

افزونه‌های نقص پیش‌فرض TestRail از نماد فایل INI برای تنظیمات پیکربندی استفاده می‌کنند، بنابراین [sections] و name=value جفت ها برای تعیین تنظیمات استفاده می شوند. از آنجایی که TestRail دارای روش هایی برای خواندن چنین گزینه های پیکربندی است، معمولاً استفاده از نماد INI ایده خوبی است.

هنگامی که یک مدیر یک افزونه را پیکربندی می کند، TestRail از افزونه می خواهد تنظیمات پیکربندی وارد شده را تأیید کند. از آنجایی که TestRail در مورد تنظیمات پیکربندی مورد نیاز (یا حتی فرمت تنظیمات پیکربندی) اطلاعی ندارد، افزونه نقص باید تأیید کند که تمام تنظیمات مورد نیاز مشخص شده است. برای انجام این کار، TestRail را فراخوانی می کند validate_config هر زمان که مدیر سعی می کند پیکربندی را تغییر دهد روش:

public function validate_config($config)
{
  $ini = ini::parse($config);
 
  // Check if the [connection] section exists
  if (!isset($ini['connection']))
  {
    throw new ValidationException('Missing [connection] group');
  }
 
  // Check if the required values exist
  $keys = array('address', 'user', 'password');
  foreach ($keys as $key)
  {
    if (!isset($ini['connection'][$key]) ||
      !$ini['connection'][$key])
    {
      throw new ValidationException(
        "Missing configuration for key '$key'"
      );
    }
  }
 
  $address = $ini['connection']['address'];
 
  // Check whether the address is a valid url (syntax only)
  if (!check::url($address))
  {
    throw new ValidationException('Address is not a valid url');
  }
}

روش بالا بررسی می کند که [connection] بخش وجود دارد و این بخش حاوی کلیدها است address، user و password. همچنین تأیید می کند که کلید آدرس حاوی یک URL معتبر است (از طریق check::url روتین). همچنین به نحوه عملکرد TestRail توجه کنید ini ماژول برای تجزیه تنظیمات پیکربندی در ابتدای روش استفاده می شود. اگر روش مشکلی در پیکربندی پیدا کند (مانند یک کلید گم شده یا یک مقدار نامعتبر)، یک استثنا از نوع ایجاد می کند. ValidationException. TestRail سپس پیام خطا را به مدیر نمایش می دهد.

پس از پیکربندی تنظیمات، افزونه به راهی برای دسترسی به تنظیمات نیاز دارد. TestRail به طور خودکار با آن تماس می گیرد configure روش هر بار که کلاس نقص در حال نمونه سازی است. به عنوان مثال، قبل از اینکه TestRail از یک افزونه نقص بخواهد شناسه نقص را جستجو کند، آن را فراخوانی می کند configure روشی برای ارائه افزونه با تمام تنظیمات پیکربندی لازم. این افزونه مسئول نگه داشتن این تنظیمات تا زمانی است که نمونه فعال است تا برای تماس های متد واقعی به این تنظیمات دسترسی داشته باشد. یک افزونه معمولاً تنظیمات را در یک متغیر نمونه ذخیره می کند تا این کار را انجام دهد:

public function configure($config)
{
  $ini = ini::parse($config);
  $this->_address = str::slash($ini['connection']['address']);
  $this->_user = $ini['connection']['user'];
  $this->_password = $ini['connection']['password'];	
}

این روش تنظیمات پیکربندی را از طریق ini دوباره ماژول و تنظیمات پیکربندی را در متغیرها/فیلدهای نمونه ذخیره می کند. برای دسترسی به آدرس ردیاب نقص در فراخوانی‌های متد بعدی، افزونه می‌تواند به سادگی دسترسی داشته باشد $this→_address.

جستجوی عیوب #

ابتدا به بررسی عملکرد جستجوی نقص می پردازیم زیرا پیاده سازی آن نسبت به عملکرد نقص فشاری ساده تر است و راه خوبی برای آشنایی بیشتر با نحوه عملکرد افزونه های نقص است. وقتی TestRail یک شناسه نقص وارد شده را ارائه می کند (مثلاً به عنوان بخشی از نتیجه آزمایش)، بررسی می کند که آیا افزونه نقص پیکربندی شده (در صورت وجود) از جستجوی نقص پشتیبانی می کند (با بررسی can_lookup گزینه برگردانده شده توسط get_meta).

اگر افزونه از قابلیت جستجو پشتیبانی می‌کند، کاربران می‌توانند نشانگر ماوس خود را روی شناسه نقص نگه دارند تا درباره وضعیت و توضیحات نقص اطلاعات بیشتری کسب کنند. هر زمان که کاربر این کار را انجام می دهد، TestRail از افزونه نقص می خواهد که اطلاعات مربوط به نقص را بازیابی کند تا TestRail بتواند داده ها را نمایش دهد (مفید است بدانید که TestRail ممکن است در آینده از این اطلاعات برای اهداف دیگری مانند محاسبه عیوب باز/بسته شده برای گزارش استفاده کند).

درخواست اطلاعات در مورد یک نقص از طریق انجام می شود lookup روش قبل از فراخوانی این متد، TestRail همیشه the را فراخوانی می کند configure روشی که افزونه تمام تنظیمات پیکربندی لازم را داشته باشد. را lookup روش برای ردیاب نقص خیالی ما اشکالات به نظر می رسد این است:

public function lookup($defect_id)
{
  // Get the defect information via the Bugs API
  $defect = $this->_bugs_get_defect($defect_id);
 
  // Build the status_id based on the status property
  if ($defect['status'] == 'Open')
  {
    $status_id = GI_DEFECTS_STATUS_OPEN;
  }
  elseif ($defect['status'] == 'Resolved')
  {
    $status_id = GI_DEFECTS_STATUS_RESOLVED;
  }
  else
  {
    $status_id = GI_DEFECTS_STATUS_CLOSED;
  }
 
  // Build the bug URL and project link
  $bug_url = str::format('{0}?bug={1}', 
    $this->_address,
    $defect['id']);
  $project_link = str::format(
    '{2}',
    a($this->_address),
    a($defect['project_id']),
    h($defect['project']));
 
  // Build the description
  $description = str::format(
    '{0}',
    nl2br(
      html::link_urls(
        h($defect['description'])
      )
    )
  );	
 
  // Return the defect details
  return array(
    'id' => $defect['id'],
    'title' => $defect['title'],
    'status_id' => $status_id,
    'status' => $defect['status'],
    'url' => $bug_url,
    'description' => $description,
    'attributes' => array(
      'Type' => h($defect['type']),
      'Status' => h($defect['status']),
      'Project' => $project_link
    )
  );
}

این روش کمی طولانی‌تر از سایر پیاده‌سازی‌های متد است که تاکنون دیده‌ایم، بنابراین بیایید نگاهی به مراحل جداگانه‌ای که متد انجام می‌دهد بیاندازیم. ابتدا با تماس با داخلی/خصوصی جزئیات نقص را دریافت می کنیم _bugs_get_defect روش این یا یک روش مشابه معمولاً API ردیاب نقص را فراخوانی می کند یا اطلاعات نقص را در پایگاه داده جستجو می کند. اگر کد منبع این نمونه پلاگین را در زیر دانلود کنید، متوجه خواهید شد که این روش به سادگی تمام جزئیات نقص را کدگذاری می کند و در واقع هیچ تماسی از سرویس وب برقرار نمی کند، اما این برای اهداف نمایشی به خوبی کار می کند.

سپس چند مقدار را برای TestRail آماده می کنیم مانند the status_id یا لینک ها و توضیحات را status_id به TestRail می گوید که آیا نقصی باز است، برطرف شده است یا بسته شده است. اگر یک ردیاب نقص بین حل شده و بسته تمایز قائل نمی شود (مثلاً یک باگ یا باز شده یا برطرف شده است)، مطمئن شوید که GI_DEFECTS_STATUS_CLOSED وضعیت TestRail ممکن است از status_id برای گزارش ها و سایر عملکردها در آینده.

برخی از فیلدهایی که lookup روش از HTML پشتیبانی می کند. این بدان معنی است که بسیار مهم است که از رشته ها و مقادیر خود قبل از بازگرداندن آنها به TestRail فرار کنید (در صورتی که داده ها را به عنوان HTML معتبر از ردیاب نقص خود دریافت نکرده باشید). اگر این کار را انجام ندهید، خطر حملات اسکریپت متقابل سایت (XSS) وجود دارد و این یک خطر امنیتی بالقوه است. برای فرار از یک رشته، TestRail را ارائه می دهد h() و a() روال هایی برای فرار از متون و ویژگی های برچسب، به ترتیب. برای مثال، ویژگی‌های برگشتی می‌توانند حاوی کد HTML (مانند پیوندها) باشند و اگر از مقادیری مانند نام پروژه فرار نکنید، TestRail آن‌ها را همانطور که هست ارائه می‌کند و مهاجم می‌تواند کد جاوا اسکریپت را از طریق نام پروژه تزریق کند. همچنین توجه کنید که این روش چگونه توضیحات باگ را در a قرار می دهد div برای قالب بندی توضیحات با فونت تک فاصله تگ کنید.

آخرین اما نه کم اهمیت، این روش جزئیات نقص را به TestRail برمی گرداند. علاوه بر جزئیاتی مانند شناسه نقص، عنوان، وضعیت و غیره، امکان بازگرداندن ویژگی ها و توضیحات نیز وجود دارد. ویژگی ها می توانند شامل اطلاعاتی مانند پروژه، نوع موضوع، جزء یا منطقه پروژه باشند. دقیقاً مانند ویژگی ها، توضیحات از HTML پشتیبانی می کند و بنابراین می توان از آن برای افزودن انواع اطلاعات اضافی استفاده کرد. لطفاً مطمئن شوید که تمام HTML بازگشتی حاوی برچسب‌ها و قالب‌بندی معتبر هستند، زیرا تگ‌های HTML شکسته می‌توانند طرح‌بندی و عملکرد TestRail را خراب کنند. اسکرین شات زیر نشان می دهد که چگونه TestRail جزئیات نقص برگشتی را ارائه می دهد (توجه کنید که چگونه ویژگی ها در بالای توضیحات با پس زمینه آبی نمایش داده می شوند).

فشار دادن عیوب بدون دیالوگ #

بیایید نگاهی به ارسال گزارش‌های نقص از TestRail به ابزار ردیابی نقص بیندازیم. ابتدا عملکرد فشار را بدون دیالوگ فشار اجرا می کنیم و در بخش بعدی به سناریوی پیچیده تر با یک گفتگوی فشاری نگاهی خواهیم انداخت. دو روش وجود دارد که برای اجرای عملکرد فشار بدون دیالوگ فشار برای ما مرتبط است: prepare_push و push. TestRail را فرا می خواند prepare_push روشی برای درخواست اطلاعات در مورد گفتگو و فیلدهای موجود که باید ارائه شود. اگر به یک گفتگوی فشاری نیازی نداریم و فقط می‌خواهیم گزارش اشکال را بدون تعامل کاربر ارسال کنیم، به سادگی false را در اینجا برمی‌گردانیم:

public function prepare_push($context)
{
  return false;
}

برای فشار واقعی نقص، ما همچنین باید روش فشار را پیاده سازی کنیم. اکنون، برای ایجاد یک گزارش نقص مفید، مطمئناً باید اطلاعاتی در تست‌کیس (مانند عنوان پرونده یا نظر وارد شده) و شاید جزئیات دیگری مانند شخصی که نقص را انجام می دهد، داشته باشیم. اینجاست که $context استدلالی که به همه روش های مربوط به فشار ارسال می شود مفید است. را $context استدلال با بسیاری از اطلاعات زمینه مفید مانند جزئیات تست‌کیس، آزمون، شخصی که نقص را تحت فشار قرار می دهد و غیره ارائه می شود. بیایید نگاهی به برخی از اطلاعاتی که از طریق آن منتقل می شود بیندازیم $context استدلال:

Array
(
    [event] => push
    [tests] => Array
        (
            [0] => stdClass Object
                (
                    [id] => 12
                    [run_id] => 1
                    [case_id] => 128
                    [status_id] => 1
                    [url] => http://testrail/index.php?/tests/view/12
                    [case] => stdClass Object
                        (
                            [id] => 128
                            
Lorem ipsum dolor sit amet... #
 => Verify CSV import with enclosed test data files
                            [url] => http://testrail/index.php?/cases/view/128
                        )

                    [run] => stdClass Object
                        (
                            [id] => 1
                            [name] => File Formats
                            [config] => 
                            [plan_id] => 
                            [project_id] => 1
                            [url] => http://testrail/index.php?/runs/view/1
                        )

                )

        )

    [test_count] => 1
    [test_change] => stdClass Object
        (
            [status_id] => 1
            [assignedto] => 
            [comment] => Importing our standard Unicode CSV file (unitest1.csv) failed with the error message `Could not detect file encoding`.
            [attachments] => 
            [version] => 
            [elapsed] => 
            [defects] => 
        )

    [project] => stdClass Object
        (
            [id] => 1
            [name] => Datahub
            [url] => http://testrail/index.php?/projects/overview/1
        )

    [preferences] => Array
        (
            [type] => 1
            [project] => DH
            [component] => 10010
        )

    [user] => stdClass Object
        (
            [id] => 2
            [name] => ..
            [email] => test@example.com
        )

)

همانطور که می بینیم، TestRail جزئیات مربوط به تست(های) انتخابی، تست‌کیس‌ها مرتبط، پروژه، تغییرات تست (یعنی اطلاعاتی که کاربر در آن وارد کرده است را ارائه می دهد. اضافه کردن نتیجه تست گفتگو) و غیره همانطور که از ساختار داده می بینید، تست های متعددی وجود دارد که TestRail به افزونه نقص ارسال می کند. TestRail چندین رکورد تست را به اسکریپت ارسال می کند اگر کاربر چندین تست را انتخاب کرده و از آن استفاده کند اضافه کردن نتیجه تست دکمه ای برای اضافه کردن یک نتیجه به تمام آن تست ها به طور همزمان (یک دکمه اقدام انبوه). فشار دادن نقص و برگرداندن شناسه نقص جدید می تواند به شکل زیر باشد:

public function push($context, $input)
{
  // Build the summary/title
  $test = current($context['tests']);
  $summary = 'Failed test: ' . $test->case->title;
 
  if ($context['test_count'] > 1)
  {
    $summary .= ' (+others)';
  }	
 
  // Build the comment (based on the test result comment
  // and links/URLs of the tests
  if ($context['test_change']->comment)
  {
    $comment = $context['test_change']->comment;
    $comment .= "\n";
  }
  else 
  {
    $comment = '';
  }
 
  $tests = $context['tests'];
  foreach ($tests as $test)
  {
    $comment .= "\nTest: ";
    $comment .= $test->case->title;
    $comment .= "\n";
    $comment .= $test->url;
  }
 
  // We hard code a few other details here for demonstration
  // purposes. We could also select these attributes based
  // on context information such as the test suite or user
  $project = $context['project']->name;
  $type = 'Bug';
  $component = '(default)';
 
  // Push the defect and return the new defect ID
  $defect_id = $this->_bugs_push_defect(
    $summary,
    $comment,
    $project,
    $type,
    $component
  );
  return $defect_id;
}

را push متد عنوان/خلاصه و نظر گزارش اشکال را بر اساس نتیجه تست وارد شده و اطلاعات زمینه ایجاد می کند. سپس داخلی را فرا می خواند _bugs_push_defect روش ارسال گزارش اشکال واقعی این روش فراخوانی واقعی یک API سرویس وب یا نوشتن گزارش اشکال در پایگاه داده را اجرا می کند. ما فقط باید شناسه نقص جدید را به TestRail برگردانیم که شناسه را به آن اضافه می کند نقص زمینه برای ما

فشار دادن عیوب با دیالوگ #

بعد از اینکه ساختن یک افزونه نقص را بررسی کردیم که می تواند گزارش های باگ را بدون هیچ گونه تعامل کاربر ارسال کند، می خواهیم افزونه را برای استفاده از یک به روز رسانی کنیم. نقص فشار گفتگو آزمایش‌کننده‌ها می‌توانند با استفاده از این گفتگو، توضیحات باگ را تغییر دهند یا پروژه دیگری را هنگام فشار دادن نقص به ردیاب نقص انتخاب کنند. اولین چیزی که باید تغییر دهیم به روز رسانی است prepare_push روش به جای برگشتن false برای نشان دادن اینکه ما نیازی به گفتگو نداریم، می‌توانیم طرحی از فرم را به این شکل برگردانیم:

public function prepare_push($context)
{
  // Return a form with the following fields/properties
  return array(
    'fields' => array(
      'summary' => array(
        'type' => 'string',
        'label' => 'Summary',
        'required' => true,
        'size' => 'full'
      ),
      'type' => array(
        'type' => 'dropdown',
        'label' => 'Issue Type',
        'required' => true,
        'remember' => true,
        'size' => 'compact'
      ),
      'project' => array(
        'type' => 'dropdown',
        'label' => 'Project',
        'required' => true,
        'remember' => true,
        'cascading' => true,
        'size' => 'compact'
      ),
      'component' => array(
        'type' => 'dropdown',
        'label' => 'Component',
        'required' => true,
        'remember' => true,
        'depends_on' => 'project',
        'size' => 'compact'
      ),
      'description' => array(
        'type' => 'text',
        'label' => 'Description'
      )
    )
  );
}

طرح فرم به TestRail می گوید که به کدام فیلدهای فرم نیاز داریم. اسکریپت نقص در واقع نباید خود دیالوگ را رندر کند، زیرا TestRail به طور خودکار دیالوگ فشار را برای ما بر اساس طرح فرمی که در ما برمی‌گردانیم ارائه می‌کند. prepare_push روش بیشتر طرحواره فرمی که با مثال بالا بازگردانده شده است باید خود توضیحی باشد. ما لیستی از فیلدهای فرم را که TestRail باید نمایش دهد، برمی گردانیم.

کلید آرایه (به عنوان مثال “توضیح”) یک فیلد نامی است که TestRail برای ارسال داده های ورودی به اسکریپت ما استفاده می کند. را نوع از زمینه در حال حاضر می تواند یکی از text، dropdown یا string و به TestRail می گوید که ما به چه نوع زمینه ای نیاز داریم. الف string یک عنصر ورودی متن تک خطی است، در حالی که text می تواند چندین خط ورودی را بپذیرد. را مورد نیاز است گزینه مشخص می کند که آیا فیلد باید توسط کاربر وارد شود یا اینکه اختیاری است و برچسب نحوه فراخوانی فیلد در دیالوگ را مشخص می کند.

را اندازه گزینه عرض فیلد را مشخص می کند، جایی که full منجر به فیلدی می شود که تمام عرض افقی یک گفتگو را پر می کند. اگر مشخص کنید compact به عنوان اندازه فیلد، TestRail سعی می کند چندین فیلد فشرده را در یک خط نمایش دهد (این فقط برای فیلدهای فشرده که در طرح فرم با هم مشخص شده اند صادق است). اگر مشخص کنید به یاد داشته باشید گزینه، TestRail آخرین مقدار وارد شده از یک مقدار را برای پروژه TestRail فعلی ذخیره می کند. این امر به خاطر سپردن مقادیر فرم قبلاً وارد شده (مانند ناحیه پروژه یا جزء فرعی) را آسان می کند تا کاربر مجبور نباشد بارها و بارها همان داده ها را وارد کند. در ادامه این بخش نگاهی به نحوه عملکرد آن خواهیم داشت.

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

اکنون که طرح فرم را مشخص کرده‌ایم، باید مقادیر کشویی معتبر و متون پیش‌فرض فیلدهای گفتگو را نیز به TestRail بگوییم. این را می توان از طریق انجام داد prepare_field روش هر زمان که TestRail دیالوگ را مقداردهی اولیه می کند یا اگر فیلدهای آبشاری تغییر کند، TestRail از افزونه نقص می خواهد که اطلاعات مربوط به فیلدهای مربوطه را ارائه دهد. TestRail را فرا می خواند prepare_field روش برای هر زمینه TestRail به اطلاعات نیاز دارد.

public function prepare_field($context, $input, $field)
{
  $data = array();
 
  // Take the preferences of the user into account, but only
  // for the initial form rendering (not for cascading loads).
  if ($context['event'] == 'prepare')
  {
    $prefs = arr::get($context, 'preferences');
  }
  else
  {
    $prefs = null;
  }
 
  // And then build the options and default values for the
  // form fields and return them.
  switch ($field)
  {
    case 'summary':
      $data['default'] = 
        $this->_get_summary_default($context);
      break;
 
    case 'description':
      $data['default'] = 
        $this->_get_description_default($context);
      break;
 
    case 'type':
      $data['options'] = $this->_bugs_get_types();
 
      // Select the stored preference or the first item in
      // the list otherwise.
      $default = arr::get($prefs, 'type');
      if ($default)
      {
        $data['default'] = $default;
      }
      else
      {
        if ($data['options'])
        {
          $data['default'] = key($data['options']);
        }
      }				
      break;
 
    case 'project':
      $data['default'] = arr::get($prefs, 'project');
      $data['options'] = $this->_bugs_get_projects();
      break;
 
    case 'component':
      if (isset($input['project']))
      {
        $data['default'] = arr::get($prefs, 'component');
        $data['options'] = $this->_bugs_get_components(
          $input['project']);
      }
      break;
  }
 
  return $data;
}

TestRail سه آرگومان را به ما ارسال می کند prepare_field روش: $context آرگومان حاوی اطلاعات زمینه ای است که از روش های قبلی می دانیم. را $input آرایه حاوی داده های واقعی است که کاربر در محاوره فشار وارد کرده است (این به ویژه برای تماس های کشویی آبشاری مفید است). را $field آرگومان حاوی نام فیلدی است که متد برای آن فراخوانی شده است (همانطور که متد برای فیلدهای ما به طور جداگانه فراخوانی می شود).

TestRail همچنین ترجیحات کاربر فعلی (برای پروژه فعلی) را به عنوان بخشی از آن ارسال می کند $context استدلال بنابراین اولین چیزی که ما prepare_field اگر TestRail در حال حاضر گفتگو را مقداردهی اولیه می کند، روش انجام می دهد که تنظیمات برگزیده کاربر را در یک متغیر محلی کپی می کند. اگر این یک فراخوان بعدی برای یک فیلد کشویی آبشاری باشد، ترجیحات را نادیده می گیریم.

سپس داده های مناسب فیلد را به TestRail برمی گردانیم. ما این کار را در یک دستور سوئیچ بزرگ انجام می دهیم که اساساً کد مربوطه را بسته به فیلدی که TestRail برای آن درخواست داده است، اجرا می کند.

به عنوان مثال، وقتی TestRail مقادیر ممکن را برای the می‌پرسد پروژه در فیلد، کد زیر اجرا می شود:

case 'project':
  $data['default'] = arr::get($prefs, 'project');
  $data['options'] = $this->_bugs_get_projects();
  break;

TestRail اساساً به دو جزئیات در مورد یک فیلد کشویی نیاز دارد: گزینه های احتمالی که کاربر می تواند انتخاب کند و گزینه پیش فرضی که انتخاب شده است. برای فیلدهای متن و رشته، فقط پیش فرض مقدار باید مشخص شود (هیچ گزینه ای وجود ندارد که کاربر بتواند از میان یک فیلد متن یا رشته انتخاب کند). در مثال ما، گزینه پیش فرض بر اساس ترجیح کاربر انتخاب می شود. بنابراین اگر کاربری قبلاً پروژه خاصی را انتخاب کرده است، ما این پروژه را بازیابی می کنیم تا کاربر مجبور نباشد دوباره پروژه را مشخص کند. به طور مشابه، ما متن‌های پیش‌فرض را برای خلاصه/عنوان و قسمت توضیحات بر اساس جزئیات تست تولید می‌کنیم. بنابراین گفتگوی ما شبیه به تصویر زیر خواهد بود.

در مثال ما، ما واقعاً به طور کامل روش هایی مانند _bugs_get_projects. در یک افزونه کاملاً کاربردی، این روش از API وب سرویس ردیاب نقص برای دریافت لیستی از پروژه ها استفاده می کند (یا فهرستی از پروژه ها را از پایگاه داده می خواند). در مورد ما، ما به سادگی فهرستی از پروژه‌ها با کد سخت را برمی‌گردانیم (اگر پروژه‌های شما مرتباً تغییر نمی‌کنند، این نیز می‌تواند یک روش معتبر برای اجرای آن باشد):

private function _bugs_get_projects()
{
  return array(
    'dh' => 'Datahub',
    'pr' => 'Presenter',
    'wr' => 'Writer'
  );
}

توجه کنید که چگونه از شناسه ها به عنوان کلیدهای آرایه در اینجا استفاده می کنیم. TestRail زمانی که کاربر روی دکمه ارسال کلیک می کند، آن شناسه ها را به عنوان مقدار ورودی به روش فشار ما ارسال می کند. اما قبل از اجرای روش فشار، اجازه دهید به طور خلاصه به آن نگاه کنیم validate_push روش این روش به ما اجازه می دهد تا قبل از پذیرش مقادیر وارد شده برای گزارش اشکال، ورودی کاربر را تأیید کنیم. اگر نیازی به اعتبارسنجی بیشتر داده‌ها ندارید، پیاده‌سازی این روش ضروری نیست، اما برای اعمال فرمت‌ها یا محدودیت‌های ورودی خاص (مانند تاریخ‌ها و غیره) می‌تواند مفید باشد. مثال زیر از validate_push روش محدود کردن تعداد کاراکترها در قسمت خلاصه به ۱۰۰ کاراکتر:

public function validate_push($context, $input) 
{ 
  if (isset($input['summary'])) 
  { 
    if (str::len($input['summary']) > 100) 
    { 
      throw new ValidationException( 'Field Summary cannot exceed 100 characters.'); 
    } 
  } 
}

هنگامی که کاربر گزارش اشکال را وارد کرد، روی دکمه ارسال کلیک کرده و اسکریپت ورودی را از طریق validate_push روش، TestRail را فراخوانی می کند push روش ارسال گزارش اشکال مشابه مثال ما بدون گفتگو در بالا، ما push روش گزارش را ارسال می کند. توجه داشته باشید که چگونه از آن استفاده می کنیم $input استدلال این بار به جای ساختن گزارش اشکال از $context خودمان استدلال کنیم:

public function push($context, $input)
{
  // Push the defect and return the new defect ID
  $defect_id = $this->_bugs_push_defect(
    $input['summary'],
    $input['description'],
    $input['project'],
    $input['type'],
    $input['component']
  );
  return $defect_id;
}

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

دانلود کنید #

می توانید نمونه کامل اسکریپت مورد بحث در این مقاله را از اینجا دانلود کنید:

برای مشاهده نمونه‌های بیشتر از افزونه‌های نقص واقعی، توصیه می‌شود به پلاگین‌های نقصی که با TestRail ارسال می‌شوند نگاهی بیندازید. می توانید پلاگین های نقص را در فهرست راهنمای نصب TestRail خود در زیر پیدا کنید app/plugins/defects. اگر سؤال دیگری در مورد ساخت یا سفارشی کردن افزونه های نقص دارید، لطفاً دریغ نکنید با ما تماس بگیرید.