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

نتایج

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

از API متدهای زیر برای دریافت جزئیات test resultها و اضافه کردن test resultهای جدید استفاده کنید.

get_results #

فهرستی از test resultهای یک test را برمی‌گرداند.

GET index.php?/api/v2/get_results/{test_id}

پارامترها #

نام نوع الزامی توضیح
test_id عدد صحیح true ID مربوط به test
limit عدد صحیح false عددی که تعداد test resultهای نمایش‌داده‌شده در response را محدود می‌کند. محدودیت پیش‌فرض اندازه response برابر ۲۵۰ است – به TestRail ۶.۷ یا نسخه‌های جدیدتر نیاز دارد
offset عدد صحیح false عددی که مشخص می‌کند response از کدام موقعیت شروع شود – به TestRail ۶.۷ یا نسخه‌های جدیدتر نیاز دارد

این متد حداکثر ۲۵۰ مورد را در آرایه response برمی‌گرداند. برای دریافت موارد بیشتر، می‌توانید requestهای دیگری با filter مربوط به offset ارسال کنید که در بخش فیلترهای request در ادامه توضیح داده شده است.

فیلترهای request #

filterهای زیر قابل استفاده هستند:

نام نوع توضیح
defects_filter رشته یک Defect ID واحد، مانند TR-۱ یا ۴۲۹۱
limit/offset عدد صحیح نتیجه را به :limit test result محدود کنید. برای رد کردن recordها از :offset استفاده کنید
status_id عدد صحیح (فهرست) فهرستی از status IDها، جداشده با کاما، برای filter کردن 
# The latest 10 results for test with ID 1 and statuses 4 or 5 (Retest, Failed)
GET index.php?/api/v2/get_results/1&status_id=4,5&limit=10

محتوای response #

نمونه‌ای از یک response معمول را در ادامه ببینید:

{
    "offset": 0,
    "limit": 250,
    "size": 250,
    "_links": {
       "next": "/api/v2/get_results/131071&limit=250&offset=250",
       "prev": null
    },
    "results": [
        {
            "assignedto_id": 1,
            "comment": "This test failed: ..",
            "created_by": 1,
            "created_on": 1393851801,
            "custom_step_results": [],   
            "defects": "TR-1",
            "elapsed": "5m",
            "id": 1,
            "status_id": 5,
            "test_id": 1,
            "version": "1.0RC1"
        }
    ]
}

system fieldهای زیر همیشه در response وجود دارند:

نام نوع توضیح
assignedto_id عدد صحیح ID کاربری که test result به او assigned شده است
comment رشته comment یا پیام خطای test result
created_by عدد صحیح ID کاربری که test result را ایجاد کرده است
created_on timestamp تاریخ و زمان ایجاد test result، به صورت UNIX timestamp
defects رشته فهرستی از defectهای مرتبط با test result، جداشده با کاما
elapsed بازه زمانی مدت‌زمان اجرای test، مانند «1m» یا «2m 30s»
id عدد صحیح ID یکتای test result
status_id عدد صحیح status مربوط به test result، مانند passed یا failed؛ همچنین ببینید get_statuses
test_id عدد صحیح ID مربوط به testی که این test result به آن تعلق دارد
version رشته نسخه یا buildی که test روی آن اجرا شده است

فیلدهای depth ، display_order و parent سلسله‌مراتب sectionها را در یک test suite مشخص می‌کنند. فیلد depth برای همه sectionهای سطح ریشه ۰ است و برای همه child sectionها مقداری بزرگ‌تر از ۰ دارد. بنابراین فیلد depth سطح section را در سلسله‌مراتب نشان می‌دهد. همچنین ببینید get_sections برای نمونه.

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test resultها در response برگردانده می‌شوند
400 test نامعتبر یا ناشناخته است
403 به project دسترسی ندارید
429 فقط TestRail Cloud– requestهای بیش از حد؛ ببینید API rate limit)

get_results_for_case #

فهرستی از test resultها را برای ترکیب یک test run و test case برمی‌گرداند.

