دسترسی به TestRail API

TestRail API بر پایه HTTP است و می‌توانید با requestهای ساده HTTP با آن کار کنید. همه requestهای نوشتنی باید از متد HTTP POST استفاده کنند و همه requestهای خواندنی باید از متد HTTP GET استفاده کنند. داده‌ها با فرمت JSON و encoding نوع UTF-۸ منتقل می‌شوند.

Authentication #

TestRail برای API انتظار دارد credentialهای authentication از طریق HTTP basic authentication استاندارد ارسال شوند. برای authentication درخواست‌های API در TestRail دو روش وجود دارد.

Username و Password #

برای authentication در API، می‌توانید username استاندارد TestRail خود را (که معمولا email شماست) همراه با password TestRail ارسال کنید. این اطلاعات باید از طریق HTTP basic authentication فرستاده شوند.

بسته به configuration احراز هویت TestRail، password شما ممکن است همان password معمول Active Directory یا LDAP باشد (این موضوع به نحوه configuration TestRail بستگی دارد؛ برای اطلاعات بیشتر راهنمای Authentication را ببینید). اگر مطمئن نیستید نصب TestRail شما از کدام گزینه استفاده می‌کند، از مدیر TestRail خود بپرسید.

$ curl -H "Content-Type: application/json" \ 
  -u "user@example.com:{some-password}" \
  ..

header تعریف می‌شود و از -H tag شروع می‌شود و در دومین \ بعد از credentialهای کاربر پایان می‌یابد.

Username و API Key #

در روش دیگر، TestRail از API key هم پشتیبانی می‌کند. API keyها را می‌توانید در TestRail از مسیر My Settings بسازید. با API key همچنان از HTTP basic authentication استفاده می‌کنید و همچنان username TestRail خود را (مثلا email) می‌فرستید؛ فقط password را با یکی از API keyهای ساخته‌شده و active جایگزین می‌کنید. می‌توانید برای سیستم‌ها یا ابزارهای third-party مختلف چند API key بسازید و هر زمان خواستید با حذف API key از مسیر My Settings دسترسی را revoke کنید.

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:{api key}" \
  ..

مخزن اسکریپت‌های API #

نمونه API scriptها در repository عمومی GitHub ما موجود است. ممکن است scriptی پیدا کنید که همین حالا نیاز شما را برطرف کند یا فقط به چند تغییر ساده نیاز داشته باشد. لطفا به repository سفارشی‌سازی‌های TestRail در GitHub مراجعه کنید.

همچنین از همه کاربران استقبال می‌کنیم scriptهای خود را به این repository ارسال کنند، اگر این scriptها می‌توانند برای کاربران دیگر مفید باشند.

نمونه request نوع GET #

مثال زیر یک request ساده برای خواندن یک test case را نشان می‌دهد. در این مثال برای ارسال request از ابزار CLI به نام cURL استفاده می‌کنیم، اما هر ابزار یا library مبتنی بر HTTP هم کار می‌کند. توجه کنید که همه usernameها، passwordها و URLها فقط نمونه هستند.

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:APIkey" \
  "https://example.testrail.com/index.php?/api/v2/get_case/1"

اجزای این request با جزئیات:

بخش	توضیح
“Content-Type: application/json”	یک header الزامی
https://example.testrail.com/	آدرس سرور
index.php?/api/v2/	مسیر TestRail API
get_case	متد API که فراخوانی می‌شود
/1	یک argument برای متد API

request و response واقعی HTTP به شکل زیر است (ساده‌سازی شده):

GET /index.php?/api/v2/get_case/1 HTTP/1.1
Host: example.testrail.com
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":1,
  "title":"An example test case"
  ..
}

نمونه request نوع POST #

request زیر یک درخواست نوشتنی ساده برای ثبت نتیجه تست را نشان می‌دهد:

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:" \
  -d '{ "status_id": 1 }' \
  "https://example.testrail.com//index.php?/api/v2/add_result/1"

request و response به شکل زیر است (ساده‌سازی شده):

POST /index.php?/api/v2/add_result/1 HTTP/1.1
Host: example.testrail.com
Content-Type: application/json

{ "status_id": 1 }

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":1,
  "test_id":1,
  "status_id":1
  ..
}

نمونه upload کردن attachment #

request زیر یک درخواست نوشتنی ساده برای افزودن attachment به نتیجه تست را نشان می‌دهد:

$ curl -H "Content-Type: multipart/form-data" \ 
  -u "user@example.com:" \ 
  -F "attachment=@C:\\image.jpg" \ 
  "https://example.testrail.io/index.php?/api/v2/add_attachment_to_result/1"

request و response به شکل زیر است (ساده‌سازی شده):

POST /index.php?/api/v2/add_attachment_to_result/1 HTTP/1.1
Host: example.testrail.io
Content-Type: multipart/form-data

{"attachment_id":11}