TestRail API の概要

TestRail API を使用すると、さまざまなツール、フレームワーク、およびサードパーティ製アプリケーションと統合できます。たとえば、多くのユーザーは API を使用して自動テストと統合し、テスト結果を TestRail に送信しています。API はほかにもさまざまなタスクに使用できます。以下にいくつかの例を挙げます。

API は HTTP ベースであるため、ほとんどどのようなフレームワーク、プログラミング言語、およびツールからも使用できます。API を介して TestRail にデータを送信するには、単純な POST リクエストを使用します。データの要求は GET リクエストを介して行われます。すべてのリクエストとレスポンスは JSON 形式と UTF-8 エンコードを使用します。

API は TestRail の一部であり、TestRail 管理エリアの [管理] > [サイト設定] > [API] で有効にできます。

API が使用できる典型的なシナリオ:

- 自動テストからテスト結果を送信する
- レガシーシステムからテストケースを移行する
- 異なるシステム間でテストケースを同期させる
- プログラムでテストランと計画を作成する
- 統合のために情報を照会する

API リファレンスを読み進める前に、テストケース、テストラン、テスト結果、テストスイートなどの TestRail のエンティティについて理解してください。それには、TestRail ユーザーガイドの入門トピックやベストプラクティスを参照してください。

API offset および limit パラメーター

TestRail には多数の一括 API エンドポイントが用意されており、複数のテストケース、テスト、その他の TestRail エンティティに関する情報を 1 回の GET リクエストで取得できます。これにより、TsetRail からの情報取得がより効率的になるだけでなく、プロセスがシンプルになり、TestRail API に送信される全体的なリクエスト数が抑制されます。

制限

一括 GET エンドポイント (たとえば get_cases、get_runs、get_results_for_case など) を使用する場合、返されるレコード数のデフォルト値は 250 です。しかし、limit パラメーターを使用してさらにレコード数を少なくすることもできます。

たとえば、get_runs API メソッドを使用し、project_id が 3 のプロジェクトの最初の 3 つのテストランだけを取得したい場合、次のようなリクエストを送信します。

GET https://{hostname}/index.php?/api/v2/get_runs/3&limit=3

{hostname} は実際の TestRail の URL に置き換える必要があります。

次のようなレスポンスが返されます。

{
  "offset": 0,
  "limit": 3,
  "size": 3,
  "_links": {
    "next": "/api/v2/get_runs/3&limit=3&offset=3",
    "prev": null
  },
  "runs": [
    {
      "id": 1,
      ..
    },
    {
      "id": 2,
      ..
    },
    {
      "id": 3,
      ..
    }
  ]
}

limit パラメーターには 1 以上 250 以下の整数を指定できます。250 はレスポンスで許可される最大のレコード数です。250 の制限を超える値を設定した場合、次のエラーが返されます。

{
  "error": "Field :limit is too large (maximum 250)."
}

オフセット

offset パラメーターは、次の結果セットに移動するために使用します。たとえば、get_cases エンドポイントを使用してすべてのテストケースを取得しようとし、limit 値を設定しなかった場合、デフォルトの最大結果件数は 250 であるため、リクエストは最大で 250 件のテストケースレコードを返します。

サンプル出力:

{
  "offset": 0,
  "limit": 250,
  "size": 250,
  "_links": {
    "next": "api/v2/get_cases/3&limit=250&offset=250",
    "prev": null
  },
  "cases": [
    {
      "id": 2604,
      "title": "Add watermark to document and verify print output",
      "section_id": 268,
      "template_id": 1,
      "type_id": 7,
      "priority_id": 4,
      "milestone_id": null,
      "refs": null,
      "created_by": 2,
      "created_on": 1631664168,
      "updated_by": 2,
      "updated_on": 1631664168,
      "estimate": null,
      "estimate_forecast": "8m 40s",
      "suite_id": 32,
      "display_order": 1,
      "is_deleted": 0,
      "custom_automation_type": 0,
      "custom_automation_status": null,
      "custom_preconds": null,
      "custom_steps": null,
      "custom_expected": "Etiam massa dolor, ornare sit amet, lacinia nec, bibendum ut, magna.\n\t\t\n* Nam feugiat, eros at commodo dictum,\n* Felis libero varius orci, in vulputate\n* Massa turpis scelerisque diam.\n* Nunc et felis est. Phasellus laoreet nibh vel augue\n* Faucibus at varius est pretium.\n\nQuisque pellentesque **mauris**.",
      "custom_steps_separated": null,
      "custom_mission": null,
      "custom_goals": null
    },
    ..
  ]
}

プロジェクトに 250 件を超えるテストケースが存在する場合、別の GET リクエストを送信して次のレコードセットを取得する必要があります。このとき、次のように offset パラメーターに 250 を設定します。

GET https://{hostname}/index.php?/api/v2/get_cases/3&offset=250

上記の例で get_cases を使用していたため、次の 250 件のテストケースが返されます。

注意：一括 GET リクエストで検索できるレコードは、エンティティの ID 値の順にソートされます。たとえば、get_cases はケースの ID の昇順にテストケースを返します。

次のレコードセットを処理するには、前のレスポンスで返された _links オブジェクトの next 値を使用するか、オフセットの末尾に到達するまで手動で offset の数値を繰り返すこともできます。

利用可能なレコードの末尾に到達したことを知るには、次の 2 つの方法があります。現在のリクエストに検索しているテーブルの最終レコードが含まれている場合、レスポンスは _links オブジェクトの next 値に null を返します。また、利用可能なレコード数より大きいオフセット値を指定すると、空の配列が返されます。例:

