テスト計画

テスト計画に関する情報を取得したり、テスト計画を作成または変更するには、次の API メソッドを使用します。TestRail では、テスト計画を使用して複数のテスト ランをまとめたり、複数のブラウザー、OS、その他の設定に対して 1 つずつテスト ランを追加する代わりにテスト ランを自動生成できます。

get_plan

既存のテスト計画を返します。

GET index.php?/api/v2/get_plan/{plan_id}

パラメーター

レスポンスの内容

レスポンスの例

{
    "id": 10,
    "name": "Release 1.0: Final (all browsers)",
    "description": null,
    "milestone_id": 3,
    "assignedto_id": null,
    "is_completed": false,
    "completed_on": null,
    "passed_count": 445,
    "blocked_count": 99,
    "untested_count": 473,
    "retest_count": 107,
    "failed_count": 56,
    "custom_status1_count": 0,
    "custom_status2_count": 0,
    "custom_status3_count": 0,
    "custom_status4_count": 0,
    "custom_status5_count": 0,
    "custom_status6_count": 0,
    "custom_status7_count": 0,
    "project_id": 1,
    "created_on": 1646058671,
    "created_by": 1,
    "url": "https://74trialapitesting.testrail.io/index.php?/plans/view/10",
    "entries": [
        {
            "id": "75698796-61d5-46e8-9c14-d334351f12d0",
            "suite_id": 1,
            "name": "Browser test",
            "refs": null,
            "description": null,
            "include_all": true,
            "runs": [
                {
                    "id": 13,
                    "suite_id": 1,
                    "name": "Browser test",
                    "description": null,
                    "milestone_id": 3,
                    "assignedto_id": null,
                    "include_all": true,
                    "is_completed": false,
                    "completed_on": null,
                    "passed_count": 88,
                    "blocked_count": 20,
                    "untested_count": 97,
                    "retest_count": 19,
                    "failed_count": 12,
                    "custom_status1_count": 0,
                    "custom_status2_count": 0,
                    "custom_status3_count": 0,
                    "custom_status4_count": 0,
                    "custom_status5_count": 0,
                    "custom_status6_count": 0,
                    "custom_status7_count": 0,
                    "project_id": 1,
                    "plan_id": 10,
                    "entry_index": 1,
                    "entry_id": "75698796-61d5-46e8-9c14-d334351f12d0",
                    "config": "Chrome",
                    "config_ids": [
                        3
                    ],
                    "created_on": 1646058671,
                    "refs": null,
                    "created_by": 1,
                    "url": "https://74trialapitesting.testrail.io/index.php?/runs/view/13"
                }
            ]
        }
    ]
}

レスポンスには次のフィールドが含まれています。

entries フィールドにはテスト計画の entries の配列が含まれます。テスト計画のエントリとは、 (ユーザー インターフェイスと同様に) 同じテスト スイートに所属する テスト ラン のグループです。各グループに含まれる テスト ランの量はさまざまであり、設定もサポートされています。add_plan および add_plan_entry も参照してください。

レスポンス コード

get_plans

プロジェクトのテスト計画のリストを返します。

GET index.php?/api/v2/get_plans/{project_id}

パラメーター

リクエスト ボディ

このメソッドは、最大で 250 のエントリを含むレスポンス配列を返します。それ以上のエントリを取得するには、下のリクエスト フィルター セクションで説明されているオフセット フィルターを使用して追加のリクエストを行います。

# All active test plans for project with ID 1 and milestone 2 or 3
GET index.php?/api/v2/get_plans/1&is_completed=0&milestone_id=2,3

レスポンスの内容

レスポンスにはテスト計画の配列が含まれます。リスト内の各テスト計画の形式は、レスポンスには entriesフィールドが含まれていないことを除いては、get_plan と同じです。

{
    "offset": 0,
    "limit": 250,
    "size": 1,
    "_links": {
        "next": null,
        "prev": null,
    },
    "plans": [
        {
            "id": 1,
            "name": "System test 1", 
            // ..
        },
        {
            "id": 2,
            "name": "System test 2", 
            // ..
        },
        // ..
    ]
}

レスポンス コード

add_plan

新規テスト計画を作成します。

POST index.php?/api/v2/add_plan/{project_id}

パラメーター

リクエスト ボディ

リクエストの例

次の例は、いくつかの テスト ラン を含む新しいテスト計画を作成する方法を示しています。

{
    "name": "System test",
    "entries": [
        {
            "suite_id": 1,
            "name": "Custom run name",
            "assignedto_id": 1 // ID of the assignee
        },
        {
            "suite_id": 1,
            "include_all": false, // Custom selection
            "case_ids": [1, 2, 3, 5]
        }
    ]
}

add_plan は テスト計画の設定(configurations) もサポートしています。

{
    "name": "System test",
    "entries": [
        {
            "suite_id": 1,
            "include_all": true,
            "config_ids": [1, 2, 4, 5, 6],
            "runs": [
                {
                    "include_all": false,
                    "case_ids": [1, 2, 3],
                    "assignedto_id": 1,
                    "config_ids": [2, 5]
                },
                {
                    "include_all": false,
                    "case_ids": [1, 2, 3, 5, 8],
                    "assignedto_id": 2,
                    "config_ids": [2, 6]
                }
                // ..
            ]
        },
        // ..
    ]
}

