فهرست مستندات

نتایج

به‌روزرسانی ۱۷ تیر ۱۴۰۵ ۱۵ دقیقه مطالعه TestRail

فهرست مطالب

از 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

فیلترهای 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

فیلترهای 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

کدهای 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)

get_results

پارامترها

فیلترهای request

محتوای response

کدهای response

get_results_for_case

پارامترها

فیلترهای request

محتوای response

کدهای response

get_results_for_run

پارامترها

فیلترهای request

محتوای response

کدهای response

add_result

پارامترها

فیلدهای request

نمونه request

محتوای response

کدهای response

add_result_for_case

پارامترها

محتوای response

کدهای response

add_results

پارامترها

نمونه request

محتوای response

کدهای response

add_results_for_cases

پارامترها

نمونه request

محتوای response

کدهای response

edit_result

پارامترها

بدنه request

نمونه request

محتوای response

کدهای response

TestRail را همین حالا در محیط دمو ببینید.