# 可用于使用 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();
```
**参数**
`options` [选项](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)（可选）是浏览器的一组可配置的选项。
**返回值**
Promise ``，其中 [Browser](https://playwright.dev/docs/api/class-browser) 是一个 Playwright 浏览器实例。
如果再次调用该函数，则先前打开的浏览器将在启动新浏览器之前关闭。您可以覆盖 CloudWatch Synthetics 使用的启动参数，并在启动浏览器时传递其他参数。例如，以下代码段以默认参数和默认可执行文件路径启动浏览器，但视区为 800 x 600 像素。有关更多信息，请参阅 Playwright 文档中的 [Playwright launch options](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` 标志来禁用 Web 安全：
```
// 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)
```
**参数**
接受 Playwright [Browser](https://playwright.dev/docs/api/class-browser) 实例或 Playwright [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) 实例。
**返回值**
Promise ，其中 Page 是 Playwright [Page](https://playwright.dev/docs/api/class-page) 实例。
## 关闭
关闭当前打开的浏览器。
**用法**
```
await synthetics.close();
```
建议在脚本的 `finally` 块中关闭浏览器。
**参数**
无
**返回值**
返回 Synthetics 启动函数在启动浏览器时使用的 Promise。
## getDefaultLaunchOptions
`getDefaultLaunchOptions()` 函数返回 CloudWatch Synthetics 使用的浏览器启动选项。
**用法**
```
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```
**参数**
无
**返回值**
返回 Synthetics `launch` 函数用于启动浏览器的 Playwright [启动选项](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`。
**参数**
+ `stepName` 字符串（必填）（布尔值）– Synthetics 步骤的名称。
+ `functionToExecute` 异步函数（必填）– 您希望 Synthetics 运行的函数。此函数应包含该步骤的逻辑。
+ `stepConfig` 对象（可选）– 步骤配置覆盖此函数的全局 Synthetics 配置。
+ `continueOnStepFailure` 布尔值（可选）– 在此步骤失败后是否继续运行 Canary 脚本。
+ `screenshotOnStepStart` 布尔值（可选）– 在此步骤开始是否时捕获屏幕截图。
+ `screenshotOnStepSuccess` 布尔值（可选）– 在此步骤成功时是否捕获屏幕截图。
+ `screenshotOnStepFailure` 布尔值（可选）– 在此步骤失败后是否捕获屏幕截图。
+ `page` – Playwright 页面对象（可选）
Playwright 页面对象。Synthetics 使用此页面对象来捕获屏幕截图和 URL。默认情况下，Synthetics 使用调用 `synthetics.newPage()` 函数时创建的 Playwright 页面来捕获屏幕截图和 URL 等页面详细信息。
**返回值**
返回 Promise，该参数使用 ` functionToExecute` 函数返回的值进行解析。有关示例脚本，请参阅本指南中的 [金丝雀脚本示例代码](CloudWatch_Synthetics_Canaries_Samples.md)。