このサンプル リクエストは、TestRail のユーザー インターフェイスを使用してテスト計画と設定を管理する場合と同様に、テスト計画エントリごとに複数のテスト ランを作成します。詳細については下記の add_plan_entry を参照してください。

‘refs’ フィールドは TestRail 6.3 以降でサポートされています。

レスポンスの内容

成功した場合、このメソッドは get_plan と同じレスポンス形式を使用して新しいテスト計画を返します。

レスポンス コード

add_plan_entry

テスト計画に 1つまたはそれ以上の新しい テスト ラン を追加します。

POST index.php?/api/v2/add_plan_entry/{plan_id}

パラメーター

リクエスト ボディ

リクエストの例

いくつかの テスト ラン と設定を含む新しいテスト計画エントリを作成する方法を示す次の例も参照してください。

{
    "suite_id": 1,
    "assignedto_id": 1,                 // Default assignee
    "include_all": true,                // Default selection
    "config_ids": [1, 2, 4, 5, 6],
    "runs": [
        {
            "include_all": false,       // Override selection
            "case_ids": [1, 2, 3],
            "config_ids": [2, 5]
        },
        {
            "include_all": false,       // Override selection
            "case_ids": [1, 2, 3, 5, 8],
            "assignedto_id": 2,         // Override assignee
            "config_ids": [2, 6]
        },
        // ..
    ]
}

この例では、runs フィールドの配列要素ごとに新しい テスト ラン が作成されます。最上位の assignedto_id、include_all、および case_ids フィールドには、すべての テスト ラン のデフォルトの担当者および選択するテスト ケースを指定します。上記の例に示されているように、テスト ランごとにこれらのフィールドを上書きできます。

最上位の config_ids フィールドは、テスト ラン のリストで使用するすべての設定をまとめたリストを指定します。個々のテスト ランで参照されるすべての設定は、このフィールドに含まれていなければなりません。各テスト ランでは、設定グループごとに 1 つの設定を指定できます。設定グループを網羅した組み合わせを指定する必要があります。たとえば、次のような設定と設定グループがあるとします。

例のトップレベルの  config_ids フィールドには、設定 1、2、4、5 および 6 が含まれています。設定の組み合わせが有効であるためには、各設定グループから 1 つの設定を含める必要があります。したがって、有効な組み合わせは次のとおりです。

例では、これらの組み合わせのうち、 2,5 (Firefox、Windows 8) と 2,6 (Firefox、Ubuntu 12) の 2 つだけを含めることを選択しています。TestRail は、組み合わせごとに 1 つ、合計 2 つのテスト ランを追加します。

レスポンスの内容

成功した場合、このメソッドは、get_plan の entries フィールドと同じレスポンス形式を使用して、テスト ランを含む新しいテスト計画エントリを返します。エントリのリストではなく単一のエントリを返します。

レスポンス コード

add_run_to_plan_entry

POST index.php?/api/v2/add_run_to_plan_entry/{plan_id}/{entry_id}

パラメーター

リクエスト ボディ

リクエストの例

テスト計画エントリに新しいテスト ランを追加する方法を示す次の例も参照してください。

{
    "config_ids": [1, 5],
    "include_all": false,
    "case_ids": [1, 2, 4]
}

レスポンス コード

update_plan

既存のテスト計画を更新します (部分的な更新がサポートされています。つまり、特定のフィールドのみを送信して更新できます)。

POST index.php?/api/v2/update_plan/{plan_id}

パラメーター

entriesフィールドを除いて、このメソッドは add_plan と同じ POST フィールドをサポートします。

レスポンスの内容

成功した場合、このメソッドは get_plan と同じレスポンス形式を使用して更新されたテスト計画を返します。

レスポンス コード

update_plan_entry

テスト計画に含まれる 1 つまたはそれ以上のテスト ランのグループを更新します (部分的な更新がサポートされています。つまり、特定のフィールドのみを送信して更新できます)。

POST index.php?/api/v2/update_plan_entry/{plan_id}/{entry_id}

パラメーター

リクエスト ボディ

レスポンスの内容

成功した場合、このメソッドは、get_plan の entries フィールドと同じレスポンス形式を使用して、テスト ランを含む新しいテスト計画エントリを返します。エントリのリストではなく単一のエントリを返します。

レスポンス コード

update_run_in_plan_entry

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

パラメーター

リクエスト ボディ

リクエストの例

テスト計画エントリ内の設定を使用するランを更新する方法を示す次の例も参照してください。

{
    "include_all": false,
    "case_ids": [1,2,4]
}

レスポンス コード

close_plan

既存のテスト計画を閉じて、そのテスト ランと結果をアーカイブします。

POST index.php?/api/v2/close_plan/{plan_id}

パラメーター

レスポンスの内容

成功した場合、このメソッドは get_plan と同じレスポンス形式を使用してクローズされたテスト計画を返します。

レスポンス コード

delete_plan

POST index.php?/api/v2/close_plan/{plan_id}

パラメーター

レスポンス コード

delete_plan_entry

テスト計画から 1つまたはそれ以上のテスト ランを削除します。

POST index.php?/api/v2/delete_plan_entry/{plan_id}/{entry_id}

パラメーター

レスポンス コード

delete_run_from_plan_entry

テスト計画エントリからテスト ランを削除します。

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

パラメーター

レスポンス コード