# Playwright を使用する Node.js Canary スクリプトに利用可能なライブラリ関数
<a name="CloudWatch_Synthetics_Canaries_Nodejs_Playwright"></a>

このセクションでは、Node.js Playwright ランタイムを使用して Canary スクリプトで使用できるライブラリ関数について説明します。

**Topics**
+ [打ち上げ](#Synthetics_Library_Nodejs_Playwright_functions)
+ [newPage](#Synthetics_Library_Nodejs_Playwright_function_newPage)
+ [close](#Synthetics_Library_Nodejs_Playwright_function_close)
+ [getDefaultLaunchOptions](#Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions)
+ [executeStep](#Synthetics_Library_Nodejs_Playwright_function_executeStep)

## 打ち上げ
<a name="Synthetics_Library_Nodejs_Playwright_functions"></a>

この関数は、Playwright 起動関数を使用して Chromium ブラウザを起動し、ブラウザオブジェクトを返します。ブラウザバイナリを解凍し、ヘッドレスブラウザに適したデフォルトオプションを使用して Chromium ブラウザを起動します。`launch` 関数の詳細については、Playwright ドキュメントにある「[https://playwright.dev/docs/api/class-browsertype#browser-type-launch](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)」を参照してください。

 **使用方法** 

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

 **引数** 

`options` [オプション](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) (任意) は、ブラウザの構成可能なオプションのセットです。

 **戻り値** 

Promise `<Browser>`。ここで、[Browser](https://playwright.dev/docs/api/class-browser) は Playwright ブラウザインスタンスです。

この関数を再度呼び出すと、以前に開いたブラウザが閉じられてから新しいブラウザが開始されます。ブラウザを起動するときに、CloudWatch Synthetics で使用されている起動パラメータを上書きし、追加のパラメータを渡すことができます。例えば、次のコードスニペットでは、デフォルトの引数とデフォルトの実行可能パスを使用してブラウザを起動しますが、ビューポートは 800 x 600 ピクセルになります。詳細については、Playwright ドキュメントの「[Playwright 起動オプション](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)」を参照してください。

```
const browser = await synthetics.launch({
  defaultViewport: { 
      "deviceScaleFactor": 1, 
      "width": 800,
      "height": 600 
}});
```

 デフォルトでブラウザに渡される Chromium フラグを追加または上書きすることもできます。例えば、ウェブセキュリティを無効にするには、CloudWatch Synthetics の起動パラメータの引数に `--disable-web-security` フラグを追加します。

```
// This function adds the --disable-web-security flag to the launch parameters
const defaultOptions = await synthetics.getDefaultLaunchOptions();
const launchArgs = [...defaultOptions.args, '--disable-web-security'];
const browser = await synthetics.launch({
    args: launchArgs
  });
```

## newPage
<a name="Synthetics_Library_Nodejs_Playwright_function_newPage"></a>

`newPage()` 関数は新しい Playwright ページを作成して返します。Synthetics は Chrome DevTools Protocol (CDP) 接続を自動的にセットアップして、HTTP アーカイブ (HAR) 生成のネットワークキャプチャを有効にします。

 **使用方法** 

以下のいずれかの方法で、`newPage()` を使用してください。

 **1. 新しいブラウザコンテキストで新しいページを作成する：**

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

 **2. 指定したブラウザコンテキストで新しいページを作成する：**

```
// Create a new browser context
const browserContext = await browser.newContext();

// Create a new page in the specified browser context
const page = await synthetics.newPage(browserContext)
```

 **引数** 

Playwright [Browser](https://playwright.dev/docs/api/class-browser) インスタンスまたは Playwright [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) インスタンスのいずれかを受け入れます。

 **戻り値** 

Promise <Page>。ここで、Page は Playwright [Page](https://playwright.dev/docs/api/class-page) インスタンスです。

## close
<a name="Synthetics_Library_Nodejs_Playwright_function_close"></a>

現在開いているブラウザを閉じます。

 **使用方法** 

```
await synthetics.close();
```

スクリプトの `finally` ブロックでブラウザを閉じることをお勧めします。

 **引数** 

なし 

 **戻り値** 

ブラウザを起動するために Synthetics 起動関数で使用される Promise<void> を返します。

## getDefaultLaunchOptions
<a name="Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions"></a>

`getDefaultLaunchOptions()` 関数は、CloudWatch Synthetics で使用するブラウザ起動オプションを返します。

 **使用方法** 

```
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```

 **引数** 

なし 

 **戻り値** 

ブラウザを起動するために Synthetics `launch` 関数で使用される Playwright [起動オプション](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)を返します。

## executeStep
<a name="Synthetics_Library_Nodejs_Playwright_function_executeStep"></a>

`executeStep` 関数は、Synthetics スクリプトでステップを実行するために使用されます。CloudWatch Synthetics では、Synthetics ステップは、Canary スクリプトを一連の明確に定義されたアクションに分割する方法であり、アプリケーションジャーニーのさまざまな部分を個別にモニタリングできます。CloudWatch Synthetics は、ステップごとに以下を実行します。
+ ステップの開始前とステップの完了後にスクリーンショットを自動的にキャプチャします。ステップ内でスクリーンショットをキャプチャすることもできます。スクリーンショットはデフォルトでキャプチャされますが、Synthetics 設定を使用してオフにできます。
+ ステップの期間、`pass` または `fail` ステータス、ソースページと宛先ページの URL、関連するスクリーンショットなど、ステップ実行の詳細の概要を含むレポートが Canary 実行ごとに作成されます。CloudWatch Synthetics コンソールで実行を選択すると、**[ステップ]** タブで各ステップの実行の詳細を表示できます。
+ `SuccessPercent` および `Duration` CloudWatch メトリクスはステップごとに出力されるため、ユーザーは各ステップの可用性とレイテンシーをモニタリングできます。

 **使用方法** 

```
await synthetics.executeStep("mystepname", async function () {
  await page.goto(url, { waitUntil: 'load', timeout: 30000 });
}
```

**注記**  
ステップは順番に実行する必要があります。Promise では必ず `await` を使用してください。

 **引数** 
+ `stepName` string (必須) (ブール値) - Synthetics ステップの名前。
+ `functionToExecute` async function (必須) - Synthetics を実行する関数。この関数には、 ステップのロジックが含まれている必要があります。
+ `stepConfig` オブジェクト (オプション) — ステップ設定では、このステップのグローバル Synthetics 設定を上書きします。
  + `continueOnStepFailure` ブール値 (オプション) — このステップが失敗した後も Canary スクリプトの実行を継続するかどうか。
  + `screenshotOnStepStart` ブール値 (オプション) - このステップの開始時にスクリーンショットを作成するかどうか。
  + `screenshotOnStepSuccess` ブール値 (オプション) — このステップが成功した場合にスクリーンショットを作成するかどうか。
  + `screenshotOnStepFailure` ブール値 (オプション) — このステップが失敗した場合にスクリーンショットを作成するかどうか。
+ `page` — Playwright ページオブジェクト (オプション)

  Playwright ページオブジェクト。Synthetics は、このページオブジェクトを使用してスクリーンショットと URL をキャプチャします。デフォルトでは、Synthetics は、スクリーンショットや URL などのページの詳細をキャプチャするために `synthetics.newPage()` 関数が呼び出されたときに作成された Playwright ページを使用します。

 **戻り値** 

` functionToExecute` 関数によって返された値で解決される Promise を返します。スクリプトの例については、このガイドの「[Canary スクリプトのサンプルコード](CloudWatch_Synthetics_Canaries_Samples.md)」を参照してください。