レポーティングAPI

API経由でのテスト結果と成果物の取得

mablのレポーティングAPIを使うと、外部のレポートツールまたはデータベースへ、テスト結果やテスト実行の成果物をプログラムを経由してエクスポート・取り込むことができます。レポーティングAPIの早期アクセスプログラムで使用できるエンドポイントは次のとおりです。

  1. テスト実行結果を取得する、実行結果に関するエンドポイント (Run results endpoints)
  2. 特定の条件に当てはまる複数のテスト結果をまとめて取得する、複数の実行結果に関するエンドポイント (Batch results endpoint)
  3. テスト実行の成果物をエクスポートする、テスト成果物に関するエンドポイント (Run artifacts endpoints)
  4. ワークスペースでのユーザーアクティビティをエクスポートするアクティビティフィード結果エンドポイント(Activity feed results endpoint)

このガイドでは、これらのレポーティングAPIエンドポイントの概要を説明します。

はじめに

レポーティングAPIを使う前に、コマンドラインインターフェース(CLI)のAPIキーを作成する必要があります。このキーは、APIリクエストのヘッダに含まれ、認証に使用されます。

たとえば、デプロイメントイベントの結果を取得する次のcURLリクエストは、-uフラグで認証を行います。

curl -s "https://api.mabl.com/execution/result/event/DEPLOYMENT-EVENT-ID"\ 
     -u "key:YOUR-API-KEY"

📘

APIキーに関連する権限

mablでAPIキーの作成とコピーができるのは、ワークスペースのOwner(所有者)のみです。

実行結果に関するエンドポイント (Run results endpoint)

実行結果に関するエンドポイントでは、テスト実行、プラン実行、またはデプロイメントイベントのステータスと結果を取得することができ、それらを外部のレポートワークフローに統合して詳細な分析を行うことができます。

mablのテスト実行を外部データベースに連携するするユースケースには、次のようなケースが考えられます。

  • 信頼性の低いテストを特定する
  • テスト頻度や成功率の傾向を分析する
  • チーム、リリース、ブランチごとにmablのテスト結果の現状を示す社内用ダッシュボードを作成する

実行結果に関するエンドポイントからステータスと実行結果を取得するには、パラメーターとして適切なmablリソースIDを指定してAPIリクエストを送信します。
次の表に、各エンドポイントとそのパラメーターおよび出力を示します。

エンドポイントパラメーター出力
テスト実行結果の取得テスト実行IDテスト実行の結果に関する情報
プラン実行結果の取得プラン実行IDプラン実行の結果に関する情報
デプロイメントイベントの結果の取得デプロメントイイベントIDデプロイメントイベントの結果に関する情報

複数のテスト結果に関するエンドポイント (Batch results endpoint)

特定のテスト実行、プラン実行、デプロイイベントの結果を取得するだけでなく、複数のテスト結果に関するエンドポイント を使用して、複数のテスト結果をまとめて取得することもできます。このエンドポイントでは、時間範囲、テスト/プランラベル、テストID、プランID、アプリケーションID、環境ID などフィルタリング条件に合わせて、条件に当てはまる複数のテストの実行結果が返されます。

複数のテスト結果に関するエンドポイントは、以下のような場合に使うことができます。。

  • ワークスペースのすべてのテスト実行を結果取得をし、既存のすべての結果で外部データベースを初期化する
  • 1回限りの分析のために、最近のリリースに関する特定の統計情報をまとめて取得する

パスパラメーターとしてワークスペースIDを指定して、リクエストを送信します。デフォルトでは、エンドポイントは、過去30日間のクラウド上のすべてのテスト実行を返します。実行は、テストが完了した後にしか利用できませんが、通常はテストの実行後数秒以内に利用できます。

📘

ご注意:

テストのステータスstopped または canceled のテスト実行は、複数のテスト結果に関するエンドポイントで取得できるテスト結果には含まれません。

取得するテスト結果をフィルタリングするには、APIリクエストに追加のクエリパラメーターを指定します。パラメーターが値としてIDを取る場合、適切なmablリソースIDを指定します。

