メインコンテンツへスキップ

Webhook

Eva Ferreira
  • 更新

mabl では、テストの開始前または完了後に、実行の詳細を Webhook へ送信するようにワークスペースを設定できます。これは、CI/CD ワークフロー内で、mabl のテストにおける特定のステータスや結果にアクションを連結したい場合に役立ちます。例えば、次のようなケースがあります:

  • mabl テストが実行される前にクラウド内でリソースをセットアップする
  • mabl のテスト実行完了後にクラウド上のリソースをクリーンアップする

この記事では、mabl のウェブフックについて詳しく概要を説明します。

Webhook設定

mabl アプリから Webhook を設定できます: ワークスペース > Webhook。新しい webhook を追加するには、+ 新規Webhook ボタンをクリックして、次の詳細を入力してください:

  • Webhook名 - 複数の webhook に mabl の結果を送信する場合は、このフィールドを使用して目的を識別します。
  • ベースURL - mabl は、保留中または完了した実行について説明する JSON ペイロードを付けてこの URL を呼び出します。
  • 厳格なSSL検証（任意） - mabl は、すべての接続が有効なSSL証明書を使用することを保証します。自己署名証明書を使用しているCIサーバーを使っている場合は、厳格なSSL検証を無効にできます。

mabl テストの実行前や実行後にWebhookを送信するよう設定できます：

  • 事前実行の呼び出し - テスト実行が始まる前に、mabl はトリガーされたテストの情報を webhook エンドポイントに送信します。任意で、webhook の URL からの成功レスポンスを必須にできます。エンドポイントが成功ステータスにならない場合、テストは失敗として扱われます。
  • 実行後に呼び出し - すべてのテスト実行が完了した後、mabl はテスト実行に関する情報を送信します。実行後の Webhook では、mabl が Webhook に投稿するタイミングを指定します。〈on failure〉（失敗した実行）および/または〈on success〉（成功した実行）。

停止された実行

ステータスが停止済みのテストでは、実行後のWebhookはトリガーされません。

トラブルシューティング

Webhook が失敗する場合に遭遇したら、よくある課題と、そのトラブルシューティングのための提案を以下にまとめました。

  • ファイアウォール - webhook リクエストは mabl の固定 IP アドレスから送信されます。webhook の URL がファイアウォールの内側にある場合は、mabl の固定 IP アドレスを追加して、ファイアウォールの許可リストに登録してください。
  • TIMEOUT エラー - 各 webhook は 60 秒以内に完了する必要があります。完了しない場合、TIMEOUT エラーで失敗します。
  • 401 または 403 エラー - Webhook の URL が 401 または 403 エラーを返す場合、mabl が到達できるように、Webhook を公開設定にしてください。
  • Basic認証 - Webhook に Basic認証 のクレデンシャルを送る必要がある場合、1 つの方法はクレデンシャルを Webhook の URL 自体にエンコードすることです。たとえば、https://username:password@example.com のようにします。

Webhookペイロード

Webhookイベントがトリガーされると、Webhookエンドポイントは、実行された特定のプランおよびテストのステータス、結果、詳細に関する情報を含むJSONペイロードを受信します。特定のワークスペースのすべてのWebhookは並列で発火します。

Webhookのペイロードは編集できません。

Webhookのペイロードには、次の属性が含まれます。

属性 説明
“success” 「success」属性の値は、状態が「terminated」「cancelled」「failed」のいずれかになるまで「true」です。
“status” 考えられるステータスの状態には、「queued」、「scheduling」、「scheduled」、「succeeded」、「failed」、「cancelled」、「completed」が含まれます。
“status_cause” 「status_cause」のデフォルト値は null です。テストがユーザーによる終了、テストのタイムアウト、その他のエラーなど、想定外の方法で終了した場合。
“plan” プラン名やラベルを含むプランに関する情報。アドホックのテスト実行にはプランのペイロードがありません。
“plan_execution”

そのプラン実行のステータスに関する情報（ステータス、ID、利用可能な場合はリビジョンを含む）。

