Playwright ランタイムを使用した Node.js Canary スクリプトの記述 - Amazon CloudWatch

Playwright ランタイムを使用した Node.js Canary スクリプトの記述

Playwright ランタイム用の Node.js Canary ファイルのパッケージ化

Canary スクリプトは、Synthetics ハンドラーコードを含む .js (CommonJS 構文) または .mjs (ES 構文) ファイルと、コードが依存する追加のパッケージやモジュールで構成されます。ES (ECMAScript) 形式で作成されたスクリプトは、拡張子として .mjs を使用するか、"type": "module" フィールドが設定された package.json ファイルを含める必要があります。Node.js Puppeteer などの他のランタイムとは異なり、スクリプトを特定のフォルダ構造に保存する必要はありません。スクリプトを直接パッケージ化できます。任意の zip ユーティリティを使用して、ハンドラーファイルをルートに置く .zip ファイルを作成します。Canary スクリプトが Synthetics ランタイムに含まれていない追加のパッケージまたはモジュールに依存している場合は、これらの依存関係を .zip ファイルに追加できます。そのためには、npm install コマンドを実行して、関数に必要なライブラリを node_modules ディレクトリにインストールします。次の CLI コマンドの例では、index.js または index.mjs ファイル (Synthetics ハンドラー) とその依存関係を含む my_deployment_package.zip という名前の .zip ファイルを作成します。この例では、npm パッケージマネージャーを使用して依存関係をインストールします。

~/my_function ├── index.mjs ├── synthetics.json ├── myhelper-util.mjs └── node_modules ├── mydependency

プロジェクトフォルダの内容を含む .zip ファイルをルートに作成します。次の例で示すように r (再帰的) オプションを使用して、zip がサブフォルダを確実に圧縮するようにします。

zip -r my_deployment_package.zip .

Synthetics 設定ファイルを追加して、CloudWatch Synthetics の動作を設定します。synthetics.json ファイルを作成し、エントリポイントまたはハンドラーファイルと同じパスに保存できます。

オプションで、選択したフォルダ構造にエントリポイントファイルを保存することもできます。ただし、フォルダパスがハンドラー名で指定されていることを確認してください。

ハンドラー名

スクリプトのエントリポイント (ハンドラー) のファイル名に一致するように、Canary のスクリプトのエントリポイントを myCanaryFilename.functionName として設定します。オプションで Canary を myFolder/my_canary_filename.mjs などの別のフォルダに保存できます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します (myFolder/my_canary_filename.functionName など)。

既存の Playwright スクリプトを変更して CloudWatch Synthetics の Canary として使用する

Node.js と Playwright の既存のスクリプトを編集して Canary として使用できます。Playwright の詳細については、「Playwright ライブラリ」のドキュメントを参照してください。

ファイル exampleCanary.mjs に保存されている次の Playwright スクリプトを使用できます。

import { chromium } from 'playwright'; import { expect } from '@playwright/test'; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://example.com', {timeout: 30000}); await page.screenshot({path: 'example-home.png'}); const title = await page.title(); expect(title).toEqual("Example Domain"); await browser.close();