パラメーター説明
application_idアプリケーションIDを指定して、特定のアプリケーションに関連するテスト結果を返します。
environment_id環境IDを指定して、特定の環境に関連するテスト結果を返します。
test_idテストIDを指定して、特定のテストの結果を返します。
test_labelテストラベルで結果をフィルタリングします。
plan_idプランIDを指定して、特定のプランに含まれるテストのテスト結果を返します。
plan_labelプランラベルで結果をフィルタリングします。
earliest_start_time最も早いテスト実行開始時刻(注)。時刻の書式はエポックミリ秒
latest_end_time最も遅いテスト実行終了時刻(注)。時刻の書式はエポックミリ秒
limit1つのAPIレスポンスで返す実行の最大数。その後のAPIリクエストでcursorパラメーターを渡すことで、残りのテスト結果を取得できます。
cursorページ分割されたAPIレスポンスで、追加のテスト結果を取得するために使用します。

*最も早い開始時刻から最も遅い終了時刻までの時間範囲は、最長90日間です。時間範囲を指定しない場合、APIレスポンスはデフォルトで過去30日間のテスト実行の結果を返します。

テスト成果物に関するエンドポイント (Run artifacts endpoints)

テスト成果物に関するエンドポイントは、特定のテスト実行の成果物をエクスポートできる状態にして、取得します。監査のために、テスト実行の成果物を自動的にエクスポートするのに役立ちます。

テスト成果物に関するエンドポイントからは、次のテスト成果物を取得できます。

  • Chromeトレース
  • コンソールログ
  • DOMスナップショット
  • HARログ
  • スクリーンショット

これらのテスト成果物は、mabl CLIのコマンド、mabl test-runs export <テスト実行ID> でエクスポートすることもできます。

テスト成果物をエクスポートできるようにした上で取得するには、パラメーターとして適切なmablリソースIDを指定してAPIリクエストを送信します。
次の表に、テスト成果物に関するエンドポイントと、そのパラメーターおよび出力を示します。

エンドポイントパラメーター出力
テスト成果物のエクスポート準備テスト実行IDテスト成果物のエクスポートの準備をはじめ、エクスポートIDを返します。
テスト成果物の取得エクスポートIDテスト成果物のエクスポートの準備ができるまでエンドポイントをポーリングします。
成果物のエクスポートの準備が整うと、このエンドポイントは、エクスポートのzipファイルのURLを返します。

📘

テスト成果物エクスポートURLのアクセス期間

テスト成果物のエクスポートURLは、7日間のみ有効です。

アクティビティフィード結果エンドポイント

アクティビティフィード結果エンドポイントは、ワークスペースでの過去のユーザーアクティビティの結果を返します。結果は、時間範囲、アクションのタイプ、エンティティタイプ、エンティティ名、アクターIDでフィルタリングできます。このエンドポイントを使用すると、結果を内部データベース、ダッシュボード、またはレポートツールにエクスポートして、ワークスペースアクティビティを追跡できます。

パスパラメーターとしてワークスペースIDを指定して、リクエストを送信します。

結果をフィルタリングするには、リクエストに追加のクエリパラメーターを指定します。パラメーターが値としてIDを取る場合、適切な[mablリソースID]を指定します。

パラメーター説明
action_type実行されたアクションのタイプ: "create"、"update"、"delete"、または "recover"
entity_typeアクションの対象となったオブジェクトのタイプ ("test" や "snippet" など)。[Settings] > [Activity Feed]に移動し、[Entity Type] ドロップダウンをクリックすると、サポート対象のエンティティの一覧が表示されます。
entity_nameアクションの対象となったエンティティの名前。このフィールドでは大文字と小文字が区別されます。これまでにエンティティに付けられていた名前(後で更新されたエンティティ名を含む) に基づいた結果が返されます。
actor_idアクションを実行したユーザー (ユーザーID、APIキーID、またはmablシステム)。
start_time最も早いアクティビティ開始時刻 (エポックミリ秒)
end_time最も遅いアクティビティ終了時刻 (エポックミリ秒)
limit1つの応答で返す結果の最大数。その後の呼び出しでcursorパラメーターを渡すことで、結果のページを追加取得できます。
cursorページ分割された応答で追加の結果を取得するために使用します。