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 レート制限

すべてのユーザーに最適なパフォーマンスを保証するため、TestRail Cloud では、API はレート制限されており、リクエストが絞られる場合があることに注意してください。また、TestRail は 429 Too Many Requests レスポンスを返す場合があり、ユーザーはこれに対処する必要があります。

TestRail Cloud でレート制限を避けるには、一括 API エンドポイントを使用したり (add_results_for case ではなく add_results_for_cases を使用するなど)、API 呼び出しの間に遅延時間を設けることを検討してください。

注意：TestRail Server には API レート制限は組み込まれていません。

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} を 5 に置換します。

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

ケース 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 link 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 レート制限

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