API: 計画

テスト計画に関する情報を取得したり、テスト計画を作成または変更するには、次の API メソッドを使用します。

get_plan

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

GET index.php?/api/v2/get_plan/:plan_id

レスポンスの内容

典型的なレスポンスについては、次のサンプルを参照してください。

{
    "assignedto_id": null,
    "blocked_count": 2,
    "completed_on": null,
    "created_by": 1,
    "created_on": 1393845644,
    "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,
    "description": null,
    "entries": [
        {
            "id": "3933d74b-4282-4c1f-be62-a641ab427063",
            "description": null,
            "include_all": true,
            "name": "File Formats",
            "runs": [
                {
                    "assignedto_id": 6,
                    "blocked_count": 0,
                    "completed_on": null,
                    "config": "Firefox, Ubuntu 12",
                    "config_ids": [
                        2,
                        6
                    ],
                    "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,
                    "description": null,
                    "entry_id": "3933d74b-4282-4c1f-be62-a641ab427063",
                    "entry_index": 1,
                    "failed_count": 2,
                    "id": 81,
                    "include_all": false,
                    "is_completed": false,
                    "milestone_id": 7,
                    "name": "File Formats",
                    "passed_count": 2,
                    "plan_id": 80,
                    "project_id": 1,
                    "retest_count": 1,
                    "refs": "RF-1, RF-2",
                    "suite_id": 4,
                    "untested_count": 3,
                    "url": "http://<server>/testrail/index.php?/runs/view/81"
                },
                {
                    ..
                }
            ],
            "refs": "RF-1, RF-2",
            "suite_id": 4
        }
    ],
    "failed_count": 2,
    "id": 80,
    "is_completed": false,
    "milestone_id": 7,
    "name": "System test",
    "passed_count": 5,
    "project_id": 1,
    "retest_count": 1,
    "untested_count": 6,
    "url": "http://<server>/testrail/index.php?/plans/view/80"
}

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

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

レスポンス コード

get_plans

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

GET index.php?/api/v2/get_plans/:project_id

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

リクエスト フィルター

以下のフィルターを適用できます。

レスポンスの内容

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

[
    {
        "id": 1,
        "name": "System test 1", 
        ..
    },
    {
        "id": 2,
        "name": "System test 2",
        ..
    },
    ..
]

新しいレスポンスの内容

レスポンスにはテスト計画の配列が含まれます。リスト内の各テスト計画の形式は、レスポンスには 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

リクエスト フィールド

以下の POST フィールドがサポートされています。

リクエストの例

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

{
    "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 は テスト計画の設定(configs) もサポートしています。

{
    "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

リクエスト フィールド

以下の POST フィールドがサポートされています。

リクエストの例

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

{
    "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

テスト計画エントリに新しいテスト ランを追加します (設定を使用)。

TestRail 6.4 以降が必要です。

POST index.php?/api/v2/add_run_to_plan_entry/:plan_id/:entry_id

リクエスト フィールド

以下の POST フィールドがサポートされています。

リクエストの例

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

{
       "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

リクエスト フィールド

以下の POST フィールドがサポートされています。

レスポンスの内容

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

レスポンス コード

update_run_in_plan_entry

計画エントリ内の設定を使用するランを更新します。

TestRail 6.4 以降が必要です。

POST index.php?/api/v2/update_run_in_plan_entry/:run_id

リクエスト フィールド

以下の POST フィールドがサポートされています。

リクエストの例

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

{
      "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/delete_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

レスポンス コード