このチュートリアルでは、実行後のWebhook、JavaScript、mablレポートAPIを使用して、mablテストの結果をGoogle Sheetに追加するカスタムインテグレーションの作成方法について説明します。
このカスタムレポートワークフローをセットアップするには、チームの誰かが以下のことに精通している必要があります。
- Webhookの作成
- カスタムJavaScriptコードの作成とメンテナンス
- APIのコンセプトおよびAPIの基本的な使用法
APIのセットアップ
このワークフローを実装するには、Google Sheets APIおよびmablレポートAPIへのアクセスが必要です。
Google Sheets API
Google Sheets APIを使ってGoogle Sheetをプログラムで編集するには、Google Cloudのプロジェクトを使用する必要があります。このチュートリアルに関しては、無料枠のGoogle Cloudプロジェクトで十分です。以下の手順に沿って、Google CloudのプロジェクトとWebhookからアクセスするGoogle Sheetを用意します。
- まだ作成していない場合は、Google Cloudのプロジェクトを作成します (無料枠が利用できます)。
- 作成したプロジェクトでSheets APIを有効にします。
- WebhookがSheets APIとの認証に使用するサービスアカウントを作成します。 このサービスアカウントには、役割や権限を付与する必要はありません。
- ステップ (3) のサービスアカウント用のキーを作成します。このキーはお使いのコンピューターに安全にダウンロードされます。 Webhookコードでこのキーを使用して、Sheets APIとの認証を行います。
- 新しいGoogle Sheetを作成するか、データを書き込む既存のGoogle Sheetを開きます。
- [共有] ボタンをクリックして、Google Sheetをステップ (3) でEditor (編集者) として作成したサービスアカウントのメールアドレスと共有します。
mablレポートAPI
ワークスペースの所有者にmabl Viewer APIキーを作成してもらうか、既存のmabl Viewer APIキーを使用します。Webhookコードでこのキーを使用して、mablレポートAPIとの認証を行います。
Webhookコード
クラウド実行後にmablから呼び出すことができる実行後のWebhookの作成を行います。 たとえば、Google Cloud FunctionやAWS Lambdaとして、このWebhookを作成することができます。
大まかに言うと、このWebhookコードは、mablのプラン実行が完了したときに以下を実行します。
- 実行後のペイロードからプラン実行IDを抽出します。
plan_execution.id
- mablレポートAPIを使用して抽出されたプラン実行IDのプラン実行結果を取得します。
- プラン実行結果を行と列から成るフラットなスプレッドシート形式に変換します。
- このフラットなスプレッドシート形式の結果を、Google Sheets APIのセットアップ時に共有したGoogle Sheetに追加します。
ライブラリのインポート
まず、このWebhookコードには、GoogleおよびmablのAPIとやり取りするためのgoogleapisおよびaxiosライブラリが必要です。 次のように、NPMを使用して、NodeJSプロジェクトにこれらをインストールします。
npm install googleapis@111 axios@1.3.3 --save
これらのライブラリをインポートし、mablレポートAPIおよびGoogle Sheetsとやり取りするための情報を設定して、Webhookコードを開始します。
API情報の設定
MABL_API_KEY
、SPREADSHEET_ID
、SPREADSHEET_PAGE
、GOOGLE_SA_CREDENTIALS_FILE
の値を適切な値に置き換えます。
const {google} = require('googleapis');
const axios = require('axios');
// mabl API info
const MABL_API_KEY = '<API-KEY>';
const MABL_ENDPOINT_URL = 'https://api.mabl.com/results/planRun';
// Spreadsheet that has been shared with Google Service Account email address.
// Spreadsheet ID can be found in the URL for the spreadsheet like https://docs.google.com/spreadsheets/d/SPREADSHEET-ID-IS-HERE
const SPREADSHEET_ID = '<SPREADSHEET-ID>';
const SPREADSHEET_PAGE = 'Sheet1';
// Google scopes needed to append to spreadsheet
const SCOPES = ['https://www.googleapis.com/auth/spreadsheets'];
// File containing Google Service Account key created and downloaded in Setup step (4)
const GOOGLE_SA_CREDENTIALS_FILE = 'path/to/google-service-account-key.json';
テスト結果フィールドの定義
次に、順に抽出してスプレッドシートにプッシュするフィールドを定義します。 特定のフィールドが存在しないか、フィールドに実行結果の値がない場合、生成されるスプレッドシートのこの行のセルは空欄になります。 以下に示すフィールドは、ここに示された順序で、Google Sheetで定義される列に対応している必要があります。ただし、Google Sheetの列見出しでは、列を表すのにこれとまったく同じフィールド名を使用する必要はありません。
// Ordered fields on individual test runs
const TEST_RUN_FIELDS = [
"initial_url",
"browser",
"browser_version",
"execution_runner_type",
"scenario_name",
"test_id",
"test_version",
"test_name",
"test_type",
"branch",
"test_run_id",
"test_run_app_url",
"is_ad_hoc_run",
"start_time",
"end_time",
"run_time",
"status",
"success",
"failure_category",
"emulation_mode"
];
// Ordered fields on plan runs, to be appended after the test run fields.
const PLAN_RUN_FIELDS = [
"workspace_name",
"plan_id",
"plan_run_id",
"plan_name",
"trigger_type",
"triggering_deployment_event_id",
"application_name",
"environment_name",
"status",
"success"
];
Webhook関数の作成
Webhookでジョブを実行するのに必要な関数を作成します。 最初に、特定のプラン実行IDで、詳細なテスト実行結果を取得し、上記のフィールドに対応するフラットな値のリストに変換するステップ (2) および (3) の関数を作成します。
async function getPlanRunResults(id) {
const response = await axios.get(`${MABL_ENDPOINT_URL}/${id}`, {
auth: {
username: 'key',
password: MABL_API_KEY,
}
});
return response.data.test_results.map(result => {
const testRunFields = TEST_RUN_FIELDS.map(field => result[field]);
const planRunFields = PLAN_RUN_FIELDS.map(field => response.data[field]);
return [testRunFields, planRunFields];
});
}
次に、Googleとの認証を行うためのサービスアカウントのクレデンシャルを読み込み、これらを使ってフラットな実行結果をスプレッドシートにプッシュする関数を作成します。
async function loadGoogleCredentials(filename) {
return new google.auth.GoogleAuth({
keyFile: filename,
scopes: SCOPES,
});
}
async function appendToSheet(googleAuth, data) {
const sheets = google.sheets({version: 'v4', auth: googleAuth});
return await sheets.spreadsheets.values.append({
spreadsheetId: SPREADSHEET_ID,
range: SPREADSHEET_PAGE,
valueInputOption: 'RAW',
insertDataOption: 'INSERT_ROWS',
resource: {
values: data
}
});
}
最後に、トップレベル関数でこれらの関数を使用して、Webhookのペイロードを受け取り、詳細な実行結果をGoogle Sheetにプッシュします。
async function handlePlanRunWebhook(webhookPayload) {
const planRunId = webhookPayload.plan_execution.id;
const planRunResult = await getPlanRunResults(planRunId);
const googleAuth = await loadGoogleCredentials(GOOGLE_SA_CREDENTIALS_FILE);
await appendToSheet(googleAuth, planRunResult);
console.log(`Successfully processed plan run ID [${planRunId}]`);
}
実行後のWebhookの作成
このWebhookが機能する状態になったら、各実行後に呼び出される実行後のWebhookとしてURLを指定します。