تفاوت آن با get_results این است که این متد به‌جای test، به test run + test case نیاز دارد. در TestRail، testها بخشی از یک test run هستند و test caseها در test suite مرتبط قرار دارند. بنابراین وقتی یک test run جدید می‌سازید، TestRail برای هر test case موجود در test suite آن run یک test ایجاد می‌کند. در نتیجه می‌توانید test را «نمونه‌ای» از یک test case در نظر بگیرید که می‌تواند test result، comment و test status داشته باشد. همچنین راهنمای getting started guide TestRail را برای جزئیات بیشتر درباره تفاوت test case و test ببینید.

GET index.php?/api/v2/get_results_for_case/{run_id}/{case_id}

پارامترها #

نام نوع الزامی توضیح
run_id عدد صحیح true ID مربوط به test run
case_id عدد صحیح true ID مربوط به test case

این متد حداکثر ۲۵۰ مورد را در آرایه response برمی‌گرداند. برای دریافت موارد بیشتر، می‌توانید requestهای دیگری با filter مربوط به offset ارسال کنید که در بخش فیلترهای request در ادامه توضیح داده شده است.

فیلترهای request #

filterهای زیر قابل استفاده هستند: 

نام نوع توضیح
defects_filter رشته یک Defect ID واحد، مانند TR-۱ یا ۴۲۹۱
limit عدد صحیح تعداد test resultهایی که response باید برگرداند. اندازه پیش‌فرض response برابر ۲۵۰ است – به TestRail ۶.۷ یا نسخه‌های جدیدتر نیاز دارد
offset عدد صحیح محلی که شمارش resultهای test باید از آن شروع شود، یعنی offset – به TestRail ۶.۷ یا نسخه‌های جدیدتر نیاز دارد
status_id عدد صحیح (فهرست) فهرستی از status IDها، جداشده با کاما، برای filter کردن 
# All results for test run with ID 1 and test case with ID 2
GET index.php?/api/v2/get_results_for_case/1/2

محتوای response  #

این متد از همان قالب response مربوط به get_results.

{
    "offset": 0,
    "limit": 250,
    "size": 250,
    "_links": {
       "next": "/api/v2/get_results/131071&limit=250&offset=250",
       "prev": null
    },
    "results": [
        {
            "assignedto_id": 1,
            "comment": "This test failed: ..",
            "created_by": 1,
            "created_on": 1393851801,
            "custom_step_results": [],
            "defects": "TR-1",
            "elapsed": "5m",
            "id": 1,
            "status_id": 5,
            "test_id": 1,
            "case_id": 5,
            "version": "1.0RC1"
        }
    ]
}

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test resultها در response برگردانده می‌شوند
400 test run یا test case نامعتبر یا ناشناخته است
403 به project دسترسی ندارید
429 فقط TestRail Cloud– requestهای بیش از حد؛ ببینید API rate limit)

get_results_for_run #

فهرستی از test resultها را برای یک test run برمی‌گرداند.

GET index.php?/api/v2/get_results_for_run/{run_id}

پارامترها #

نام نوع الزامی توضیح
run_id عدد صحیح true ID مربوط به test run

این متد حداکثر ۲۵۰ مورد را در آرایه response برمی‌گرداند. برای دریافت موارد بیشتر، می‌توانید requestهای دیگری با filter مربوط به offset ارسال کنید که در بخش فیلترهای request در ادامه توضیح داده شده است.

فیلترهای request #

filterهای زیر قابل استفاده هستند:

