Webhook

Webhook を使用すると、TestRail で発生したイベントに基づいて他のアプリケーションにリアルタイムの情報を提供できます。

更新された情報を取得するには頻繁にデータを問い合わせする必要がある典型的な API リクエストとは異なり、Webhook を使用すると、新規テスト ケースの追加、新規テスト ランの作成、新規テスト結果のアップロードなどの特定のイベントが TestRail で発生したときに外部のシステムやアプリケーションに通知とペイロードを送信することができます。これにより、API を備えた任意のアプリケーションと TestRail を統合し、テスト サイクルの重要なプロセスをスピードアップできるほか、チーム全体のテスト アクティビティの進捗をいっそう可視化できます。

Webhook の追加方法

Webhook を追加する方法は 2 つあります。グローバルに追加する方法 (TestRail インスタンス内のすべてのプロジェクトでトリガーされる) と特定のプロジェクト用に追加する方法です。

すべてのプロジェクト用に Webhook をセットアップするには、[管理] に移動し、[統合] をクリックします。

[Webhook] タブを選択します。ここで新規 Webhook の追加または既存の Webhook の編集を行うことができます。

新規 Webhook をセットアップするには、[Webhook の追加] をクリックします。次のウィンドウが表示されます。このウィンドウで名前を追加し、ペイロード URL、メソッド、コンテンツ タイプ、ヘッダーおよびペイロードなどのキー情報を指定できます。

• • Webhook に分かりやすい名前を付けます。
  • ペイロード URL を追加します: この URL は、Webhook がトリガーされたときにコンテンツが送信される URL です。
  • メソッド: POST、GET、PUT、PATCH または DELETE を選択します。
  • コンテンツ タイプを選択します。選択肢は次のとおりです。
    • application/json
    • application/x-www-form-urlencoded
    • application/xml
    • text/xml
    • text/plain
  • 必要なその他のヘッダーを追加します。TestRail のすべての Webhook には、灰色で表示されたデフォルトのヘッダーがありますが、黒で表示されるカスタム ヘッダーを追加することもできます。
  • Webhook にペイロードを追加します。コンソールを使用してほぼどんなペイロードでも構成して送信できるよう、ペイロード フィールドは柔軟に設計されています。(詳細については下のペイロードを参照してください)

• • 必要に応じて、Webhook に認証用のシークレットを設定することもできます。シークレットは Webhook のヘッダーに含められます。
  • イベントでは、オプションの左にあるチェックボックスをオンにして Webhook をトリガーするイベントを選択します。
    • 1 つの Webhook をトリガーする複数のイベントを選択できます。
  • プロジェクトでは、選択したイベントで Webhook をトリガーするプロジェクトのチェックボックスをオンにします。
  • 最後に、[アクティブ] チェックボックスをオンまたはオフにして Webhook をアクティベートまたはデアクティベートできます。
  • 準備ができたら [設定の保存] をクリックします。

Webhook を設定したら、[Webhook の追加] ダイアログの右上にある [テスト] ボタンを使用して Webhook の設定をテストできます。

特定のプロジェクトに Webhook を追加する

[プロジェクトの編集] ページから特定のプロジェクトに Webhook を追加することもできます。 [プロジェクトの編集] ページを開くには、[管理] にアクセスし、右サイドバーのメニューの [プロジェクト] をクリックしてから、えんぴつのアイコンをクリックします。または、すでに特定のプロジェクトの [プロジェクトの概要] ページを開いている場合は、右上隅の [編集] をクリックします。[プロジェクトの編集] ページに移動したら、[Webhook] タブをクリックしてプロジェクト固有の Webhook を追加または編集します。

Webhook のテストと監査

新規 Webhook を追加する場合、保存する前にテストを行い、リクエスト、ペイロード、レスポンスを確認するのはよいアイデアです。[Webhook の追加] ページで最初に設定するときにテストできるほか、後で既存の Webhook をテストすることもできます。Webhook の設定でセットアップ済みの Webhook によってトリガーされたリクエストの履歴を参照することもできます。

