本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 適用於使用 Playwright 之 Node.js Canary 指令碼的程式庫函式
本節說明可供使用 Node.js Playwright 執行時期的 Canary 指令碼使用的程式庫函式。
**Topics**
+ [
## 啟動
](#Synthetics_Library_Nodejs_Playwright_functions)
+ [
## newPage
](#Synthetics_Library_Nodejs_Playwright_function_newPage)
+ [
## 關閉
](#Synthetics_Library_Nodejs_Playwright_function_close)
+ [
## getDefaultLaunchOptions
](#Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions)
+ [
## executeStep
](#Synthetics_Library_Nodejs_Playwright_function_executeStep)
## 啟動
此函式使用 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();
```
**Arguments (引數)**
`options` [options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) (選用) 是一組可設定的瀏覽器選項。
**傳回值**
承諾 ``，其中 [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 旗標。舉例來說，您可以透過將 `--disable-web-security` 旗標新增至 CloudWatch Synthetics 啟動參數中的引數來停用網路安全功能：
```
// 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
`newPage()` 函式會建立並傳回新的 Playwright 頁面。Synthetics 會自動設定 Chrome DevTools 通訊協定 (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)
```
**Arguments (引數)**
接受 Playwright [瀏覽器](https://playwright.dev/docs/api/class-browser)執行個體或 Playwright [ BrowserContext](https://playwright.dev/docs/api/class-browsercontext)執行個體。
**傳回值**
承諾 ，其中 Page 是 Playwright [Page](https://playwright.dev/docs/api/class-page) 執行個體。
## 關閉
關閉目前開啟的瀏覽器。
**用途**
```
await synthetics.close();
```
建議您在指令碼的 `finally` 區塊中關閉瀏覽器。
**Arguments (引數)**
無
**傳回值**
傳回 Synthetics 啟動函式用於啟動瀏覽器的 Promise。
## getDefaultLaunchOptions
`getDefaultLaunchOptions()` 函數會傳回 CloudWatch Synthetics 使用的瀏覽器啟動選項。
**用途**
```
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```
**Arguments (引數)**
無
**傳回值**
傳回 Synthetics `launch` 函式用於啟動瀏覽器的 Playwright [launch options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)。
## executeStep
`executeStep` 函式用於在 Synthetics 指令碼中執行步驟。在 CloudWatch Synthetics 中，Synthetics 步驟是將 Canary 指令碼分解為一系列明確定義動作的方式，讓您能夠分別監控應用程式旅程的不同環節。對於每個步驟，CloudWatch Synthetics 會執行下列動作：
+ 在步驟開始之前和步驟完成之後自動擷取螢幕畫面。也可以在步驟內擷取螢幕畫面。螢幕擷取畫面預設為擷取，但可以使用 Synthetics 組態關閉。
+ 針對每個 Canary 執行過程，系統會產生一份報告，包括步驟執行詳細資訊的摘要，例如步驟持續時間、`pass` 或 `fail` 狀態、來源和目的地頁面 URL、關聯的螢幕擷取畫面等。當您在 CloudWatch Synthetics 主控台中選擇執行時，可以在**步驟**索引標籤上檢視每個步驟的執行詳細資訊。
+ 每個步驟都會發出 `SuccessPercent` 和 `Duration` CloudWatch 指標，讓使用者能夠監控每個步驟的可用性和延遲。
**用途**
```
await synthetics.executeStep("mystepname", async function () {
await page.goto(url, { waitUntil: 'load', timeout: 30000 });
}
```
**注意**
步驟應循序執行。請務必對 promise 使用 `await`。
**Arguments (引數)**
+ `stepName` 字串 (必要) (布林值) – Synthetics 步驟的名稱。
+ `functionToExecute` 非同步函式 (必要) – 您希望 Synthetics 執行的函式。此函式應包含步驟的邏輯。
+ `stepConfig` 物件 (選用) – 步驟組態覆寫此函式的全域 Synthetics 組態。
+ `continueOnStepFailure` 布林值 (選用) – 此步驟失敗後是否繼續執行 Canary 指令碼。
+ `screenshotOnStepStart` 布林值 (選用) – 是否要在此步驟開始時擷取螢幕畫面。
+ `screenshotOnStepSuccess` 布林值 (選用) – 如果此步驟成功，是否擷取螢幕畫面。
+ `screenshotOnStepFailure` 布林值 (選用) – 如果此步驟失敗，是否擷取螢幕畫面。
+ `page` – Playwright 頁面物件 (選用)
Playwright 頁面物件。Synthetics 使用此頁面物件來擷取螢幕畫面和 URL。根據預設，Synthetics 使用呼叫 `synthetics.newPage()` 函式時建立的 Playwright 頁面來擷取頁面詳細資訊，例如螢幕擷取畫面和 URL。
**傳回值**
傳回 Promise，使用 ` functionToExecute` 函式傳回的值解析。如需範例指令碼，請參閱本指南中的 [Canary 指令碼的範本程式碼](CloudWatch_Synthetics_Canaries_Samples.md)。