# Playwright을 사용하여 Node.js 카나리 스크립트에 사용할 수 있는 라이브러리 함수
<a name="CloudWatch_Synthetics_Canaries_Nodejs_Playwright"></a>

이 섹션에서는 Node.js Playwright 런타임을 사용하여 카나리 스크립트에 사용할 수 있는 라이브러리 함수에 대해 설명합니다.

**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)

## 시작
<a name="Synthetics_Library_Nodejs_Playwright_functions"></a>

이 함수는 Playwright 시작 함수를 사용하여 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)(선택 사항)은 브라우저에 설정할 수 있는 구성 가능한 옵션 집합입니다.

 **반환** 

[Browser](https://playwright.dev/docs/api/class-browser)가 Playwright 브라우저 인스턴스인 Promise `<Browser>`가 반환됩니다.

이 함수를 다시 직접적으로 호출하면 새 브라우저를 시작하기 전에 이전에 열었던 브라우저가 닫힙니다. 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` 플래그를 추가하여 웹 보안을 사용 중지할 수 있습니다.

```
// 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는 HTTP 아카이브(HAR) 생성을 위한 네트워크 캡처를 활성화하기 위해 Chrome DevTools Protocol(CDP) 연결을 자동으로 설정합니다.

 **사용량** 

다음 중 한 가지 방법으로 `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) 인스턴스 중에 하나를 수락합니다.

 **반환** 

Page가 Playwright [Page](https://playwright.dev/docs/api/class-page) 인스턴스인 Promise <Page>가 반환됩니다.

## 해지
<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 단계는 카나리 스크립트를 명확하게 정의된 작업으로 세분화하여, 애플리케이션 여정의 다양한 부분을 개별적으로 모니터링할 수 있는 방법입니다. 각 단계에 대해 CloudWatch Synthetics는 다음을 수행합니다.
+ 단계가 시작되기 전과 단계가 완료된 후 스크린샷을 자동으로 캡처합니다. 단계 내에서 스크린샷을 캡처할 수도 있습니다. 스크린샷은 기본적으로 캡처되지만, Synthetics 구성을 사용하여 끌 수 있습니다.
+ 각 카나리 실행에 대해 단계 지속 시간, `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` 부울(선택 사항) - 이 단계가 실패한 후에도 카나리 스크립트를 계속 실행할지 여부입니다.
  + `screenshotOnStepStart` 부울(선택 사항) - 이 단계를 시작할 때 스크린샷을 생성할지 여부입니다.
  + `screenshotOnStepSuccess` 부울(선택 사항) - 이 단계가 성공할 경우 스크린샷을 생성할지 여부입니다.
  + `screenshotOnStepFailure` 부울(선택 사항) - 이 단계가 성공할 경우 스크린샷을 생성할지 여부입니다.
+ `page` - Playwright 페이지 객체(선택 사항)

  Playwright 페이지 객체입니다. Synthetics는이 페이지 객체를 사용하여 스크린샷과 URL을 캡처합니다. 기본적으로 Synthetics는 스크린샷과 URL 등의 페이지 세부 정보를 캡처하기 위해 `synthetics.newPage()` 함수를 직접적으로 호출할 때 생성된 Playwright 페이지를 사용합니다.

 **반환** 

` functionToExecute` 함수에서 반환된 값을 확인하는 Promise가 반환됩니다. 예제 스크립트는 이 가이드의 [canary 스크립트 샘플 코드](CloudWatch_Synthetics_Canaries_Samples.md) 섹션을 참조하세요.