نام نوع توضیح
created_after timestamp فقط test resultهایی را برگرداند که پس از این تاریخ ایجاد شده‌اند، به صورت UNIX timestamp
created_before timestamp فقط test resultهایی را برگرداند که قبل از این تاریخ ایجاد شده‌اند، به صورت UNIX timestamp
created_by عدد صحیح (فهرست) فهرستی از ایجادکنندگان، یعنی user IDها، جداشده با کاما، برای filter کردن
defects_filter رشته یک Defect ID واحد، مانند TR-۱ یا ۴۲۹۱
limit عدد صحیح عددی که تعداد resultهای نمایش‌داده‌شده در response را محدود می‌کند. این parameter اختیاری است و محدودیت پیش‌فرض اندازه response برابر ۲۵۰ است – به TestRail ۶.۷ یا نسخه‌های جدیدتر نیاز دارد
offset عدد صحیح عددی که مشخص می‌کند response از کدام موقعیت شروع شود. این parameter اختیاری است – به TestRail ۶.۷ یا نسخه‌های جدیدتر نیاز دارد
status_id عدد صحیح (فهرست) فهرستی از status IDها، جداشده با کاما، برای filter کردن 
# The latest 10 results for test run with ID 1 created by user 5
GET index.php?/api/v2/get_results_for_run/1&created_by=5&limit=10

محتوای response  #

نمونه‌ای از یک response معمول را در ادامه ببینید:

{
    "offset": 0,
    "limit": 250,
    "size": 250,
    "_links": {
       "next": "/api/v2/get_results/131071&limit=250&offset=250",
       "prev": null
    },
    "results": [
        {
            "assignedto_id": 1,
            "comment": "This test failed: ..",
            "created_by": 1,
            "created_on": 1393851801,
            "custom_step_results": [],   
            "defects": "TR-1",
            "elapsed": "5m",
            "id": 1,
            "case_id": 123,
            "status_id": 5,
            "test_id": 1,
            "version": "1.0RC1"
        }
    ]
}

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test resultها در response برگردانده می‌شوند
400 test run نامعتبر یا ناشناخته است
403 به project دسترسی ندارید
429 فقط TestRail Cloud– requestهای بیش از حد؛ ببینید API rate limit)

add_result #

یک test result جدید یا comment اضافه می‌کند، یا یک test را assign می‌کند. اگر می‌خواهید برای چند test نتیجه اضافه کنید، بهتر است از add_results استفاده کنید.

POST index.php?/api/v2/add_result/{test_id}

پارامترها #

نام نوع الزامی توضیح
test_id عدد صحیح true ID مربوط به testی که result باید به آن اضافه شود

فیلدهای request #

POST fieldهای زیر پشتیبانی می‌شوند (system fieldها):

نام نوع توضیح
status_id عدد صحیح

ID مربوط به test status. statusهای پیش‌فرض سیستم این IDها را دارند:

  • 1: Passed
  • 2: Blocked
  • 3: Untested (هنگام اضافه کردن result جدید مجاز نیست)
  • 4: Retest
  • 5: Failed

فهرست کامل statusهای سیستمی و سفارشی را می‌توانید از طریق get_statuses دریافت کنید.
comment رشته comment یا توضیح مربوط به test result
version رشته نسخه یا buildی که تست کرده‌اید
elapsed بازه زمانی زمانی که اجرای test طول کشیده است، مانند «30s» یا «1m 45s»
defects رشته فهرستی از defectها، جداشده با کاما، برای لینک کردن به test result
assignedto_id عدد صحیح ID کاربری که test باید به او assigned شود

custom fieldها نیز پشتیبانی می‌شوند و باید با system name خود و با پیشوند custom_ ارسال شوند، مانند:

{
    ..
    "custom_comment": "This is a custom comment"
    ..
}

custom fieldهای زیر پشتیبانی می‌شوند:

نام نوع توضیح
Checkbox boolean true اگر انتخاب شده باشد؛ در غیر این صورت false
Date رشته تاریخ با همان قالبی که برای کاربران TestRail و API تنظیم شده است، مانند «۰۷/۰۸/۲۰۱۳»
Dropdown عدد صحیح ID یکی از مقدارهای dropdown، مطابق configuration همان field
Integer عدد صحیح یک عدد صحیح معتبر
Milestone عدد صحیح ID یک milestone برای custom field
Multi-select آرایه آرایه‌ای از IDها، مطابق configuration همان field
Step Results آرایه آرایه‌ای از objectها که step resultها را مشخص می‌کند. همچنین نمونه زیر را ببینید
String رشته یک رشته معتبر با حداکثر طول ۲۵۰ کاراکتر
Text رشته رشته‌ای بدون محدودیت طول
URL رشته رشته‌ای که با ساختار URL معتبر مطابقت دارد
User عدد صحیح ID یک کاربر برای custom field

