使用 Playwright 執行時期撰寫 Node.js Canary 指令碼

為 Playwright 執行時期封裝 Node.js Canary 檔案

Canary 指令碼由 .js (CommonJS 語法) 或 .mjs(ES 語法) 檔案組成，其中包含您的 Synthetics 處理常式程式碼，以及程式碼所依賴的任何其他套件和模組。以 ES (ECMAScript) 格式建立的指令碼應使用 .mjs 作為副檔名，或包含具有「類型」：「模組」欄位集的 package.json 檔案。與 Node.js Puppeteer 等其他執行時期不同，您不需要將指令碼儲存在特定的資料夾結構中。可以直接封裝指令碼。使用您慣用的 zip 公用程式建立 .zip 檔案，並將處理常式檔案放在根目錄下。如果您的 Canary 指令碼仰賴 Synthetics 執行時期中未包含的其他套件或模組，可以將這些相依項新增至 .zip 檔案。為此，可以執行 npm install 命令，在 node_modules 目錄中安裝函式所需的程式庫。下列 CLI 命令範例會建立名為 my_deployment_package.zip 的 .zip 檔案，其中包含 index.js 或 index.mjs 檔案 (Synthetics 處理常式) 及其相依項。在此範例中，可以使用 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，以符合指令碼進入點的檔案名稱。可以選擇將 Canary 儲存在單獨的資料夾 (例如 myFolder/my_canary_filename.mjs) 中。如果將其存放在單獨的資料夾中，請在指令碼進入點中指定該路徑，例如 myFolder/my_canary_filename.functionName。

變更現有 Playwright 指令碼以用作 CloudWatch Synthetics Canary

可以編輯 Node.js 和 Playwright 的現有指令碼，以用作 Canary。如需 Playwright 的詳細資訊，請參閱 Playwright 程式庫文件。

可以使用儲存在檔案 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 Canary 執行。以下是更新的指令碼：

已更新 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 指標組態

與具有不同 HTTP 狀態碼之網路請求計數相關的指標組態，由 CloudWatch Synthetics 針對此 Canary 發出。

Canary 指標組態

CloudWatch Synthetics 發出之其他指標的組態。

其他組態

CloudWatch Synthetics 環境變數

使用環境變數設定記錄層級和格式。

記錄格式

CloudWatch Synthetics Playwright 執行時期會為每個 Canary 執行建立 CloudWatch 日誌。日誌以 JSON 格式撰寫，方便查詢。或者，您可以將日誌格式變更為 TEXT。

日誌層級

雖然啟用 Debug 模式會提升詳盡程度，但對於疑難排解很有用。