دسته‌ها را مشاهده کنید

مقدمه ای بر TestRail API

مدت زمان مطالعه: : 8 دقیقه

TestRail_API (Navy Logo).png

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

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

API بخشی از TestRail است و می تواند در بخش مدیریت TestRail فعال شود مدیر > تنظیمات سایت > API.

برخی از سناریوهای معمولی که API می تواند برای آنها استفاده شود:

  • نتایج آزمون را از آزمون‌های خودکار ارسال کنید
  • تست‌کیس‌ها را از سیستم‌های قدیمی مهاجرت کنید
  • همگام سازی تست‌کیس‌ها بین سیستم های مختلف
  • اجرای تست و برنامه ریزی را به صورت برنامه ریزی شده ایجاد کنید
  • پرس و جو اطلاعات برای ادغام

  #

قبل از خواندن مرجع API، لطفاً با نهادهای TestRail مانند موارد، اجراها آشنا شوید. & نتایج، مجموعه ها و غیره. برای انجام این کار، لطفا به راهنمای کاربر TestRail با شروع موضوعات و بهترین شیوه ها.

محدودیت نرخ API #

لطفاً توجه داشته باشید که API در TestRail Cloud با نرخ محدود است تا عملکرد بهینه را برای همه کاربران تضمین کند و ممکن است درخواست‌ها را کاهش دهد. TestRail همچنین ممکن است یک پاسخ ۴۲۹ Too Many Requests را که از شما انتظار می رود پاسخ دهد. چنین پاسخی همچنین شامل یک هدر Retry-After است که نشان می دهد چند ثانیه باید منتظر بمانید تا اجازه ارسال درخواست بعدی را داشته باشید.

برای جلوگیری از محدودیت نرخ در TestRail Cloud، سعی کنید از نقاط پایانی API انبوه استفاده کنید (به عنوان مثال استفاده از add_results_for_cases به جای add_results_for case)، یک تاخیر زمانی در تماس‌های API خود ایجاد کنید، یا به TestRail Enterprise Cloud ارتقا دهید.

محدودیت های نرخ برای TestRail Cloud به شرح زیر است:

  • ۱۸۰ درخواست در هر نمونه، در دقیقه برای اشتراک های TestRail Cloud Professional.
  • ۳۰۰ درخواست در هر نمونه، در دقیقه برای اشتراک های TestRail Cloud Enterprise.

 توجه داشته باشید: هیچ محدودیتی در نرخ API در نصب سرور TestRail تعبیه نشده است.

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

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

محدود کنید #

هنگام استفاده از نقطه پایانی GET انبوه (مانند get_cases، get_runs، یا get_results_for_case) تعداد پیش‌فرض رکوردهایی که برگردانده می‌شوند ۲۵۰ است. با این حال، می‌توانید از پارامتر حد برای کاهش بیشتر در صورت تمایل استفاده کنید.

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

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

لطفا توجه داشته باشید، شما باید جایگزین کنید {hostname} با URL واقعی برای نمونه 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,
      ..
    }
  ]
}

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

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

افست #

را جبران پارامتر چیزی است که برای پیمایش به مجموعه بعدی نتایج استفاده می شود. برای مثال، اگر از get_cases نقطه پایانی برای بازیابی داده‌ها برای همه تست‌کیس‌ها در نمونه شما و تعیین مقدار محدود جداگانه، درخواست اولیه شما حداکثر ۲۵۰ پرونده آزمایشی را برمی‌گرداند زیرا حداکثر تعداد نتایج پیش‌فرض ۲۵۰ است.

خروجی نمونه:

{
  "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
    },
    ..
  ]
}

اگر بیش از ۲۵۰ تست‌کیس در پروژه خود دارید، باید یک درخواست GET دیگر برای بازیابی مجموعه رکوردهای بعدی ارسال کنید، این بار پارامتر offset را روی ۲۵۰ تنظیم کنید، مانند:

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

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

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

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

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

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": []
}

شما می توانید از این برای تعیین اینکه آیا در اتوماسیون خود رکوردها را به پایان رسانده اید یا خیر استفاده کنید.

قراردادهای مورد استفاده در مرجع API #

کتابچه راهنمای TestRail API از چند قرارداد برای نشان دادن پارامترهای متغیری استفاده می‌کند که باید در URLهای درخواست API جایگزین شوند و نحوه نمایش برخی از نمونه‌های پاسخ‌ها در اسناد را کوتاه می‌کند.

۱. متغیرهایی با بریس های مجعد #