すでに作成済みの Webhook をテストしたり、アクティビティの履歴を参照したりするには、再び [管理] タブの [統合] に移動し、[Webhook] タブを表示します。ページ右側のテスト セクションを表示します。

ここに最近のデリバリーと日付のログが表示されます。最近のデリバリーをクリックすると、[Request] タブで、デリバリーをトリガーした特定のイベントでヘッダーやペイロードに含められた情報を参照できます。

[Response] タブでは、Webhook を受信した外部アプリケーションから TestRail に返されたレスポンスのステータス コードや、レスポンスのヘッダーおよびペイロードを参照することができます。

Webhook のイベント

TestRail で Webhook をセットアップする際、Webhook をトリガーするイベントを選択できます。現在、Webhook をトリガーするイベントとして選択できるイベントは次のとおりです。

イベント	説明
計画作成時	このイベントをオンにすると、指定されたプロジェクトで新規テスト計画が作成されたときに Webhook がトリガーされます。
計画更新時	このイベントをオンにすると、指定されたプロジェクトでテスト計画が更新されたときに Webhook がトリガーされます。
計画エントリ作成時	このイベントをオンにすると、指定されたプロジェクトでテスト計画エントリが作成されたときに Webhook がトリガーされます。
計画エントリ更新時	このイベントをオンにすると、指定されたプロジェクトでテスト計画エントリが更新されたときに Webhook がトリガーされます。
テスト ラン作成時	このイベントをオンにすると、指定されたプロジェクトでテスト ランが作成されたときに Webhook がトリガーされます。
テスト ラン更新時	このイベントをオンにすると、指定されたプロジェクトでテスト ランが更新されたときに Webhook がトリガーされます。
ケース作成時	このイベントをオンにすると、指定されたプロジェクトでテスト ケースが作成されたときに Webhook がトリガーされます。
ケース更新時	このイベントをオンにすると、指定されたプロジェクトでテスト ケースが更新されたときに Webhook がトリガーされます。
テスト結果作成時	このイベントをオンにすると、指定されたプロジェクトでテスト結果が作成されたときに Webhook がトリガーされます。
レポート作成時	このイベントをオンにすると、指定されたプロジェクトでレポートが作成されたときに Webhook がトリガーされます。
すべて	このチェックボックスをオンにすると、上記のいずれかのイベントが発生するたびに Webhook がトリガーされます。

ペイロードにさまざまな変数を追加して、Webhook により多くのコンテキストやデータを追加することができます。下の一覧を参照してください。

ペイロード

コンソールで利用可能なペイロード フィールドは、ほぼどのようなペイロードでも構成し送信することを可能にします。次のサンプルは、Slack で何ができるかを確認するための JSON ペイロード構造の例です。

{
  "text": "%event_creator% created a new test case:",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*%event_creator% created a new test case:*"
      }
    },
    {
      "type": "divider"
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*<%url%|%name%>* \n Priority: %case_priority% \n Type: %case_type%"
      }
    }
  ]
}

Webhook が実行されると、結果として次のようなメッセージが Slack に表示されます。

ペイロード変数

ペイロードを補完するさまざまな変数を利用できます。現在、Webhook で利用可能な変数は以下のとおりです。