GET https://{hostname}/index.php?/api/v2/get_cases/3&offset=10000000

サンプル出力:

{
  "offset": 10000000,
  "limit": 250,
  "size": 0,
  "_links": {
    "next": null,
    "prev": "/api/v2/get_cases/3&offset=9999750&limit=250"
  },
  "cases": []
}

これを利用して、自動処理の中でレコードの末尾に到達したかどうかを判断できます。

API リファレンスの表記規則

TestRail API マニュアルは、いくつかの規則に従って、API リクエスト URL 中で置き換える必要がある変数パラメーターを示すほか、一部のレスポンスのサンプルを省略して表示します。

1.波括弧で囲まれた変数

API リクエスト内の波括弧 {} で囲まれた値を実際のパラメーターに置き換えます。

例えば、API リクエスト GET index.php?/api/v2/get_project/{project_id} の {project_id} を実際のプロジェクト ID 値に置き換えます。

したがって、プロジェクト ID が 10 の場合、リクエストは GET index.php?/api/v2/get_project/10 となります。

2.レスポンスコード例の省略

.. コードブロック中の .. はレスポンスの省略を示します。単に見た目のために使用されており、TestRail API の実際のレスポンスの内容のとおりではありません。API リファレンス内の例でレスポンスが占めるスペースを短くし、ドキュメントを読みやすくするためだけに使用されています。

たとえば、下の get_cases 使用例を参照してください。

{
  "offset": 0,
  "limit": 250,
  "size": 250,
  "_links":{
    "next": "/api/v2/get_cases/1&limit=250&offset=250",
    "prev": null
  },
  "cases":[
    { "id": 1, "title": "..", .. },
    { "id": 2, "title": "..", .. },
    ..
  ]
}

API 呼び出しの ID 変数を見つける方法

多くの TestRail API エンドポイントは、リクエスト URL に ID 値を追加して特定のプロジェクト、ケース、テストランなどを指定するよう要求します。以下のセクションでは、TestRail UI で特定の ID を探し、API リクエストのパラメーターとして使用する方法を説明します。

プロジェクト ID – project_id

1. TestRail のダッシュボードに移動します。
2. リストからプロジェクトを選択します。
3. URL を確認します。末尾の数字がプロジェクト ID です。
4. あるいは、プロジェクト名の隣にある ID を確認することもできます (API リクエストでプロジェクト ID を使用する場合は文字 ‘P’ を削除してください)。

たとえば、API リクエスト GET index.php?/api/v2/get_project/{project_id} の {project_id} を 3 に置換します。

したがって、リクエストは GET index.php?/api/v2/get_project/3 のようになります。

ケース ID – case_id

1. TestRail のダッシュボードに移動します。
2. リストからプロジェクトを選択します。
3. [テストケース] タブに移動します。
4. リストからテストケースを選択します。
5. URL を確認します。末尾の数字がテストケース ID です。あるいは、テストケース名の隣にある ID を確認することもできます。API リクエストでプロジェクト ID を使用する場合は文字 ‘C’ を削除してください

添付ファイル ID – attachment_id

1. TestRail のダッシュボードに移動します。
2. リストからプロジェクトを選択します。
3. [テストケース] タブに移動します。
4. リストからテストケースを選択します。
5. 添付ファイルを追加します。

TestRail 7.1 より前のバージョンの場合 – 添付ファイルを右クリックし、[Copy image address] をクリックします。URL 内の添付ファイル ID を使用します。

TestRail バージョン 7.1 以降の場合 – 添付ファイルをクリックします。[添付ファイルの詳細] 画面の [URL] から英数字の ID をコピーします。

マイルストーン ID – milestone_id

1. TestRail のダッシュボードに移動します。
2. リストからプロジェクトを選択します。
3. [マイルストーン] タブに移動します。
4. リストからマイルストーンを選択します。
5. URL を確認します。末尾の数字がマイルストーン ID です。あるいは、マイルストーン名の隣にある ID を確認することもできます。API リクエストでプロジェクト ID を使用する場合は文字 ‘M’ を削除してください

テスト計画 ID – plan_id

1. TestRail のダッシュボードに移動します。
2. リストからプロジェクトを選択します。
3. [テストランと結果] タブに移動します。
4. リストからテスト計画を選択します。
5. URL を確認します。末尾の数字がテスト計画 ID です。あるいは、テスト計画名の隣にある ID を確認することもできます。API リクエストでプロジェクト ID を使用する場合は文字 ‘R’ を削除してください

テストラン ID – run_id

1. TestRail のダッシュボードに移動します。
2. リストからプロジェクトを選択します。
3. [テストランと結果] タブに移動します。
4. リストからテストランを選択します。
5. URL を確認します。末尾の数字がテストラン ID です。あるいは、テスト計画名の隣にある ID を確認することもできます。API リクエストでプロジェクト ID を使用する場合は文字 ‘R’ を削除してください

API offset および limit パラメーター

制限

オフセット

API リファレンスの表記規則

1.波括弧で囲まれた変数

2.レスポンス コード例の省略

API 呼び出しの ID 変数を見つける方法

プロジェクト ID – project_id

ケース ID – case_id

添付ファイル ID – attachment_id

マイルストーン ID – milestone_id

テスト計画 ID – plan_id

テスト ラン ID – run_id

目次

2.レスポンスコード例の省略

テストラン ID – run_id