نمونه request #

همچنین نمونه زیر را ببینید که نشان می‌دهد چگونه step resultها را با structured steps custom field ارسال کنید:

{
    "status_id": 5,
    "comment": "This test failed",
    "elapsed": "15s",
    "defects": "TR-7",
    "version": "1.0 RC1 build 3724",
    "custom_step_results": [
        {
            "content": "Step 1",
            "expected": "Expected Result 1",
            "actual": "Actual Result 1",
            "status_id": 1
        },
        {
            "content": "Step 2",
            "expected": "Expected Result 2",
            "actual": "Actual Result 2",
            "status_id": 2
        }
    ]
}

محتوای response #

در صورت موفقیت، این متد test result جدید را با همان قالب response مربوط به get_results برمی‌گرداند، اما به‌جای فهرستی از resultها فقط یک result برمی‌گرداند.

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test result ایجاد شده و در response برگردانده می‌شود
400 test نامعتبر یا ناشناخته است
403 مجوز اضافه کردن test resultها را ندارید یا به project دسترسی ندارید
429 فقط TestRail Cloud– requestهای بیش از حد؛ ببینید API rate limit)

add_result_for_case #

یک test result جدید یا comment اضافه می‌کند، یا یک test را assign می‌کند (برای ترکیب یک test run و test case). اگر می‌خواهید برای چند test case نتیجه اضافه کنید، بهتر است از add_results_for_cases استفاده کنید.

تفاوت آن با add_result این است که این متد به‌جای test، به test run + test case نیاز دارد. در TestRail، testها بخشی از یک test run هستند و test caseها در test suite مرتبط قرار دارند. بنابراین وقتی یک test run جدید می‌سازید، TestRail برای هر test case موجود در test suite آن run یک test ایجاد می‌کند. در نتیجه می‌توانید test را «نمونه‌ای» از یک test case در نظر بگیرید که می‌تواند test result، comment و test status داشته باشد. همچنین راهنمای getting started guide TestRail را برای جزئیات بیشتر درباره تفاوت test case و test ببینید.

POST index.php?/api/v2/add_result_for_case/{run_id}/{case_id}

پارامترها #

نام نوع الزامی توضیح
run_id عدد صحیح true ID مربوط به test run
case_id عدد صحیح true ID مربوط به test case

این متد همان POST fieldهای add_result را پشتیبانی می‌کند.

محتوای response #

در صورت موفقیت، این متد test result جدید را با همان قالب response مربوط به get_results برمی‌گرداند، اما به‌جای فهرستی از resultها فقط یک result برمی‌گرداند.

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test result ایجاد شده و در response برگردانده می‌شود
400 test run یا test case نامعتبر یا ناشناخته است
403 مجوز اضافه کردن test resultها را ندارید یا به project دسترسی ندارید
429 فقط TestRail Cloud– requestهای بیش از حد؛ ببینید API rate limit)

add_results #

یک یا چند test result یا comment جدید اضافه می‌کند، یا یک یا چند test را assign می‌کند. برای test automation مناسب است، چون می‌توانید چند test result را در یک مرحله به‌صورت گروهی اضافه کنید.

POST index.php?/api/v2/add_results/{run_id}

پارامترها #

نام نوع الزامی توضیح
run_id عدد صحیح true ID مربوط به test runی که resultها باید به آن اضافه شوند

این متد یک آرایه از test resultها را انتظار دارد؛ این آرایه از طریق field «results» ارسال می‌شود، طبق توضیح پایین. هر test result باید test ID را مشخص کند و می‌تواند همان fieldهای add_result را ارسال کند؛ یعنی همه system fieldها و custom fieldهای مربوط به test.

توجه کنید که همه testهای reference‌شده باید به همان test run تعلق داشته باشند.

نمونه request #