次のステップを実行してスクリプトを変換します。

  1. handler 関数を作成してエクスポートします。このハンドラーは、スクリプトのエントリポイント関数です。ハンドラー関数には任意の名前を選択できますが、スクリプトで使用される関数は Canary ハンドラーと同じである必要があります。スクリプト名が exampleCanary.mjs で、ハンドラ関数名が myhandler の場合、Canary ハンドラの名前は exampleCanary.myhandler になります。次の例では、ハンドラー関数名は handler です。

    exports.handler = async () => { // Your script here };
  2. Synthetics Playwright module を依存関係としてインポートします。

    import { synthetics } from '@amzn/synthetics-playwright';
  3. Synthetics Launch 関数を使用してブラウザを起動します。

    const browser = await synthetics.launch();
  4. Synthetics newPage 関数を使用して新しい Playwright ページを作成します。

    const page = await synthetics.newPage();

これで、スクリプトを Synthetics の Canary として実行できるようになりました。更新されたスクリプトは次のとおりです。

ES6 形式で更新されたスクリプト

.mjs 拡張子を付けて保存されたスクリプトファイル。

import { synthetics } from '@amzn/synthetics-playwright'; import { expect } from '@playwright/test'; export const handler = async (event, context) => { try { // Launch a browser const browser = await synthetics.launch(); // Create a new page const page = await synthetics.newPage(browser); // Navigate to a website await page.goto('https://www.example.com', {timeout: 30000}); // Take screenshot await page.screenshot({ path: '/tmp/example.png' }); // Verify the page title const title = await page.title(); expect(title).toEqual("Example Domain"); } finally { // Ensure browser is closed await synthetics.close(); } };

CommonJS 形式で更新されたスクリプト

.js 拡張子を付けて保存されたスクリプトファイル。

const { synthetics } = require('@amzn/synthetics-playwright'); const { expect } = require('@playwright/test'); exports.handler = async (event) => { try { const browser = await synthetics.launch(); const page = await synthetics.newPage(browser); await page.goto('https://www.example.com', {timeout: 30000}); await page.screenshot({ path: '/tmp/example.png' }); const title = await page.title(); expect(title).toEqual("Example Domain"); } finally { await synthetics.close(); } };

CloudWatch Synthetics の設定

Synthetics Playwright ランタイムの動作を設定するには、synthetics.json という名前のオプション JSON 設定ファイルを指定します。このファイルは、ハンドラーファイルと同じ場所にパッケージ化する必要があります。設定ファイルはオプションですが、設定ファイルを指定しない場合、または設定キーがない場合、CloudWatch はデフォルトを引き受けます。

設定ファイルのパッケージ化

サポートされている設定値とそのデフォルト値を次に示します。

{ "step": { "screenshotOnStepStart": false, "screenshotOnStepSuccess": false, "screenshotOnStepFailure": false, "stepSuccessMetric": true, "stepDurationMetric": true, "continueOnStepFailure": true, "stepsReport": true }, "report": { "includeRequestHeaders": true, "includeResponseHeaders": true, "includeUrlPassword": false, "includeRequestBody": true, "includeResponseBody": true, "restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports "restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these url parameters are redacted from logs and reports }, "logging": { "logRequest": false, "logResponse": false, "logResponseBody": false, "logRequestBody": false, "logRequestHeaders": false, "logResponseHeaders": false }, "httpMetrics": { "metric_2xx": true, "metric_4xx": true, "metric_5xx": true, "failedRequestsMetric": true, "aggregatedFailedRequestsMetric": true, "aggregated2xxMetric": true, "aggregated4xxMetric": true, "aggregated5xxMetric": true }, "canaryMetrics": { "failedCanaryMetric": true, "aggregatedFailedCanaryMetric": true }, "userAgent": "", "har": true }

ステップ設定

  • screenshotOnStepStart – ステップの開始前に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは true です。

  • screenshotOnStepSuccess – ステップが成功した後に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは true です。

  • screenshotOnStepFailure – ステップが失敗した後に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは true です。

  • continueOnStepFailure – ステップが失敗した後もスクリプトを続行するかどうかを決定します。デフォルトは false です。

  • stepSuccessMetric - ステップの SuccessPercent メトリクスが出力されるかどうかを決定します。ステップの SuccessPercent メトリクスは、ステップが成功した場合は Canary 実行の 100 となり、ステップが失敗した場合は 0 となります。デフォルトは true です。

  • stepDurationMetric – ステップの Duration メトリクスが出力されるかどうかを決定します。Duration メトリクスは、ステップの実行時間としてミリ秒単位で出力されます。デフォルトは true です。

レポート設定

HAR ファイルや Synthetics ステップレポートなど、CloudWatch Synthetics によって生成されたすべてのレポートが含まれます。機密データの編集フィールド restrictedHeadersrestrictedUrlParameters は、Synthetics によって生成されたログにも適用されます。

  • includeRequestHeaders – レポートにリクエストヘッダーを含めるかどうか。デフォルトは false です。

  • includeResponseHeaders – レポートにレスポンスヘッダーを含めるかどうか。デフォルトは false です。

  • includeUrlPassword — URL に表示されるパスワードを含めるかどうか。デフォルトでは、機密データの開示を防ぐために、URL に表示されるパスワードはログとレポートで墨消しされます。デフォルトは false です。

  • includeRequestBody – レポートにリクエスト本文を含めるかどうか。デフォルトは false です。

  • includeResponseBody – レポートにレスポンス本文を含めるかどうか。デフォルトは false です。

  • restrictedHeaders – ヘッダーが含まれている場合に無視するヘッダー値のリスト。これは、リクエストヘッダーとレスポンスヘッダーの両方に適用されます。例えば、includeRequestHeaders を true として、restrictedHeaders['Authorization'] として渡すことで、認証情報を非表示にできます。

  • restrictedUrlParameters — 編集する URL パスまたはクエリパラメータのリスト。これは、ログ、レポート、エラーに表示される URL に適用されます。パラメータ名では大文字と小文字が区別されます。アスタリスク (*) を値として渡すと、すべての URL パスおよびクエリパラメータ値を墨消しできます。デフォルトは、空白の配列です。

  • har – HTTP アーカイブ (HAR) を生成するかどうかを決定します。デフォルトは true です。

以下はレポート設定ファイルの例です。

"includeRequestHeaders": true, "includeResponseHeaders": true, "includeUrlPassword": false, "includeRequestBody": true, "includeResponseBody": true, "restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports "restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these URL parameters are redacted from logs and reports

ロギング設定

CloudWatch Synthetics によって生成されたログに適用されます。リクエストログとレスポンスログの詳細度を制御します。

  • logRequest - すべてのリクエストを Canary ログに記録するかどうか。UI Canary の場合、ブラウザから送信された各リクエストがログに記録されます。デフォルトは false です。

  • logResponse - すべてのレスポンスを Canary ログに記録するかどうか。UI Canary の場合、ブラウザが受信したすべてのレスポンスをログに記録します。デフォルトは false です。

  • logRequestBody -リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、logRequest が true である場合にのみ適用されます。デフォルトは false です。

  • logResponseBody -リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、logResponse が true である場合にのみ適用されます。デフォルトは false です。

  • logRequestHeaders -リクエストヘッダーを Canary ログのリクエストとともに記録するかどうか。この設定は、logRequest が true である場合にのみ適用されます。デフォルトは false です。

  • logResponseHeaders -レスポンスヘッダーを Canary ログのレスポンスとともに記録するかどうか。この設定は、logResponse が true である場合にのみ適用されます。デフォルトは false です。

HTTP メトリクス設定

この Canary の CloudWatch Synthetics によって出力される、異なる HTTP ステータスコードを持つネットワークリクエストの数に関連するメトリクスの設定。

  • metric_2xx – この Canary の 2xx メトリクス (CanaryName ディメンションを含む) を出力するかどうか。デフォルトは true です。

  • metric_4xx – この Canary の 4xx メトリクス (CanaryName ディメンションを含む) を出力するかどうか。デフォルトは true です。

  • metric_5xx – この Canary の 5xx メトリクス (CanaryName ディメンションを含む) を出力するかどうか。デフォルトは true です。

  • failedRequestsMetric – この Canary の failedRequests メトリクス (CanaryName ディメンションを含む) を出力するかどうか。デフォルトは true です。

  • aggregatedFailedRequestsMetric – この Canary の failedRequests メトリクス (CanaryName ディメンションを含まない) を出力するかどうか。デフォルトは true です。

  • aggregated2xxMetric – この Canary の 2xx メトリクス (CanaryName ディメンションを含まない) を出力するかどうか。デフォルトは true です。

  • aggregated4xxMetric – この Canary の 4xx メトリクス (CanaryName ディメンションを含まない) を出力するかどうか。デフォルトは true です。

  • aggregated5xxMetric – この Canary の 5xx メトリクス (CanaryName ディメンションを含まない) を出力するかどうか。デフォルトは true です。

Canary メトリクス設定

CloudWatch Synthetics によって出力される他のメトリクスの設定。

  • failedCanaryMetric – この Canary の Failed メトリクス (CanaryName ディメンションを含む) を出力するかどうか。デフォルトは true です。

  • aggregatedFailedCanaryMetric – この Canary の Failed メトリクス (CanaryName ディメンションを含まない) を出力するかどうか。デフォルトは true です。

その他の設定

  • userAgent – ユーザーエージェントに追加する文字列。ユーザーエージェントは、リクエストヘッダーに含まれる文字列であり、ヘッドレスブラウザの使用時にアクセスしたウェブサイトに対してブラウザを識別します。CloudWatch Synthetics は CloudWatchSynthetics/canary-arn to the user agent を自動的に追加します。指定された設定は、生成されたユーザーエージェントに追加されます。追加するデフォルトのユーザーエージェント値は空の文字列 ("") です。

CloudWatch Synthetics 環境変数

環境変数を使用してログ記録レベルと形式を設定します。

ログ形式

CloudWatch Synthetics Playwright ランタイムは、Canary の実行ごとに CloudWatch ログを作成します。ログは、クエリしやすいように JSON 形式で書き込まれます。必要に応じて、ログ形式を TEXT に変更できます。

  • Environment variable name – CW_SYNTHETICS_LOG_FORMAT

  • Supported values – JSON、テキスト

  • Default – JSON

ログレベル

Debug モードを有効にすると詳細度は高くなりますが、トラブルシューティングに役立ちます。

  • Environment variable name – CW_SYNTHETICS_LOG_LEVEL

  • Supported values – TRACE、DEBUG、INFO、WARN、ERROR、FATAL

  • Default – INFO