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"
}