アドホックテスト実行には、実際のプランに基づいていないにもかかわらず、「plan_execution」(プラン実行とも呼ばれます)に関する情報が含まれています。この情報は「合成」されたものであり、mabl バックエンドの一貫性を維持するために含まれています。
“journeys” テスト名やラベルを含む、テストに関する情報。
“journey_executions” 特定のテスト実行のステータスに関する情報。開始時刻と終了時刻、関連するテストケースIDを含みます。
“href” 特定のプラン、プラン実行、テスト、またはテスト実行のAPIエンドポイント。
“results_href” mabl アプリの特定のテスト実行の結果 URL。
“tags” 「tag」属性は、スモークテストやリンククローラーのテストなど、mabl が自動生成するテストを識別するために使用します。タグはユーザーが編集できません。
“test_cases”

Zephyr や TM4J などの外部の テストケース管理ツール に mabl のテストを関連付けている場合、ペイロードにはそれらのテストのテストケース ID が含まれます。

テストケース管理にXrayを使用している場合は、mablテスト結果をXrayテストケースと同期する方法の詳細について、 Xray結果レポート に関する記事をご覧ください。
“message_version” mabl の Webhook ペイロードのバージョンを示します。

ジャーニー

Webhookのペイロードでは、テストは「journeys」と呼ばれます。

実行前サンプルペイロード

{
  "status": "queued",
  "status_cause": null,
  "success": true,
  "plan": {
    "id": "4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
    "name": "Print click and assert Plan",
    "labels": [ "apple", "zebra"],
    "href": "https://api.mabl.com/v1/schedule/runPolicy/4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
    "tags": []
  },
  "plan_execution": {
    "status": "queued",
    "status_cause": null,
    "id": "d5b96d02-c45d-4d08-8684-de55411bcede",
    "href": "https://api.mabl.com/v1/execution/runPolicyExecution/d5b96d02-c45d-4d08-8684-de55411bcede",
    "revision": "12240"
  },
  "journeys": [
    {
      "id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "name": "Print, then assert",
      "labels": [ "apple", "zebra"],
      "href": "https://api.mabl.com/v1/test/journey/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "tags": [
        "training"
      ]
    }
  ],
  "journey_executions": [],
  "start_time": null,
  "stop_time": null,
  "tags": [],
  "results": [],
  "message_version": "1.0.0"
}

サンプルの実行後ペイロード

{
  "status": "succeeded",
  "status_cause": null,
  "success": true,
  "plan": {
    "id": "4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
    "name": "Print click and assert Plan",
    "labels": [ "apple", "zebra"],
    "href": "https://api.mabl.com/v1/schedule/runPolicy/4ba4550d-df2b-4df2-8799-46c44dbb4b9e",
    "tags": []
  },
  "plan_execution": {
    "status": "succeeded",
    "status_cause": null,
    "id": "d5b96d02-c45d-4d08-8684-de55411bcede",
    "href": "https://api.mabl.com/v1/execution/runPolicyExecution/d5b96d02-c45d-4d08-8684-de55411bcede",
    "revision": "12240"
  },
  "journeys": [
    {
      "id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "name": "Print, then assert",
      "labels": [ "apple", "zebra"],
      "href": "https://api.mabl.com/v1/test/journey/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "tags": [
        "training"
      ]
    }
  ],
  "journey_executions": [
    {
      "status": "completed",
      "status_cause": null,
      "success": true,
      "name": "Print, then assert",
      "journey_id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "journey_execution_id": "c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "start_time": 1517612117504,
      "stop_time": 1517612146280,
      "href": "https://api.mabl.com/v1/execution/runPolicyExecution/4ba4550d-df2b-4df2-8799-46c44dbb4b9e/testScriptExecution/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "results_href": "https://app.mabl.com/workspaces/3627972b-a762-4a87-a3fb-97cde3e9c414/test/plan-executions/d5b96d02-c45d-4d08-8684-de55411bcede/journeys/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0",
      "test_cases": [
        {
          "id": "MABL-1234"
        },
        {
          "id": "MABL-999"
        }
      ]
    }
  ],
  "start_time": 1517612110113,
  "stop_time": 1517612146368,
  "tags": [],
  "results": [
    {
      "success": true,
      "name": "Print, then assert",
      "results_href": "https://app.mabl.com/workspaces/3627972b-a762-4a87-a3fb-97cde3e9c414/test/plan-executions/d5b96d02-c45d-4d08-8684-de55411bcede/journeys/c221c1f8-aa52-4fdb-a1bd-5ee5b408ac9f:0"
    }
  ],
  "message_version": "1.0.0"
}

関連記事