فهرست زیر یک request نمونه معمول را نشان می‌دهد. علاوه بر test، برای هر result باید حداقل یکی از fieldهای status، comment یا assignee را مشخص کنید.

{
    "results": [
        {
            "test_id": 101,
            "status_id": 5,
            "comment": "This test failed",
            "defects": "TR-7"

        },
        {
            "test_id": 102,
            "status_id": 1,
            "comment": "This test passed",
            "elapsed": "5m",
            "version": "1.0 RC1"
        },
        {
            "test_id": 101,
            "assignedto_id": 5,
            "comment": "Assigned this test to Joe"
        }
    ]
}

محتوای response #

در صورت موفقیت، این متد test resultهای جدید را با همان قالب response مربوط به get_results و با همان ترتیب فهرست داخل request برمی‌گرداند.

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test resultها ایجاد شده و در response برگردانده می‌شوند
400 test run یا testها نامعتبر یا ناشناخته هستند
403 مجوز اضافه کردن test resultها را ندارید یا به project دسترسی ندارید
429 فقط TestRail Cloud– requestهای بیش از حد؛ ببینید API rate limit)

add_results_for_cases #

یک یا چند test result یا comment جدید اضافه می‌کند، یا یک یا چند test را assign می‌کند (با استفاده از case IDها). برای test automation مناسب است، چون می‌توانید چند test result را در یک مرحله به‌صورت گروهی اضافه کنید.

POST index.php?/api/v2/add_results_for_cases/{run_id}

پارامترها #

نام نوع الزامی توضیح
run_id عدد صحیح true ID مربوط به test runی که resultها باید به آن اضافه شوند

این متد یک آرایه از test resultها را انتظار دارد؛ این آرایه از طریق field «results» ارسال می‌شود، طبق توضیح پایین. هر test result باید test case ID را مشخص کند و می‌تواند همان fieldهای add_result را ارسال کند؛ یعنی همه system fieldها و custom fieldهای مربوط به test.

تفاوت آن با add_results این است که این متد به‌جای test ID، test case ID دریافت می‌کند. برای جزئیات، ببینید add_result_for_case .

توجه کنید که همه testهای reference‌شده باید به همان test run تعلق داشته باشند.

نمونه request #

فهرست زیر یک request نمونه معمول را نشان می‌دهد. علاوه بر test case، برای هر result باید حداقل یکی از fieldهای status، comment یا assignee را مشخص کنید.

{
    "results": [
        {
            "case_id": 1,
            "status_id": 5,
            "comment": "This test failed",
            "defects": "TR-7"
        },
        {
            "case_id": 2,
            "status_id": 1,
            "comment": "This test passed",
            "elapsed": "5m",
            "version": "1.0 RC1"
        },
        {
            "case_id": 1,
            "assignedto_id": 5,
            "comment": "Assigned this test to Joe"
        }
    ]
}

محتوای response #

در صورت موفقیت، این متد فهرستی صفحه‌بندی‌نشده از test resultهای جدید را با قالبی مشابه get_results برمی‌گرداند. 

[    
    {
        "assignedto_id": 1,
        "comment": "This test failed: ..",
        "created_by": 1,
        "created_on": 1393851801,
        "custom_step_results": [],   
        "defects": "TR-1",
        "elapsed": "5m",
        "id": 1,
        "status_id": 5,
        "test_id": 1,
        "version": "1.0RC1"
    }
]

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test resultها ایجاد شده و در response برگردانده می‌شوند
400 test run یا test caseها نامعتبر یا ناشناخته هستند
403 مجوز اضافه کردن test resultها را ندارید یا به project دسترسی ندارید
429 فقط TestRail Cloud– requestهای بیش از حد؛ ببینید API rate limit)

edit_result #

یک test result موجود را به‌روزرسانی می‌کند. از update جزئی پشتیبانی می‌کند؛ فقط fieldهایی که در request آمده‌اند تغییر می‌کنند و سایر fieldها مقدار فعلی خود را حفظ می‌کنند. وقتی لازم است resultی را که قبلاً ارسال شده اصلاح یا کامل‌تر کنید، از این متد استفاده کنید؛ برای مثال برای اضافه کردن custom step resultها یا به‌روزرسانی comment بعد از ارسال اولیه.

