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ビルドツールと、curljqなどの標準的なツールを使って、bashでカスタムビルドステップを記述できるLinuxベースのコンテナを使用していることを想定しています。ご自身が利用されている環境に合わせて内容を調整ください。

CI/CDワークフローの仮説を立てる

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

385385

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の使用方法を学ぶ最も簡単な方法があります。 SettingsAPIs と進み、 API Documentation セクションで Deployment Event API を選択してください。その後、mablの環境(Environment)を選択すれば、Deployment Event APIを呼び出すためのcurlコマンドが自動生成され表示されます。

14991499

📘

インタラクティブにAPIのリファレンスが可能です。

API Documentationでは、環境などの条件を指定するだけでcurlコマンドを自動生成してくれます。

📘

テスト実行を気軽に試せるサイト「Trigger mabl test executions」もあります

テスト実行を気軽に試せるサイトも用意しています。 https://help.mabl.com/reference/post_events-deployment

最小限の 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'
  }
}

revisionevent_timeproperties の各属性はすべてオプションです。以下にそれぞれの意味を簡単に説明します。

  • 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 を選択します。

12851285

📘

テスト実行を気軽に試せるサイト「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_metricsjourney_execution_metrics のサマリー情報だけを処理すれば十分でしょう。app_href という名前の出力フィールドには、エンティティや実行結果を直接表示するために使用できるmabl UIへのリンクが含まれています。

📘

Journeyとは?

過去にmablはテストを「Journey」と呼んでいました。APIレスポンスには、古い用語である 「Journey」がまだ反映されています。

CI/CDパイプラインにmablを組み込む

CI/CDパイプラインにmablを組み込む方法としては、以下のようなものが考えられます。

  • Deployment Events APIを使用して、特定の環境にデプロイが発生したときに特定のプランをキックする。
  • すべてのプランが成功、または失敗するまでExecution Result APIをポーリングする

先ほどのパイプラインの例で言えば、以下のようになります。

497497

実行と結果を紐付ける

以下は、デプロイメントイベントをトリガーして、実行が完了するか失敗するまでポーリングするために使用できるbashスクリプトです。もちろん、この例を使用または適用する前に、独自のAPIキーとEnvironment IDを代入する必要があります。

🚧

ご利用の環境に合わせて以下のコードを修正してください。

以下の「api-key」と「environment-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