APIを使ったCI/CDインテグレーション

Suggest Edits

ほとんどのmablのお客様は、mablの既存のインテグレーションやmabl CLIを使用して、エンドツーエンドテストをDevOpsパイプラインに統合しています。しかし、これらのオプションがニーズに合わない場合は、mabl APIを使用して、コードのデプロイ時にエンドツーエンドテストを実行できます。

📘
おすすめの記事
CI/CDパイプラインにmablを統合する前に、以下のリソースを確認してください。

テスト実行の概要

mablデプロイイベント

CI/CDによる継続的テスト

このガイドでは、デプロイイベントAPIを使用して、CI/CDパイプラインのステップとしてmablを統合する方法について、例を交えながら説明します。

最初のAPI呼び出しは、新しいソフトウェアデプロイイベントに対して、特定の環境、アプリケーション、プランラベルに関連するすべてのプランをトリガーします。
2番目のAPI呼び出しは、最初のAPI呼び出しの結果として起動されたプランのステータスを確認します。

説明に使用する例では、Jenkins、Gitlab、CircleCIなどのCIビルドツールと、curlやjqなどの標準的なツールを使ってbashでカスタムビルドステップを記述できるLinuxベースのコンテナーを使用していることを想定しています。これ以外のビルドツールを使用している場合は、以下の例をツールに合わせる必要がある場合があります。

架空のCI/CDワークフロー

チームには自動化されたCI/CDワークフローがあり、そこにmablを使ったエンドツーエンドのテストを統合したいと考えているとします。例として、CI/CDワークフローの一部を表す以下のようなパイプラインを考えてみましょう。

デプロイイベントの作成

CI/CDフローにmablを追加する最初のステップでは、mablデプロイイベントを使用して、アプリケーションのデプロイ時にmablに通知します。デプロイイベントの作成エンドポイントを呼び出すと、mablは、指定された環境、アプリケーション、ラベルに関連するすべてのプランから、デプロイトリガーを含むプランを検索し、それらのプランを直ちに実行します。

デプロイイベントAPIの使用を開始する前に、リクエストの詳細を収集する必要があります。

デプロイトリガーのAPIキー。詳細については、APIキーの管理を参照してください。
以下のmablリソースIDのうち少なくとも1つ。
- 環境ID
- アプリケーションID
プランラベル (特定のプランを対象とする場合)。

リクエストの作成

mablアプリケーションのAPIページで、デプロイイベントをトリガーするためのcurlコマンドを作成できます。

[Settings] > [APIs] に移動します。
[API documentation] までスクロールします。
ドロップダウンから [Create deployment event] を選択します。
リクエストの詳細を追加して、curlコマンドを生成します。

オプションの情報

最低限必要なenvironment_idまたはapplication_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は、後にデプロイメントイベントで開始された実行結果を取得する際に必要となります。

デプロイイベントの結果の取得

デプロイイベントを作成したら、デプロイ結果のサマリーの取得エンドポイントを使用して、起動されたプランのステータスを確認できます。

リクエストの作成

mablアプリケーションのAPIページで、デプロイイベントのステータスを取得するためのcurlコマンドを作成できます。

[Settings] > [APIs] に移動します。
[API documentation] までスクロールします。
ドロップダウンから、[Get results from a deployment event] を選択します。
デプロイイベントIDを入力します。

レスポンスの取得

「デプロイ結果のサマリーの取得」エンドポイントによって返される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)」と呼ばれていました
APIレスポンスには、テストの以前の用語である「手順 (journey)」が今でも反映されています。

パイプラインへのmablの挿入

CI/CDパイプラインにmablを挿入するオプションの1つは、以下のとおりです。

特定の環境へのデプロイが発生したときに、デプロイイベントをトリガーして特定のプランを実行します。
すべてのプランが成功するか失敗するまで、エンドポイントのポーリングを続けてデプロイイベントの結果を取得します。

架空のCI/CDワークフローを使用すると、次のようになります。

実行と結果を紐付ける

次の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 3 months ago

Related resources