ページを選択

セクション

セクションに関する情報を取得したり、セクションを作成または変更するには、次の API メソッドを使用します。セクションは、テストスイート内のテストケースをグループ化して整理するために使用されます。

get_section

既存のセクションを返します。

GET index.php?/api/v2/get_section/{section_id}

パラメーター

名前 タイプ 必須 説明
section_id integer true セクションの ID

レスポンスの内容

典型的なレスポンスについては、下記を参照してください。

{
    "depth": 0,
    "description": null,
    "display_order": 1,
    "id": 1,
    "name": "Prerequisites",
    "parent_id": null,
    "suite_id": 1
}

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

名前 タイプ 説明
depth integer テスト スイートのセクション階層のレベル
description string セクションの説明
display_order integer テスト スイート内での順序
id integer セクションの一意の ID
parent_id integer テスト スイート内での親セクションの ID
name string セクションの名前
suite_id integer テストセクションが所属するテスト スイートの ID

depthdisplay_order および parent フィールドによってテスト スイート内のセクションの階層が定義されます。ルート レベルにあるすべてのセクションの depth フィールドは 0 であり、すべての子セクションの値は 1 以上です。そのため、depth フィールドの値は、セクション階層内でのレベルに似ています。例として get_sections も参照してください。

レスポンス コード

ステータス コード 説明
200 成功。セクションがレスポンスの一部として返されます
400 無効または不明なセクション
403 プロジェクトにアクセスできない
429 TestRail Cloud のみ – リクエストが多すぎます

get_sections

プロジェクトとテスト スイートのセクションのリストを返します。

GET index.php?/api/v2/get_sections/{project_id}&suite_id={suite_id}

パラメーター

名前 タイプ 必須 説明
project_id integer true プロジェクトの ID
suite_id integer 説明を参照 テスト スイートの ID (プロジェクトがシングル スイート モードで動作している場合はオプション)

リクエスト フィルター

リクエスト URL の query パラメーターを使用して、以下のフィルターを適用できます。

名前 タイプ 説明
limit integer レスポンスが返すセクションの数 (デフォルトのレスポンスのサイズは 250) (TestRail 6.7 以降が必要)
offset integer セクションのカウントを開始する位置 (オフセット) (TestRail 6.7 以降が必要)

レスポンスの内容

典型的なレスポンスについては、下記を参照してください。

{
    "offset": 0,
    "limit": 250,
    "size": 23,
    "_links": {
        "next": null,
        "prev": null
    },
    "sections": [
        {
            "depth": 0,
            "display_order": 1,
            "id": 1,
            "name": "Prerequisites",
            "parent_id": null,
            "suite_id": 1
        },
        {
            "depth": 0,
            "display_order": 2,
            "id": 2,
            "name": "Documentation & Help",
            "parent_id": null,
            "suite_id": 1
        },
        {
            "depth": 1,  // A child section
            "display_order": 3,
            "id": 3,
            "name": "Licensing & Terms",
            "parent_id": 2,  // Points to the parent section
            "suite_id": 1
        }
    ]
}

含まれるフィールドの詳細については get_section も参照してください。

レスポンス コード

ステータス コード 説明
200 成功。セクションがレスポンスの一部として返されます
400 無効または不明なプロジェクトまたはテスト スイート
403 プロジェクトにアクセスできない
429 TestRail Cloud のみ – リクエストが多すぎます

add_section

新規セクションを作成します。

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

パラメーター

名前 タイプ 必須 説明
project_id integer true プロジェクトの ID

リクエスト ボディ

POST リクエスト ボディでは以下のフィールドがサポートされています。

名前 タイプ 必須 説明
description string false セクションの説明
suite_id integer 説明を参照 テスト スイートの ID (プロジェクトがシングル スイート モードで動作している場合は無視され、その他の場合は必須)
parent_id integer false 親セクションの ID (セクション階層の構築に使用される)
name string true セクションの名前

リクエストの例

空のセクション (以前に作成したセクションを親として) を作成する方法を示す次の例も参照してください。
{
    "suite_id": 5,
    "name": "This is a new section",
    "parent_id": 10
}

セクションを追加したら、テストケース を追加できます。

レスポンスの内容

成功した場合、このメソッドは get_section と同じレスポンス形式を使用して新しいセクションを返します。

レスポンスコード

ステータス コード 説明
200 成功。セクションが作成され、レスポンスの一部として返されます
400 無効または不明なプロジェクトまたはテスト スイート
403 セクションを追加する権限、またはプロジェクトへのアクセス権がありません
429 TestRail Cloud のみ – リクエストが多すぎます

move_section

TestRail 6.5.2 以降が必要です。

セクションを別のスイートまたはセクションに移動します。

POST index.php?/api/v2/move_section/{section_id}

パラメーター

名前 タイプ 必須 説明
section_id integer true セクションの ID

リクエスト ボディ

POST リクエスト ボディでは以下のフィールドがサポートされています。

名前 タイプ 説明
parent_id integer 親セクションの ID (ルートに移動する場合は null にします)。同一プロジェクトおよびスイート内である必要があります。移動対象セクションの直接の子にはできません
after_id integer セクションを挿入する直前のセクションの ID (null でも可)

レスポンスコード

ステータス コード 説明
200 成功。セクションが移動され、レスポンスの一部として返されます
400 無効または不明な section_id、parent_id、または after_id です
403 セクションを追加する権限、またはプロジェクトへのアクセス権がありません
429 TestRail Cloud のみ – リクエストが多すぎます

update_section

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

POST index.php?/api/v2/update_section/{section_id}

パラメーター

名前 タイプ 必須 説明
section_id integer true セクションの ID

リクエスト ボディ

POST リクエスト ボディでは以下のフィールドがサポートされています。

名前 タイプ 説明
description string セクションの説明
name string セクションの名前

リクエストの例

既存のセクションの名前を更新する方法を示す次の例も参照してください。

{
  "name": "A better section name"
}

レスポンスの内容

成功した場合、このメソッドは get_section と同じレスポンス形式を使用して更新されたセクションを返します。

レスポンス コード

ステータス コード 説明
200 成功。セクションが更新され、レスポンスの一部として返されます
400 無効または不明なセクション
403 セクションを更新する権限、またはプロジェクトへのアクセス権がありません
429 TestRail Cloud のみ – リクエストが多すぎます

delete_section

削除したセクションを元に戻すことはできず、関連するすべてのテスト ケースのほか、アクティブなテストおよびテスト結果、つまりまだクローズされていない (アーカイブされていない) テストおよびテスト結果も削除されます。

既存のセクションを削除します。

POST index.php?/api/v2/delete_section/{section_id}

パラメーター

名前 タイプ 必須 説明
section_id integer true セクションの ID

Soft パラメーター

soft パラメーターを省略した場合、または soft=0 をサブミットした場合、セクションとそのテスト ケースは削除されます。

If soft=1 の場合、影響を受けるテスト、テスト ケースなどの数に関するデータを返します。

soft=1 を設定すると、TestRail UI のエンティティは実際には削除されず、出力は API レスポンスにだけ表示されます。

レスポンス コード

ステータス コード 説明
200 成功。セクションは削除されました
400 無効または不明なセクション
403 セクションまたはテスト ケースを削除する権限がない、またはプロジェクトへのアクセス権がない
429 TestRail Cloud のみ – リクエストが多すぎます