TestRail این امکان را فراهم میکند که رابط کاربری را با استفاده از UI Scripts سفارشی کنید. UI Scripts ابزاری بسیار انعطافپذیر برای ادمینها است تا با نوشتن کد استاندارد JavaScript و تعریف stylesheetهای ساده، بخشهایی از ظاهر و رفتار TestRail را تغییر دهند.
UI Scripts را میتوان روی یک صفحه، چند صفحه یا حتی کل application اعمال کرد. برای نوشتن UI Script به محیط توسعه یا framework خاصی نیاز ندارید، چون میتوانید scriptها را مستقیم در TestRail تعریف و تست کنید. برای نوشتن UI Scripts به دانش پایه HTML، CSS و JavaScript نیاز است، اما میتوانید همین موارد را هنگام نوشتن اولین scriptهای ساده خود یاد بگیرید.
#
تمام محتوای یک UI Script در مرورگر، برای صفحههایی که آن script روی آنها اعمال میشود، بارگذاری میشود. بنابراین هنگام قرار دادن tokenها یا credentialها در UI Script دقت کنید تا کاربران TestRail نتوانند این اطلاعات را ببینند.
#
ما ساختار DOM یا HTML در TestRail را بخشی از یک API در نظر نمیگیریم؛ بنابراین ممکن است تغییرات نسخههای جدیدتر TestRail باعث از کار افتادن UI Scripts فعلی شما شود. با این حال، اگر UI Scripts خود را ساده نگه دارید و آنها را به شکل مقاوم و قابلاتکا بنویسید، احتمال اینکه updateهای TestRail روی آنها اثر بگذارند کمتر میشود. اگر قصد دارید UI Scripts غیرساده & و مهم بنویسید، توصیه میشود برای بررسی updateها یک محیط staging برای TestRail راهاندازی کنید.
نوشتن UI Scripts #
#
نمونههای UI Script در مخزن GitHub سفارشیسازیهای TestRail در دسترس هستند. ممکن است scriptی پیدا کنید که همین حالا با نیاز شما سازگار باشد یا فقط به چند تغییر ساده نیاز داشته باشد.
UI Scripts را میتوانید در TestRail از مسیر Admin > Customizations تعریف کنید. برای شروع نوشتن اولین UI Script، روی Add UI Script کلیک کنید تا editor یک نمونه ساده را نمایش دهد.
در بخشهای بعدی، سه بخش تشکیلدهنده یک UI Script کامل را بررسی میکنیم. همچنین برای شروع میتوانید نمونههای UI Scripts را ببینید.
اطلاعات Meta #
از آنجا که UI Scripts بلوکهای متنی ساده هستند، میتوانید همه اطلاعات meta، مانند نام، نویسنده یا نسخه، را مستقیم بهعنوان بخشی از script تعریف کنید. به این ترتیب میتوانید UI Scripts را بهسادگی بین نصبهای مختلف TestRail به اشتراک بگذارید؛ کافی است script را کپی & و paste کنید.
اولین بلوک یک UI Script شامل اطلاعات meta است که هم عملکرد script را توضیح میدهد و هم scope آن را مشخص میکند؛ یعنی صفحههایی که script روی آنها اعمال میشود.
name: Hello world
description: Shows a 'Hello, world!' message on the dashboard
author: Gurock Software
version: 1.0
includes: ^dashboard
excludes:attribute name بهعنوان نام نمایشی script در فهرست UI Scripts در TestRail استفاده میشود، در حالی که description ، author و version فقط برای ارائه اطلاعات به developer در نظر گرفته شدهاند.
attributeهای includes و excludes مشخص میکنند UI Script در TestRail روی کدام صفحهها اعمال شود. بنابراین با این attributeها میتوانید scope یک سفارشیسازی را محدود کنید و UI Script را فقط روی صفحههای مشخص اجرا کنید.
اگر قرار است یک UI Script فقط روی صفحههای خاصی از application اجرا شود، اکیدا توصیه میشود scope آن را با استفاده از includes و excludes ویژگیها به دلایل مربوط به performance. برای مثال، includes در مثال بالا باعث میشود UI script فقط روی dashboard اعمال شود. ویژگی includes و excludes بهعنوان regular expression تفسیر میشوند و با آرگومان pages در TestRail مطابقت داده میشوند؛ یعنی query string بعد از index.php? در URL.
برای نحوه اعمال فیلترها چند قانون وجود دارد:
- فیلتر exclude همیشه بر فیلتر include اولویت دارد.
- اگر مقدار هر دو ویژگی includes و excludes خالی باشد، یا هر دو property حذف شوند، UI Script روی همه صفحهها اعمال میشود.
این قوانین یک استثنا دارند: UI Scriptها هرگز روی خود فرم UI Script اجرا نمیشوند، تا در صورت نیاز بتوانید scriptهای خراب را غیرفعال کنید.
Style sheetها #
میتوانید با استفاده از ویژگی css در UI Script، style sheetها را تعریف یا override کنید. override کردن style sheetهای داخلی TestRail سادهترین راه برای سفارشی کردن رابط کاربری TestRail است. برای مثال، میتوانید رنگ elementها را تغییر دهید، ظاهر بعضی بخشهای UI در TestRail را عوض کنید، یا حتی در صورت نیاز، بخشهایی از قابلیتهای TestRail را کاملاً پنهان کنید. ویژگی css را در یک UI Script به این شکل تعریف میکنید:
css:
div.some-class {
color: red;
}TestRail style sheet را مستقیماً روی همه صفحههایی که در scope تعریف شدهاند اعمال میکند. بنابراین میتوانید از همه قابلیتهای موجود در CSS برای سفارشی کردن TestRail استفاده کنید.
JavaScript #
برای سفارشیسازیهای پیچیدهتر، معمولاً در کنار style sheetها، یا بهجای آنها، از JavaScript استفاده میشود. برای تعریف کد JavaScript در UI Script خود، کافی است از ویژگی js به شکل زیر استفاده کنید:
js:
$(document).ready(
function() {
alert('Hello, world!');
}
);TestRail همراه با کتابخانه محبوب jQuery JavaScript ارائه میشود و شما میتوانید از همه قابلیتهای jQuery استفاده کنید. برای مثال، معمولاً بهتر است از event مربوط به jQuery استفاده کنید تا $(document).ready() منتظر بمانید صفحه فعلی کامل load شود؛ همانطور که در مثال بالا میبینید.
اطلاعات context #
TestRail اطلاعات context بیشتری در اختیار شما میگذارد که میتوانید در کد JavaScript خود از آنها استفاده کنید؛ مثل جزئیات کاربر فعلی یا project فعلی. میتوانید از این اطلاعات context برای محدود کردن اجرای scriptها به roleهای کاربری یا projectهای مشخص استفاده کنید، یا از این دادهها برای integration با ابزارهای خارجی کمک بگیرید. attributeهای context زیر تعریف شدهاند:
uiscripts.context.user
- id
- name
- is_admin
- role_id
uiscripts.context.project
- id
- name
میتوانید به شکل زیر از داخل scriptهای خود به اطلاعات context دسترسی داشته باشید:
js:
alert('Welcome ' + uiscripts.context.user.name);از TestRail ۳.۰ به بعد، uiscripts.context جزئیات بیشتری درباره context صفحه فعلی دارد و میتواند شامل موارد زیر باشد:
- uiscripts.context.case
- uiscripts.context.milestone
- uiscripts.context.plan
- uiscripts.context.run
- uiscripts.context.suite
- uiscripts.context.test
قابلیت جدید دیگری که در TestRail ۳.۰ اضافه شده، uiscripts.env است؛ این بخش جزئیات محیطی را که TestRail در آن اجرا میشود نگه میدارد. propertyهای زیر برای uiscripts.env در دسترس هستند:
| نام | توضیحات |
|---|---|
| is_hosted | زمانی true است که TestRail روی TestRail Hosted اجرا شود و برای نصبهای on-premise مقدار آن false است. |
| page_base | آدرس پایه endpoint مربوط به index.php در TestRail، مثل «index.php?». با این مقدار میتوانید linkهای صفحههای TestRail را بهصورت پویا بسازید. |
| resource_base | آدرس پایه برای ارجاع به resourceهای static در TestRail، مثل imageها، فایلهای JS و موارد مشابه؛ برای مثال: «https://static.testrail.com/<version>/». |
ملاحظات performance #
UI Scripts با وجود قدرت و انعطافپذیری بالا، میتوانند روی performance اثر بگذارند؛ بنابراین مهم است پیامدهای scriptها و customizations خود را بشناسید. استفاده از selectorهای عمومی در JavaScript، مثل اجرای کد روی همه divهای صفحه، میتواند اجرای JavaScript را بهشدت کند کند و زمان load شدن صفحهها را افزایش دهد.
بهعنوان یک قاعده کلی، اجرای UI Scripts را فقط به صفحههایی محدود کنید که واقعاً میخواهید customize کنید، و selectorهای کد JavaScript خود را تا حد امکان دقیق تعریف کنید. بررسی نکات کلی performance در JavaScript خارج از محدوده این مقاله است، اما منابع خوبی درباره performance در JavaScript و jQuery در دسترس هستند.
