Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Library functions available for Node.js canary scripts using Playwright

This section describes the library functions that are available for canary scripts using the Node.js Playwright runtime.

launch

This function launches a Chromium browser using a Playwright launch function, and returns the browser object. It decompresses browser binaries and launches the chromium browser by using default options suitable for a headless browser. For more information about the launch function, see launch in the Playwright documentation.

Usage

const browser = await synthetics.launch();

Arguments

options options (optional) is a configurable set of options for the browser.

Returns

Promise <Browser> where Browser is a Playwright browser instance.

If this function is called again, a previously-opened browser is closed before initiating a new browser. You can override launch parameters used by CloudWatch Synthetics, and pass additional parameters when launching the browser. For example, the following code snippet launches a browser with default arguments and a default executable path, but with a viewport of 800 x 600 pixels. For more information, see Playwright launch options in the Playwright documentation.

const browser = await synthetics.launch({
  defaultViewport: { 
      "deviceScaleFactor": 1, 
      "width": 800,
      "height": 600 
}});

You can also add or override Chromium flags passed on by default to the browser. For example, you can disable web security by adding a --disable-web-security flag to arguments in the CloudWatch Synthetics launch parameters:

// 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

The newPage() function creates and returns a new Playwright page. Synthetics automatically sets up a Chrome DevTools Protocol (CDP) connection to enable network captures for HTTP archive (HAR) generation.

Usage

Use newPage() in either of the following ways:

1. Creating a new page in a new browser context:

const page = await synthetics.newPage(browser);

2. Creating a new page in a specified browser context:

// 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

Accepts either Playwright Browser instance or Playwright BrowserContext instance.

Returns

Promise <Page> where Page is a Playwright Page instance.

close

Closes the currently-opened browser.

Usage

await synthetics.close();

It is recommended to close the browser in a finally block of your script.

Arguments

None

Returns

Returns Promise<void> used by the Synthetics launch function for launching the browser.

getDefaultLaunchOptions

The getDefaultLaunchOptions() function returns the browser launch options that are used by CloudWatch Synthetics.

Usage

const defaultOptions = await synthetics.getDefaultLaunchOptions();

Arguments

None

Returns

Returns Playwright launch options used by the Synthetics launch function for launching the browser.

executeStep

The executeStep function is used to execute a step in a Synthetics script. In CloudWatch Synthetics, a Synthetics step is a way to break down your canary script into a series of clearly defined actions, allowing you to monitor different parts of your application journey separately. For each step, CloudWatch Synthetics does the following:

Usage

await synthetics.executeStep("mystepname", async function () {
  await page.goto(url, { waitUntil: 'load', timeout: 30000 });
}

Arguments

Returns

Returns a Promise that resolves with the value returned by the functionToExecute function. For an example script, see Sample code for canary scripts in this guide.