آشنایی با TestRail API

از TestRail API می‌توانید برای وصل کردن TestRail به ابزارها، frameworkها و برنامه‌های مختلف استفاده کنید. برای مثال، بسیاری از مشتریان از API برای اتصال testهای خودکار و ارسال نتایج آن‌ها به TestRail استفاده می‌کنند. API کاربردهای دیگری هم دارد و در ادامه چند نمونه از آن‌ها را می‌بینید.

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

چند کاربرد رایج API:

• ارسال نتایج testهای خودکار
• انتقال test caseها از سیستم‌های قدیمی
• همگام‌سازی test caseها بین سیستم‌های مختلف
• ساخت test run و test plan با کدنویسی
• دریافت اطلاعات برای integrationها

API rate limit

توجه داشته باشید که در TestRail Cloud برای حفظ کارایی مناسب برای همه کاربران، API دارای rate limit است و ممکن است بعضی درخواست‌ها throttle شوند. همچنین ممکن است TestRail پاسخ ۴۲۹ Too Many Requests برگرداند که باید آن را در کد خود مدیریت کنید. این پاسخ شامل header به نام Retry-After هم هست که نشان می‌دهد چند ثانیه باید صبر کنید تا بتوانید درخواست بعدی را ارسال کنید.

برای جلوگیری از رسیدن به rate limit در TestRail Cloud، از endpointهای bulk API استفاده کنید؛ مثلا از add_results_for_cases به‌جای add_results_for case استفاده کنید، بین API callها کمی تاخیر بگذارید، یا به TestRail Enterprise Cloud ارتقا دهید.

Rate limitهای TestRail Cloud به این صورت است:

• ۱۸۰ درخواست برای هر instance در هر دقیقه، برای subscriptionهای TestRail Cloud Professional.
• ۳۰۰ درخواست برای هر instance در هر دقیقه، برای subscriptionهای TestRail Cloud Enterprise.

پارامترهای offset و limit در API

در TestRail endpointهای bulk API زیادی وجود دارد که به شما اجازه می‌دهند با یک درخواست GET، اطلاعات چند case، test یا موجودیت دیگر TestRail را دریافت کنید. این روش دریافت اطلاعات از TestRail را سریع‌تر و کارآمدتر می‌کند، روند کار را ساده‌تر می‌کند و تعداد کل درخواست‌های ارسال‌شده به TestRail API را کاهش می‌دهد؛ مخصوصا اگر در TestRail Cloud به API rate limit نزدیک می‌شوید.

Limit

وقتی از یک endpoint bulk GET استفاده می‌کنید، مثل get_cases, get_runs ، یا get_results_for_case) تعداد پیش‌فرض رکوردهای برگشتی ۲۵۰ است. با این حال، اگر لازم باشد می‌توانید با parameter به نام limit این تعداد را کمتر کنید.

برای مثال، اگر از متد get_runs API استفاده می‌کنید و فقط می‌خواهید سه test run اول projectی با project_id برابر ۳ را دریافت کنید، درخواست زیر را ارسال می‌کنید:

GET https://{hostname}/index.php?/api/v2/get_runs/3&limit=3

توجه داشته باشید که باید {hostname} را با URL واقعی instance خود در TestRail جایگزین کنید.

پاسخ مورد انتظار شبیه این خواهد بود:

{
  "offset": 0,
  "limit": 3,
  "size": 3,
  "_links": {
    "next": "/api/v2/get_runs/3&limit=3&offset=3",
    "prev": null
  },
  "runs": [
    {
      "id": 1,
      ..
    },
    {
      "id": 2,
      ..
    },
    {
      "id": 3,
      ..
    }
  ]
}

برای parameter به نام limit می‌توانید یک عدد صحیح از ۱ تا ۲۵۰ وارد کنید. ۲۵۰ بیشترین تعداد رکورد مجاز در پاسخ است. اگر عددی بزرگ‌تر از ۲۵۰ وارد کنید، خطای زیر را می‌گیرید:

{
  "error": "Field :limit is too large (maximum 250)."
}

Offset

از parameter offset برای رفتن به مجموعه بعدی نتایج استفاده می‌شود. برای مثال، اگر از endpoint get_cases برای دریافت داده‌های همه test caseهای instance خود استفاده کنید و مقدار جداگانه‌ای برای limit تعیین نکنید، درخواست اول حداکثر ۲۵۰ رکورد test case برمی‌گرداند، چون مقدار پیش‌فرض بیشترین تعداد نتیجه ۲۵۰ است.