変数	タイプ	説明
%assigned_to%	text	エンティティが割り当てられたユーザー名です。
%case_priority%	text	テスト ケース イベントに関する Webhook ペイロードがトリガーされた場合の優先度フィールドのステータスです (例: “High”、“Medium”、“Low”)。
%case_type%	text	イベント ペイロードがトリガーされたテスト ケースのタイプ (指定されている場合) です (例: “Functional”、 “Smoke”、“Regression” など)
%completed_on%	timestamp	マイルストーン/計画/ランの完了時 (‘closed’ とマークされた時) のタイムスタンプです。
%config%	text	エンティティ設定名です。(テスト計画エントリのみ)
%custom_x%	object/array	テスト ケース イベントがトリガーされた場合、すべてのカスタム テスト ケース フィールドを返します。フィールドは先頭が “custom_” です (つまり、“x” がカスタム フィールド名に置き換えられます)。 (例: ‘Version number’というカスタム フィールドがある場合、変数は %custom_version_number% とします)。
%description%	text	イベントが Webhook ペイロードをトリガーするエンティティの説明です (例: マイルストーンの説明やテスト ランの説明)。
%due_on%	timestamp	マイルストーンの完了が予定された日付です。(マイルストーンのみ)
%entity_created%	timestamp	イベントがトリガーされたエンティティが作成された日時です。
%entity_creator%	text	イベントがトリガーされたエンティティを作成したユーザー名です (例: テスト ケースを最初に作成したユーザー名)。
%estimate%	integer	テスト ケース イベントに関連する Webhook ペイロードがトリガーされた場合、テスト ケースの予測フィールドです。
%event_created%	timestamp	Webhook が発生した日時です。
%event_creator%	text	Webhook イベントを作成しトリガーしたユーザー名です。
%event_type%	text	Webhook ペイロードをトリガーしたイベントのタイプです (例: “Plan created”、“Case updated”、“Report created” など)
%id%	integer	イベントが Webhook ペイロードをトリガーしたエンティティの ID です (例: ケース ID ラベル “C117” の場合 “117”、ラン ID ラベル “R42” の場合 “42”)。
%is_deleted%	boolean	ケース、ラン、計画、マイストーンが削除済みとしてマークされているかどうかを示します。
%milestone_id%	integer	エントリにマイルストーンが関連付けられている場合、関連するマイルストーンの一意の ID です。
%more_info%	text	イベントがトリガーされたエンティティに関する詳細情報を取得するために呼び出すことができる API エンドポイント (例: “/api/v2/get_runs/3)
%name%	text	イベントが Webhook ペイロードをトリガーするエンティティの名前またはタイトルです。
%project_id%	integer	エンティティが関連する TestRail プロジェクトです。
%refs%	text	Webhook エンティティの「参照」フィールドに保存された情報です (例: “TR-71, TR-72”)。
%section_id%	integer	テスト ケースに関連付けられたセクションの識別子です。
%stats%	object/array	計画、ラン、マイルストーンに関連する結果メトリクスの完全なセットです (passed_count、blocked_count、untested_count、retest_count、failed_count、custom_status_n_count)。
%suite_id%	integer	Webhook エンティティのサブスクリプションに関するテスト スイートの識別子です。
%template_name%	text	テスト ケース イベントに関する Webhook ペイロードがトリガーされた場合に使用されたテスト ケース テンプレートです (例: “Test Case Steps”、“Exploratory Session”)。
%url%	text	TestRail でエンティティを参照するためのインスタンス URL です (例: “https://allboard.testrail.com/index.php?/milestones/view/61″)。
%secret%	text	Webhook の [シークレット] フィールドに入力されたトークンです (入力されている場合)。

ペイロードに変数フィールドを追加すると、Webhook がトリガーされた時、下の図のように対応する TestRail データが挿入されます。

オンプレミス インストール (TestRail Server)

TestRail 7.5 の Server 版をインストールする場合、新しい Webhook 機能に関するオプションの追加手順があります。インストールまたはアップグレード手順を実行中に、発信 Webhook ペイロードを処理するための RabbitMQ メッセージ キュー サーバーを設定する追加手順が提示されます。

この目的でメッセージ キューを使用し、TestRail Server のインストールまたはアップグレード時に追加する場合、次の情報が必要です。

• • The RabbitMQ サーバー名
  • The RabbitMQ ポート番号 (デフォルトでは 5672)
  • The RabbitMQ ユーザー名およびパスワード
  • オプションとして RabbitMQ 証明書および秘密鍵

メッセージ キューの設定は、コンソールの [管理] > [サイト設定] にもあり、追加または更新が可能です。