هر مقدار را با پرانتزهای فرفری { } در درخواست‌های API با پارامترهای واقعی جایگزین کنید.

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

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

۲. نمونه کد پاسخ کوتاه #

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

برای مثال، لطفاً نمونه زیر را از پاسخ با استفاده از 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 پیدا کنیم؟ #

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

شناسه پروژه – project_id #

  1. به “داشبورد” در نمونه TestRail خود بروید.
  2. یک پروژه را از لیست انتخاب کنید.
  3. URL را بررسی کنید. کاراکتر عددی که در پایان می بینید ID پروژه است یا می توانید آن را نیز دریافت کنید
  4. شناسه کنار نام پروژه (لطفاً هنگام استفاده از شناسه پروژه در درخواست‌های API خود، نویسه «P» را حذف کنید).

Introduction to the TestRail API ss1.png

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

بنابراین، درخواست به نظر می رسد GET index.php?/api/v2/get_project/3.

شناسه پرونده – case_id #

  1. به “داشبورد” در نمونه TestRail خود بروید.
  2. یک پروژه را از لیست انتخاب کنید.
  3. به تب “تست‌کیس” بروید.
  4. یک تست‌کیس را از لیست انتخاب کنید.
  5. URL را بررسی کنید. کاراکتر عددی که در انتها می بینید، Test Case ID است یا می توانید شناسه را در کنار Test Case Name نیز دریافت کنید. لطفاً هنگام استفاده از درخواست‌های API مطمئن شوید که کاراکتر «C» را حذف کرده‌اید.

Introduction to the TestRail API ss2.png

شناسه پیوست – attachment_id #

  1. به “داشبورد” در نمونه TestRail خود بروید.
  2. یک پروژه را از لیست انتخاب کنید.
  3. به تب “تست‌کیس” بروید.
  4. یک تست‌کیس را از لیست انتخاب کنید.
  5. یک پیوست اضافه کنید.

برای نسخه های TestRail قبل از ۷.۱ – بر روی پیوست کلیک راست کرده و «Copy link address» را انتخاب کنید. و سپس از شناسه پیوست ذکر شده در URL استفاده کنید.

برای TestRail نسخه ۷.۱ و بالاتر – بر روی پیوست کلیک کنید. سپس شناسه الفبایی عددی را از URL موجود در صفحه «جزئیات پیوست» کپی کنید.

Introduction to the TestRail API ss5.png

Milestone ID – milestone_id #

  1. به “داشبورد” در نمونه TestRail خود بروید.
  2. یک پروژه را از لیست انتخاب کنید.
  3. به تب “Milestones” بروید.
  4. یک نقطه عطف را از لیست انتخاب کنید.
  5. URL را بررسی کنید. کاراکتر عددی که در انتها مشاهده می کنید Milestone ID است یا می توانید شناسه را در کنار Milestone Name نیز دریافت کنید. لطفاً هنگام استفاده از درخواست های API مطمئن شوید که کاراکتر “M” را حذف نکنید.

Introduction to the TestRail API ss6.png

شناسه طرح آزمایشی – plan_id #

  1. به “داشبورد” در نمونه TestRail خود بروید.
  2. یک پروژه را از لیست انتخاب کنید.
  3. به برگه «تست اجراها و نتایج» بروید.
  4. یک طرح آزمایشی را از لیست انتخاب کنید.
  5. URL را بررسی کنید. کاراکتر عددی که در انتها مشاهده می‌کنید، شناسه طرح آزمایشی است، یا می‌توانید شناسه را در کنار نام طرح آزمایشی دریافت کنید. لطفاً هنگام استفاده از درخواست‌های API مطمئن شوید که کاراکتر R را حذف کرده‌اید.

Introduction to the TestRail API ss7.png

تست Run ID – run_id #

  1. به “داشبورد” در نمونه TestRail خود بروید.
  2. یک پروژه را از لیست انتخاب کنید.
  3. به برگه «تست اجراها و نتایج» بروید.
  4. یک اجرای تست را از لیست انتخاب کنید.
  5. URL را بررسی کنید. کاراکتر عددی که در انتها مشاهده می کنید، Test Run ID است یا می توانید شناسه را در کنار Test Run Name نیز دریافت کنید. لطفاً هنگام استفاده از درخواست‌های API مطمئن شوید که کاراکتر R را حذف کرده‌اید.

Introduction to the TestRail API ss8.png

 

به‌روزرسانی شده در 1405-04-15

احساسات شما چیست؟

  • خوشحال
  • عادی
  • ناراحت

دیدگاهتان را بنویسید