Playwright 런타임을 사용하여 Node.js 카나리 스크립트 작성

Playwright 런타임을 위한 Node.js 카나리 파일 패키징

카나리 스크립트는 Synthetics 핸들러 코드가 포함된 .js(CommonJS 구문) 또는 .mjs(ES 구문) 파일, 그리고 코드가 의존하는 추가 패키지 및 모듈로 구성됩니다. ES(ECMAScript) 형식으로 생성된 스크립트는 확장명으로 .mjs를 사용하거나, "type": "module" 필드 세트가 있는 package.json 파일을 포함해야 합니다. Node.js Puppeteer 같은 여타 런타임과 달리, 스크립트를 특정 폴더 구조에 저장하지 않아도 됩니다. 스크립트를 직접 패키징할 수 있습니다. 선호하는 zip 유틸리티를 사용하여 루트에 핸들러 파일이 있는 .zip 파일을 생성합니다. 카나리 스크립트가 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으로 설정해야 합니다. 카나리를 myFolder/my_canary_filename.mjs 같은 별도의 폴더에 저장할 수도 있습니다. 별도의 폴더에 저장하는 경우 스크립트 진입점에 해당 경로를 지정합니다(예: myFolder/my_canary_filename.functionName).

기존 Playwright 스크립트를 변경하여 CloudWatch Synthetics 카나리로 사용

카나리로 사용할 Node.js 및 Playwright의 기존 스크립트를 편집할 수 있습니다. Playwright에 대한 자세한 내용은 Playwright library 설명서를 참조하세요.

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();

아래의 단계를 수행하여 스크립트를 변환합니다.

이제 스크립트를 Synthetics 카나리로 실행할 준비가 되었습니다. 다음은 업데이트된 스크립트입니다.

ES6 형식의 업데이트된 스크립트

.mjs 확장명으로 저장된 스크립트 파일입니다.

import { synthetics } from '@amzn/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('@amzn/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 구성

synthetics.json이라는 이름의 선택적 JSON 구성 파일을 제공하여 Synthetics Playwright 런타임의 동작을 구성할 수 있습니다. 이 파일은 핸들러 파일과 동일한 위치에 패키징해야 합니다. 구성 파일은 선택 사항이지만, 구성 파일을 제공하지 않거나 구성 키가 누락된 경우 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
}

단계 구성

보고서 구성

CloudWatch Synthetics에서 생성한 모든 보고서(예: HAR 파일 및 Synthetics 단계 보고서)를 포함합니다. 민감한 데이터 수정 필드 restrictedHeaders 및 restrictedUrlParameters는 Synthetics에서 생성한 로그에도 적용됩니다.

다음은 보고서 구성 파일의 예입니다.

"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에서 생성한 로그에 적용됩니다. 요청 및 응답 로그의 상세 수준을 제어합니다.

HTTP 지표 구성

이 카나리에 대해 CloudWatch Synthetics에서 내보내는 HTTP 상태 코드가 서로 다른 네트워크 요청 수와 관련된 지표의 구성입니다.

카나리 지표 구성

CloudWatch Synthetics에서 내보낸 다른 지표에 대한 구성입니다.

기타 구성

CloudWatch Synthetics 환경 변수

환경 변수를 사용하여 로깅 수준 및 형식을 구성합니다.

로그 형식

CloudWatch Synthetics Playwright 런타임은 모든 카나리 실행에 대해 CloudWatch 로그를 생성합니다. 로그는 편리한 쿼리를 위해 JSON 형식으로 작성됩니다. 원하는 경우, 로그 형식을 TEXT로 변경할 수 있습니다.

로그 수준

Debug 모드를 활성화하면 상세 수준이 높아지긴 하지만, 문제 해결에 유용할 수 있습니다.