APIを使ったCI/CDインテグレーション
ほとんどのmablのお客さまは、mablの既存のインテグレーションや、mabl CLIを使用して、エンドツーエンドテストをDevOpsパイプラインに統合しています。しかし、これらの選択肢がニーズに合わない場合は、mabl APIを使用してコードデプロイ時にエンドツーエンドテストを実行できます。
ほとんどのmablのお客さまは、mablの既存のインテグレーションや、mabl CLIを使用して、エンドツーエンドテストをDevOpsパイプラインに統合しています。しかし、これらの選択肢がニーズに合わない場合は、mabl APIを使用してコードデプロイ時にエンドツーエンドテストを実行できます。
以下の記事もおすすめです。
CI/CDパイプラインにmablを統合する前に、mablテストを実行するさまざまな方法を確認し、CI/CDでの継続的テストに関する記事をチェックしてください。
この記事では、2つのシンプルなAPIコールを使用して、CI/CDパイプラインのステップとしてmablを統合する方法のをご紹介します。最初のAPIコールは、新しいソフトウェアデプロイメントイベントに応答して、特定の環境やアプリケーション、さらに特定のラベルに関連するすべてのプランを呼び出します。2回目のAPIコールは、1回目のAPIコールの結果として起動されたプランのステータスを確認するために使用できます。
この例では、Jenkins、Gitlab、CircleCIなどのCIビルドツールと、curlやjqなどの標準的なツールを使って、bashでカスタムビルドステップを記述できるLinuxベースのコンテナを使用していることを想定しています。ご自身が利用されている環境に合わせて内容を調整ください。
CI/CDワークフローの仮説を立てる
あなたのチームが自動化されたCI/CDワークフローを持っていて、そこにmablを使ったエンドツーエンドのテストを統合したいと仮定します。例として、CI/CDワークフローの一部を表す以下のようなシンプルなパイプラインを考えてみましょう。
Deployment Events API
CI/CDフローにmablを追加する最初のステップで、Deployment Events APIを使用して、アプリケーションをデプロイする際にmablを呼び出します。Deployment Events APIを起動すると、mablは指定された環境、アプリケーション、そして指定した特定のラベルに関連するプランを検索し、それらのプランを直ちに実行します。プランにはDeploymentトリガーの設定が必要です。
Deploymentトリガーを設定してください。
Deployment Events APIは、プランに設定されたDeploymentトリガーが必要です。利用時に必ず設定してください。
Deployment Event APIの使用を開始する前に、いくつかの情報が必要になります。
- ワークスペースのAPIキー（必須、キータイプはDeployment Triggerです）
- 以下のいずれかのID （必須）
- mabl Environment ID
- mabl Application ID
- mabl Environment ID （and/or) Application ID （and/or) プランのラベル
ラベルはmablプランを整理するのに最適な方法です。また、APIにラベルパラメータとして渡すことで、どのプランを実行するかをより詳細にコントロールできます。しかしながら、呼び出し方法が複雑になるため、まずはEnvironment IDだけを利用して制御してみてください。
Deployment Event APIの使用方法を学ぶ最も簡単な方法があります。 Settings ⇒ APIs と進み、 API Documentation セクションで Deployment Event API を選択してください。その後、mablの環境（Environment）を選択すれば、Deployment Event APIを呼び出すためのcurlコマンドが自動生成され表示されます。
インタラクティブにAPIのリファレンスが可能です。
API Documentationでは、環境などの条件を指定するだけでcurlコマンドを自動生成してくれます。
テスト実行を気軽に試せるサイト「Trigger mabl test executions」もあります
テスト実行を気軽に試せるサイトも用意しています。 https://help.mabl.com/reference/ondeploy
最小限の environment_id プロパティに加えて、デプロイメントイベントに関連する他の参照情報を渡すこともできます。以下は、APIに渡すことができるJSONメッセージの例です。
{
"environment_id":"FQWY5iMcfkmqV64YMyrt5w-e",
"revision":"937e77b3822a4ae2a38135e08a5d4a8eb6eddfdd",
"event_time":1522778187000,
"properties":{
repository_branch_name: 'master',
repository_commit_username: 'mablcoder',
repository_url: '[email protected]:mycompany/myrepo.git',
repository_pull_request_url: 'https://github.com/mycompany/myrepo/pull/1013',
repository_pull_request_number: 1013,
repository_pull_request_title: 'good pr'
}
}
revision 、 event_time 、properties の各属性はすべてオプションです。以下にそれぞれの意味を簡単に説明します。
- revision: デプロイメントに関連付けられたSCMリビジョン（例：gitのハッシュ値など）
- event_time: デプロイメントイベントが発生した時刻を UNIX エポックタイムスタンプでミリ秒単位で指定します。デプロイメントが発生してから Deployment Events API が呼び出されるまでに遅延がある場合は、これを渡すことが望ましい場合があります。
- properties: キーと値のペアの任意のマップ。任意の追加情報をここに入れます。mablが認識して特別な意味を持たせる標準的なプロパティがいくつかあります。mablのネイティブ統合の多くは、以下のようなプロパティをデフォルトで提供しています。
- repository_branch_name: このデプロイメントがビルドされたコードブランチ
- repository_commit_username: デプロイされたコードをコミットしたユーザーのユーザー名
- repository_url: このデプロイメントのトリガーとなったコードリポジトリの URL
- repository_pull_request_url: このデプロイメントのトリガーとなったプルリクエストの URL
- repository_pull_request_number: このデプロイメントのトリガーとなったプルリクエストの番号
- repository_pull_request_title: このデプロイメントのトリガーとなったプルリクエストのタイトル
Deployment Events APIを起動すると、イベントIDとその他の情報を含むJSONメッセージが返されます。たとえば、次のようになります。
{
"id": "OCn2EccmXk9eFvRInTfwkQ-v",
"environment_id": "dbd62e2e-bbbc-4c15-ab7c-72aa0ce379fe",
"received_time": 1522777753410
}
レスポンスの最も重要な部分は、idフィールドです。このイベントIDは、後にデプロイメントイベントで開始された実行結果を取得する際に必要となります。
Execution Result API
デプロイメントイベントが作成された後、そのイベントの結果として起動されたプランのステータスは、実行結果 API を使用して照会できます。実行結果 API を使用するには、まずDeployment Event ID を取得する必要があります(上記の Deployment Event API を参照のこと)。
Deployment Event API と同様に、Execution Result API を知る最も簡単な方法は、mabl の curl ビルダを使用することです。 Settings => APIs に移動し、 API Document セクションで Execution Result API を選択します。
テスト実行を気軽に試せるサイト「Trigger mabl test result」もあります
テスト実行を気軽に試せるサイトも用意しています。 https://help.mabl.com/reference/getexecutionresultforevent
Deployment Event API は、実行されたすべてのプランおよびテストの概要情報（各プランの詳細情報を含む）を含む JSON オブジェクトを返します。以下にレスポンスの例を示します。
{
"event_status": {
"succeeded": true,
"succeeded_first_attempt": true
},
"plan_execution_metrics": {
"total": 1,
"passed": 1,
"failed": 0
},
"journey_execution_metrics": {
"total": 1,
"passed": 1,
"failed": 0
},
"executions": [
{
"status": "succeeded",
"success": true,
"plan": {
"id": "c953e3e3-a195-4b36-bdf8-49ec73ee3d35",
"name": "Verify home page load and login",
"label": "regression",
"href": "https://api.mabl.com/schedule/runPolicy/c953e3e3-a195-4b36-bdf8-49ec73ee3d35",
"app_href": "https://app.mabl.com/workspaces/5bf0ebb1-f158-4c02-9e71-1be9f6ce7d17/test/plans/c953e3e3-a195-4b36-bdf8-49ec73ee3d35"
},
"plan_execution": {
"id": "I9wjeolJE-iuvOmCSF28Lw-pe",
"status": "succeeded",
"href": "https://api.mabl.com/execution/runPolicyExecution/c953e3e3-a195-4b36-bdf8-49ec73ee3d35"
},
"journeys": [
{
"id": "6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
"name": "Visit home page",
"href": "https://api.mabl.com/execution/runPolicyExecution/I9wjeolJE-iuvOmCSF28Lw-pe/testScriptExecution/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
"app_href": "https://app.mabl.com/workspaces/5bf0ebb1-f158-4c02-9e71-1be9f6ce7d17/test/plan-executions/I9wjeolJE-iuvOmCSF28Lw-pe/journeys/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0"
}
],
"journey_executions": [
{
"journey_id": "6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
"journey_execution_id": "6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
"status": "completed",
"success": true,
"href": "https://api.mabl.com/test/journey/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
"app_href": "https://app.mabl.com/workspaces/5bf0ebb1-f158-4c02-9e71-1be9f6ce7d17/train/journeys/6b194f04-1ea0-45f1-8a1a-04c9338067d9:0",
"test_cases": [
{
"id": "MABL-1234"
},
{
"id": "MABL-999"
}
]
}
],
"start_time": 1522777753987,
"stop_time": 1522777997841
}
]
}
ほとんどの場合、plan_execution_metrics と journey_execution_metrics のサマリー情報だけを処理すれば十分でしょう。app_href という名前の出力フィールドには、エンティティや実行結果を直接表示するために使用できるmabl UIへのリンクが含まれています。
Journeyとは？
過去にmablはテストを「Journey」と呼んでいました。APIレスポンスには、古い用語である 「Journey」がまだ反映されています。
CI/CDパイプラインにmablを組み込む
CI/CDパイプラインにmablを組み込む方法としては、以下のようなものが考えられます。
- Deployment Events APIを使用して、特定の環境にデプロイが発生したときに特定のプランをキックする。
- すべてのプランが成功、または失敗するまでExecution Result APIをポーリングする
先ほどのパイプラインの例で言えば、以下のようになります。
実行と結果を紐付ける
以下に示すのは、デプロイイベントをトリガーして、完了または失敗するまで実行のポーリングを続けるbashスクリプトです。このスクリプト例は、sh mabl-deployment-integration.sh api-key env-idのように、引数としてAPIキーと環境IDを使用します。
#!/bin/bash
MABL_API_BASE="https://api.mabl.com"
POLL_SEC=10
if [ "$#" -ne 2 ]; then
echo "Usage: $0 <api-key> <environment-id>"
exit 0
fi
API_KEY="$1"
ENV_ID="$2"
# Create a deployment event, and retrieve its ID:
deployment_event=$(curl -s "${MABL_API_BASE}/events/deployment" -u "key:${API_KEY}" -H 'Content-Type:application/json' -d "{\"environment_id\":\"${ENV_ID}\"}")
event_id=$(echo "${deployment_event}" | jq -r '.id')
echo "Deployment Event ID: ${event_id}"
# Poll the Execution Result API until all Plans have completed
while true; do
echo "Waiting for executions to complete..."
sleep ${POLL_SEC}
results=$(curl -s "${MABL_API_BASE}/execution/result/event/${event_id}" -u "key:${API_KEY}")
event_status=$(echo "${results}" | jq '.event_status')
if [ -z "${event_status}" ] || [ "${event_status}" = "{}" ]; then
continue
fi
plan_metrics=$(echo "${results}" | jq '.plan_execution_metrics')
if [ "${plan_metrics}" != "null" ]; then
total_plans=$(echo "${plan_metrics}" | jq -r '.total')
passed_plans=$(echo "${plan_metrics}" | jq -r '.passed')
failed_plans=$(echo "${plan_metrics}" | jq -r '.failed')
fi
succeded=$(echo "${event_status}" | jq -r '.succeeded')
succeded_with_retries=$(echo "${event_status}" | jq -r '.succeeded_with_retries')
break
done
# Print summary:
echo
echo "Full Results:"
echo "${results}" | jq
echo
echo "Total plans executed: ${total_plans} succeded: ${passed_plans} failed: ${failed_plans}"
if [ "${succeded}" = "true" ]; then
if [ "${succeded_with_retries}" = "true" ]; then
echo "Successful run with retries"
else
echo "Successful run"
fi
exit 0
else
echo "One or more plans have failed"
exit 1
fi
Updated 12 days ago