خروجی نمونه:

{
  "offset": 0,
  "limit": 250,
  "size": 250,
  "_links": {
    "next": "api/v2/get_cases/3&limit=250&offset=250",
    "prev": null
  },
  "cases": [
    {
      "id": 2604,
      "title": "Add watermark to document and verify print output",
      "section_id": 268,
      "template_id": 1,
      "type_id": 7,
      "priority_id": 4,
      "milestone_id": null,
      "refs": null,
      "created_by": 2,
      "created_on": 1631664168,
      "updated_by": 2,
      "updated_on": 1631664168,
      "estimate": null,
      "estimate_forecast": "8m 40s",
      "suite_id": 32,
      "display_order": 1,
      "is_deleted": 0,
      "custom_automation_type": 0,
      "custom_automation_status": null,
      "custom_preconds": null,
      "custom_steps": null,
      "custom_expected": "Etiam massa dolor, ornare sit amet, lacinia nec, bibendum ut, magna.\n\t\t\n* Nam feugiat, eros at commodo dictum,\n* Felis libero varius orci, in vulputate\n* Massa turpis scelerisque diam.\n* Nunc et felis est. Phasellus laoreet nibh vel augue\n* Faucibus at varius est pretium.\n\nQuisque pellentesque **mauris**.",
      "custom_steps_separated": null,
      "custom_mission": null,
      "custom_goals": null
    },
    ..
  ]
}

اگر project شما بیش از ۲۵۰ test case دارد، باید یک درخواست GET دیگر برای دریافت مجموعه بعدی رکوردها ارسال کنید و این بار parameter به نام offset را روی ۲۵۰ بگذارید، به این شکل:

GET https://{hostname}/index.php?/api/v2/get_cases/3&offset=250

چون در مثال بالا از متد get_cases استفاده کرده‌ایم، پاسخ شامل ۲۵۰ test case بعدی خواهد بود.

نکته: رکوردهایی که با درخواست bulk GET قابل query هستند، بر اساس مقدار ID همان موجودیت‌ها مرتب می‌شوند. برای مثال، get_cases caseها را بر اساس ID هر case، به‌ترتیب صعودی برمی‌گرداند.

برای رفتن به مجموعه بعدی رکوردها، می‌توانید از مقدار next در object _links برگشتیِ پاسخ قبلی استفاده کنید، یا عدد offset را به‌صورت دستی جلو ببرید تا به انتهای offsetها برسید.

از دو روش می‌توانید بفهمید به انتهای رکوردهای موجود رسیده‌اید. اگر درخواست فعلی شما شامل آخرین رکورد جدولی باشد که query می‌کنید، پاسخ برای مقدار next در object _links مقدار null برمی‌گرداند. همچنین اگر offsetی وارد کنید که از تعداد رکوردهای موجود بیشتر است، یک array خالی دریافت می‌کنید. برای مثال:

GET https://{hostname}/index.php?/api/v2/get_cases/3&offset=10000000

خروجی نمونه:

{
  "offset": 10000000,
  "limit": 250,
  "size": 0,
  "_links": {
    "next": null,
    "prev": "/api/v2/get_cases/3&offset=9999750&limit=250"
  },
  "cases": []
}

در automation خود می‌توانید از این رفتار استفاده کنید تا بفهمید به انتهای رکوردها رسیده‌اید یا نه.

قواعد استفاده‌شده در API Reference

راهنمای TestRail API از چند قاعده استفاده می‌کند تا parameterهای متغیری را نشان دهد که باید در URLهای درخواست API جایگزین شوند، و همچنین نمایش بعضی نمونه responseها را در مستندات کوتاه‌تر کند.

۱. متغیرهای داخل curly braces

هر مقداری را که در درخواست‌های API داخل curly braces { } آمده است، با parameter واقعی جایگزین کنید.

برای مثال، در درخواست API، GET index.php?/api/v2/get_project/{project_id}، مقدار {project_id} را با مقدار project id واقعی خود جایگزین کنید.

پس اگر project id شما ۱۰ باشد، درخواست به این شکل می‌شود: GET index.php?/api/v2/get_project/10

۲. نمونه‌های کوتاه‌شده کد پاسخ

