APIを使ったCI/CDインテグレーション – mablヘルプ

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

おすすめの記事

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

このガイドでは、デプロイメントイベント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は、指定された環境、アプリケーション、ラベルに関連するすべてのプランから、デプロイトリガーを含むプランを検索し、IDで指定したプランと合わせて直ちに実行します。

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

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

リクエストの作成

APIページのmablデプロイメントビルダーは、mabl CLIコマンドまたはcURLリクエストとしてコマンドを生成します。cURLリクエストを作成するには、次の手順を実行します。

ワークスペース > API に移動し、デプロイ時にテストを実行までスクロールします。
コマンドの種類としてcURLを選択します。
認証に使用で、リクエストに使用するAPIキーを選択します。このドロップダウンには、デプロイメントをトリガーできるキーのみが表示されます。
ターゲットを選択し、必要に応じてオーバーライドやデプロイメントの詳細を追加して、curlコマンドを生成します。

リクエストのフィールド

すべてのリクエストには、environment_id、application_id、またはその両方を含める必要があります。その他のフィールドはすべてオプションです。以下は、リクエスト本文のより詳細な例です。

{
  "environment_id": "FQWY5iMcfkmqV64YMyrt5w-e",
  "plan_labels": ["smoke"],
  "revision": "937e77b3822a4ae2a38135e08a5d4a8eb6eddfdd",
  "plan_overrides": {
    "web_url": "https://preview-1013.example.com",
    "browser_types": ["chrome", "firefox"]
  }
}

多くのパイプラインで使用するフィールドは次のとおりです。

plan_labels: 環境やアプリケーションのすべてのプランではなく、smoke など、これらのラベルのいずれかを持つプランだけを実行します。
branch: デプロイしたコードに対応するブランチなど、mablブランチのテストを実行します。
revision: gitのコミットハッシュなど、デプロイのソースコードリビジョン。結果をデプロイしたコミットまでさかのぼれるように送信してください。
plan_overrides: このデプロイの場合に限り、トリガーされたプランの実行方法を変更します。プランのオーバーライドを参照してください。
test_selection: テスト影響分析が選択したテストを実行します。テスト影響分析が選択したテストを実行するを参照してください。

特定のプランを実行するには、リクエスト本文のトップレベルにある plan_ids にプランIDを最大50件まで追加します (例: "plan_ids": ["cLhFR8Fz0Kpsh70zP6EQ3Q-p"])。プランラベルを指定しない場合は、これらのプランだけが実行されます。プランラベルを指定した場合は、ラベルに一致するプランと一緒に実行されます。指定したプランのいずれかがデプロイメントイベントで実行できない場合、mablはリクエストを拒否し、どのプランも実行されません。IDで特定のプランを実行するを参照してください。

エンドポイントが受け付けるすべてのフィールドについては、mabl APIリファレンスのデプロイメントイベントの作成を参照してください。

プランのオーバーライド

plan_overrides を使用すると、プランを編集せずに、プランに保存されている設定とは異なる設定でトリガーされたプランを実行できます。たとえば、プランをプレビュー環境のURLに向けたり、別のブラウザーで実行したり、別のクレデンシャルでログインしたりできます。上記のリクエスト例では、プレビューURLに対してChromeとFirefoxでプランを実行します。

デプロイアクション

actions を使用すると、環境でmablブランチのスナップショットからテストを実行したり、実行するテストのビジュアルベースラインをリセットしたりできます。各アクションのフィールドについては、APIリファレンスを参照してください。

テスト影響分析が選択したテストを実行する

CIパイプラインでテスト影響分析を実行している場合は、デプロイメントイベントで、分析が返した影響を受けるテストを実行できます。test_selection で、次の値を設定します。

test_ids: 各テストの test_invariant_id（最大50件）。
impact_session_id: 分析の session_id。
source: agent。テストを選択したのは分析であるためです。

mablは、イベントの環境、アプリケーション、またはその両方に一致するデプロイで、これらのテストをまとめて1つのプラン実行として実行します。例:

{
  "environment_id": "FQWY5iMcfkmqV64YMyrt5w-e",
  "revision": "937e77b3822a4ae2a38135e08a5d4a8eb6eddfdd",
  "test_selection": {
    "test_ids": ["Xk3pQ7rLs0e2YvNw9Ha1Bg-j"],
    "impact_session_id": "{session-id}",
    "source": "agent",
    "retry_failed_tests": true
  }
}

plan_labels を送信しない場合は、選択したテストだけが実行されます。plan_labels も送信した場合は、一致するプランが同じデプロイメントイベントで実行されます。

詳しくは、影響を受けるテストを実行するを参照してください。test_selection のその他のフィールドについては、APIリファレンスを参照してください。

デプロイメントイベントのトリガー

デプロイメントイベントをトリガーすると、デプロイメントイベントIDと、開始されたプランを含むJSONメッセージが返されます。例:

{
  "id": "OCn2EccmXk9eFvRInTfwkQ-v",
  "environment_id": "FQWY5iMcfkmqV64YMyrt5w-e",
  "workspace_id": "RS2yqNMP9nK9qobpJiZ74Q-w",
  "received_time": 1522777753410,
  "plan_labels": ["smoke"],
  "triggered_plan_run_summaries": [
    {
      "plan_id": "cLhFR8Fz0Kpsh70zP6EQ3Q-p",
      "plan_run_id": "I9wjeolJE-iuvOmCSF28Lw-pr"
    }
  ]
}

レスポンスには、送信したリクエストのフィールドと、mablが設定するフィールドが含まれます。確認すべきフィールドは次のとおりです。

id: デプロイメントイベントID。デプロイメントイベントでトリガーされたテストの結果を取得するために使用します。
triggered_plan_run_summaries: デプロイメントイベントで開始された各プランの plan_id と plan_run_id。リクエストが想定どおりのプランに一致したことを確認するために使用します。
test_selection.skipped_tests: test_selection を送信した場合に、実行されなかった選択済みテストとその理由。現在、理由は disabled のみです。スキップされたテストがない場合、このフィールドはレスポンスに含まれません。分析に関連付けられたものに限らず、どの test_selection でも返されます。

test_selection で実行したテストの場合、triggered_plan_run_summaries には、plan_id がデプロイメントイベントIDの末尾に -selection を付けた値になっているエントリが含まれます。このIDを持つ保存済みのプランはありません。選択したテストのためにmablが作成するプラン実行です。

すべてのレスポンスフィールドについては、APIリファレンスを参照してください。

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

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

リクエストの作成

同じビルダーで、結果を取得するリクエストも生成できます。

ワークスペース > API に移動し、デプロイ時にテストを実行までスクロールします。
コマンドの種類としてcURLを選択します。
結果を確認するで、デプロイメントイベントIDを入力して、curlコマンドを生成します。

レスポンスの取得

「デプロイ結果のサマリーの取得」エンドポイントによって返される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  "
  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

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

デプロイメントイベントの作成

リクエストの作成

リクエストのフィールド

プランのオーバーライド

デプロイアクション

テスト影響分析が選択したテストを実行する

デプロイメントイベントのトリガー

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

リクエストの作成

レスポンスの取得

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

実行と結果を紐付ける

関連記事