POST index.php?/api/v2/edit_result/{result_id}

پارامترها #

نام نوع الزامی توضیح
result_id
 عدد صحیح true ID مربوط به test resultی که باید به‌روزرسانی شود

بدنه request #

filterهای زیر را می‌توانید به‌عنوان query parameter روی URL درخواست اعمال کنید:

نام نوع توضیح
status_id
 boolean ID مربوط به test status. statusهای پیش‌فرض سیستم این IDها را دارند: ۱: Passed; ۲: Blocked; ۳: Untested (مجاز نیست); ۴: Retest; ۵: Failed.
فهرست کامل statusهای سیستمی و سفارشی را می‌توانید از طریق get_statuses دریافت کنید.
comment
 رشته
comment یا توضیح مربوط به test result
version
 رشته
نسخه یا buildی که تست کرده‌اید
elapsed
 بازه زمانی
زمانی که اجرای test طول کشیده است، مانند “30s” یا “1m 45s”
defects رشته
فهرستی از defectها، جداشده با کاما، برای لینک کردن به test result
assignedto_id
 عدد صحیح
ID کاربری که test باید به او assigned شود
custom fieldها نیز پشتیبانی می‌شوند و باید با system name خود و با پیشوند `custom_` ارسال شوند، مانند:
نام نوع توضیح
Checkbox
 boolean true اگر انتخاب شده باشد؛ در غیر این صورت false
Date رشته
تاریخ با همان قالبی که برای کاربران TestRail و API تنظیم شده است، مانند “۰۷/۰۸/۲۰۱۳”
Dropdown عدد صحیح
ID یکی از مقدارهای dropdown، مطابق configuration همان field
Integer عدد صحیح
یک عدد صحیح معتبر
Milestone عدد صحیح
ID یک milestone برای custom field
Multi-select آرایه
آرایه‌ای از IDها، مطابق configuration همان field
Step Results آرایه
آرایه‌ای از objectها که step resultها را مشخص می‌کند. همچنین نمونه زیر را ببینید
String رشته
یک رشته معتبر با حداکثر طول ۲۵۰ کاراکتر
Text رشته
 رشته‌ای بدون محدودیت طول
URL رشته
رشته‌ای که با ساختار URL معتبر مطابقت دارد
User عدد صحیح
ID یک کاربر برای custom field

نمونه request #

{
    "status_id": 5,
    "comment": "This test failed",
    "elapsed": "15s",
    "defects": "TR-7",
    "version": "1.0 RC1 build 3724",
    "custom_step_results": [
        {
            "content": "Step 1",
            "expected": "Expected Result 1",
            "actual": "Actual Result 1",
            "status_id": 1
        },
        {
            "content": "Step 2",
            "expected": "Expected Result 2",
            "actual": "Actual Result 2",
            "status_id": 2
        }
    ]
}
توجه: وقتی `custom_step_results` ارسال شود، کل آرایه step resultهای آن result را جایگزین می‌کند. stepهای جداگانه را نمی‌توان به‌صورت مستقل به‌روزرسانی کرد.

محتوای response #

در صورت موفقیت، این متد test result به‌روزرسانی‌شده را با همان قالب response مربوط به get_results برمی‌گرداند، اما به‌جای فهرستی از resultها فقط یک result برمی‌گرداند.

کدهای response #

Status Code توضیح
200 موفقیت‌آمیز؛ test result به‌روزرسانی شده و در response برگردانده می‌شود
400 result نامعتبر یا ناشناخته است، یا request شامل field تغییرناپذیر است (id, test_id, created_on, created_by)
403 مجوز ویرایش test resultها را ندارید، به project دسترسی ندارید، یا result خارج از بازه زمانی مجاز برای ویرایش است
429 فقط TestRail Cloud – requestهای بیش از حد؛ ببینید API rate limit)

 

به‌روزرسانی شده در ۱۴۰۵-۰۴-۱۷

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

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

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