# Playwright ランタイムを使用した Node.js Canary スクリプトの記述
<a name="Synthetics_WritingCanary_Nodejs_Playwright"></a>

**Topics**
+ [Playwright ランタイム用の Node.js Canary ファイルのパッケージ化](#Synthetics_canary_Nodejs_Playwright_package)
+ [既存の Playwright スクリプトを変更して CloudWatch Synthetics の Canary として使用する](#CloudWatch_Synthetics_canary_edit_Playwright_script)
+ [CloudWatch Synthetics の設定](#Synthetics_canary_configure_Playwright_script)

## Playwright ランタイム用の Node.js Canary ファイルのパッケージ化
<a name="Synthetics_canary_Nodejs_Playwright_package"></a>

 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 として使用する
<a name="CloudWatch_Synthetics_canary_edit_Playwright_script"></a>

Node.js と Playwright の既存のスクリプトを編集して Canary として使用できます。Playwright の詳細については、「[Playwright ライブラリ](https://playwright.dev/docs/api/class-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
     };
   ```

1. `Synthetics Playwright module` を依存関係としてインポートします。

   ```
   import { synthetics } from '@aws/synthetics-playwright';
   ```

1. Synthetics `Launch` 関数を使用してブラウザを起動します。

   ```
   const browser = await synthetics.launch();
   ```

1. Synthetics `newPage` 関数を使用して新しい Playwright ページを作成します。

   ```
   const page = await synthetics.newPage();
   ```

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

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

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

```
import { synthetics } from '@aws/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('@aws/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 の設定
<a name="Synthetics_canary_configure_Playwright_script"></a>

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 によって生成されたすべてのレポートが含まれます。機密データの編集フィールド `restrictedHeaders` と `restrictedUrlParameters` は、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 環境変数
<a name="Synthetics_canary_Nodejs_Playwright_script"></a>

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

 **ログ形式** 

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