.. در code block نشان می‌دهد که response کوتاه شده است. این علامت فقط برای خواناتر شدن مستندات استفاده می‌شود و محتوای واقعی response از TestRail API را نشان نمی‌دهد. در مثال‌های API reference از این روش استفاده شده تا فضای اشغال‌شده توسط responseها کمتر شود و مقاله راحت‌تر خوانده شود.

برای مثال، نمونه زیر responseی را نشان می‌دهد که از endpoint get_cases استفاده می‌کند.

{
  "offset": 0,
  "limit": 250,
  "size": 250,
  "_links":{
    "next": "/api/v2/get_cases/1&limit=250&offset=250",
    "prev": null
  },
  "cases":[
    { "id": 1, "title": "..", .. },
    { "id": 2, "title": "..", .. },
    ..
  ]
}

چطور متغیرهای ID را برای API callها پیدا کنیم؟

بسیاری از endpointهای TestRail API از شما می‌خواهند برای مشخص کردن projectها، caseها، test runها و موارد دیگر، یک مقدار ID در URL درخواست قرار دهید. در بخش زیر یاد می‌گیرید این IDها را از کجای UI در TestRail پیدا کنید و چطور از آن‌ها به‌عنوان parameter در درخواست API استفاده کنید.

Project ID – project_id

1. در instance خود در TestRail به Dashboard بروید.
2. از فهرست، یک project را انتخاب کنید.
3. URL را بررسی کنید. عددی که در انتهای URL می‌بینید ID همان project است. همچنین می‌توانید
4. ID کنار نام project را هم بردارید. هنگام استفاده از project ID در درخواست‌های API، حتما حرف P را حذف کنید.

برای مثال، در درخواست API، GET index.php?/api/v2/get_project/{project_id}، مقدار {project_id} را با ۳ جایگزین کنید.

در نتیجه، درخواست به این شکل خواهد بود: GET index.php?/api/v2/get_project/3.

Case ID – case_id

1. در instance خود در TestRail به Dashboard بروید.
2. از فهرست، یک project را انتخاب کنید.
3. به tab به نام Test Cases بروید.
4. از فهرست، یک test case را انتخاب کنید.
5. URL را بررسی کنید. عددی که در انتهای URL می‌بینید Test Case ID است. همچنین می‌توانید ID کنار نام test case را هم بردارید. هنگام استفاده در درخواست‌های API، حتما حرف C را حذف کنید.

Attachment ID – attachment_id

1. در instance خود در TestRail به Dashboard بروید.
2. از فهرست، یک project را انتخاب کنید.
3. به tab به نام Test Cases بروید.
4. از فهرست، یک test case را انتخاب کنید.
5. یک attachment اضافه کنید.

برای نسخه‌های قبل از TestRail ۷.۱ روی attachment راست‌کلیک کنید و Copy link address را انتخاب کنید. سپس از attachment ID موجود در URL استفاده کنید.

برای TestRail ۷.۱ و نسخه‌های بعدی روی attachment کلیک کنید. سپس ID الفبایی‌عددی را از URL صفحه Attachment Details کپی کنید.

Milestone ID – milestone_id

1. در instance خود در TestRail به Dashboard بروید.
2. از فهرست، یک project را انتخاب کنید.
3. به tab به نام Milestones بروید.
4. از فهرست، یک milestone را انتخاب کنید.
5. URL را بررسی کنید. عددی که در انتهای URL می‌بینید Milestone ID است. همچنین می‌توانید ID کنار نام milestone را هم بردارید. هنگام استفاده در درخواست‌های API، حتما حرف M را حذف کنید.

Test Plan ID – plan_id

1. در instance خود در TestRail به Dashboard بروید.
2. از فهرست، یک project را انتخاب کنید.
3. به tab به نام Test Runs and Results بروید.
4. از فهرست، یک test plan را انتخاب کنید.
5. URL را بررسی کنید. عددی که در انتهای URL می‌بینید Test Plan ID است. همچنین می‌توانید ID کنار نام test plan را هم بردارید. هنگام استفاده در درخواست‌های API، حتما حرف R را حذف کنید.

Test Run ID – run_id

1. در instance خود در TestRail به Dashboard بروید.
2. از فهرست، یک project را انتخاب کنید.
3. به tab به نام Test Runs and Results بروید.
4. از فهرست، یک test run را انتخاب کنید.
5. URL را بررسی کنید. عددی که در انتهای URL می‌بینید Test Run ID است. همچنین می‌توانید ID کنار نام test run را هم بردارید. هنگام استفاده در درخواست‌های API، حتما حرف R را حذف کنید.