# Funções de biblioteca disponíveis para scripts de canário Node.js usando o Playwright
<a name="CloudWatch_Synthetics_Canaries_Nodejs_Playwright"></a>

Esta seção descreve as funções de biblioteca que estão disponíveis para scripts de canário usando o runtime do Playwright para Node.js.

**Topics**
+ [execução](#Synthetics_Library_Nodejs_Playwright_functions)
+ [newPage](#Synthetics_Library_Nodejs_Playwright_function_newPage)
+ [feche](#Synthetics_Library_Nodejs_Playwright_function_close)
+ [getDefaultLaunchOptions](#Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions)
+ [executeStep](#Synthetics_Library_Nodejs_Playwright_function_executeStep)

## execução
<a name="Synthetics_Library_Nodejs_Playwright_functions"></a>

Esta função inicia um navegador Chromium usando uma função de inicialização do Playwright e retorna o objeto do navegador. Ela descompacta os binários do navegador e inicia o navegador Chromium usando as opções padrão adequadas para um navegador sem cabeçalho. Para obter mais informações sobre a função `launch`, consulte [https://playwright.dev/docs/api/class-browsertype#browser-type-launch](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) na documentação do Playwright.

 **Usage** 

```
const browser = await synthetics.launch();
```

 **Argumentos** 

`options` [options](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) (opcional) é um conjunto configurável de opções a serem definidas no navegador.

 **Devoluções** 

Promise `<Browser>` em que [Browser](https://playwright.dev/docs/api/class-browser) é uma instância do navegador do Playwright.

Se esta função for chamada novamente, um navegador aberto anteriormente será fechado antes de iniciar um novo navegador. É possível substituir os parâmetros de inicialização usados pelo CloudWatch Synthetics e passar outros parâmetros ao iniciar o navegador. Por exemplo, o trecho de código a seguir inicia um navegador com argumentos padrão e um caminho executável padrão, mas com uma janela de visualização de 800 x 600 pixels. Para obter mais informações, consulte as [opções de inicialização do Playwright](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) na documentação do Playwright.

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

 Você também pode adicionar ou substituir os sinalizadores do Chromium passados por padrão para o navegador. Por exemplo, você pode desabilitar a segurança da Web ao adicionar um sinalizador `--disable-web-security` para argumentos nos parâmetros de inicialização do CloudWatch Synthetics: 

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

A função `newPage()` cria e retorna uma nova página do Playwright. O Synthetics configura automaticamente uma conexão do Chrome DevTools Protocol (CDP) para permitir capturas de rede para geração de arquivos HTTP (HAR).

 **Usage** 

Use `newPage()` em uma das seguintes opções:

 **1. Criar uma página em um novo contexto de navegador:** 

```
const page = await synthetics.newPage(browser);
```

 **2. Criar uma página em um contexto de navegador específico:** 

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

 **Argumentos** 

Aceita a instância [Browser](https://playwright.dev/docs/api/class-browser) ou [BrowserContext](https://playwright.dev/docs/api/class-browsercontext) do Playwright. 

 **Devoluções** 

Promise <Page> em que Page é uma instância [Page](https://playwright.dev/docs/api/class-page) do Playwright.

## feche
<a name="Synthetics_Library_Nodejs_Playwright_function_close"></a>

Fecha o navegador aberto no momento.

 **Usage** 

```
await synthetics.close();
```

É recomendável fechar o navegador em um bloco `finally` do script.

 **Argumentos** 

Nenhum 

 **Devoluções** 

Retorna Promise<void> usada pela função de inicialização do Synthetics para iniciar o navegador.

## getDefaultLaunchOptions
<a name="Synthetics_Library_Nodejs_Playwright_function_getDefaultLaunchOptions"></a>

A função `getDefaultLaunchOptions()` retorna as opções de inicialização do navegador que serão usadas pelo CloudWatch Synthetics.

 **Usage** 

```
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```

 **Argumentos** 

Nenhum 

 **Devoluções** 

Retorna as [opções de inicialização](https://playwright.dev/docs/api/class-browsertype#browser-type-launch) do Playwright usadas pela função `launch` do Synthetics para iniciar o navegador.

## executeStep
<a name="Synthetics_Library_Nodejs_Playwright_function_executeStep"></a>

A função `executeStep` é usada para executar uma etapa em um script do Synthetics. No CloudWatch Synthetics, uma etapa do Synthetics é uma forma de dividir seu script do canário em uma série de ações claramente definidas, permitindo que você monitore diferentes partes de sua jornada de aplicação separadamente. Para cada etapa, o CloudWatch Synthetics faz o seguinte:
+ Obtém automaticamente uma captura de tela antes do início da etapa e após sua conclusão. Você também pode obter capturas de tela dentro de uma etapa. As capturas de tela são realizadas por padrão, mas podem ser desativadas usando as configurações do Synthetics.
+ Um relatório, incluindo um resumo, dos detalhes da execução da etapa, como a duração de uma etapa, os status `pass` ou `fail`, os URLs das páginas de origem e destino, as capturas de tela associadas etc., é criado para cada execução do canário. Ao escolher uma execução no console do CloudWatch Synthetics, você pode visualizar os detalhes da execução de cada etapa na guia **Etapa**.
+ As métricas `SuccessPercent` e `Duration` do CloudWatch são emitidas para cada etapa, permitindo que os usuários monitorem a disponibilidade e a latência de cada etapa.

 **Usage** 

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

**nota**  
As etapas devem ser executadas sequencialmente. Certifique-se de usar `await` em promises.

 **Argumentos** 
+ `stepName` string (obrigatória) (booliano): nome da etapa do Synthetics. 
+ `functionToExecute` função assíncrona (obrigatória): a função que você deseja que o Synthetics execute. Essa função deve conter a lógica da etapa.
+ `stepConfig` objeto (opcional): a configuração da etapa substitui a configuração global de Synthetics para esta etapa.
  + `continueOnStepFailure` booliano (opcional): se você deve continuar ou não executando o script do canário após esta etapa falhar. 
  + `screenshotOnStepStart` booliano (opcional): se deve ou não obter uma captura de tela no início desta etapa. 
  + `screenshotOnStepSuccess` booliano (opcional): se deve ou não obter uma captura de tela se esta etapa tiver êxito. 
  + `screenshotOnStepFailure` booliano (opcional): se deve ou não obter uma captura de tela se esta etapa falhar. 
+ `page`: objeto de página do Playwright (opcional)

  Um objeto de página do Playwright. O Synthetics usa esse objeto de página para obter capturas de tela e URLs. Por padrão, o Synthetics usa a página do Playwright criada quando a função `synthetics.newPage()` é chamada para capturar detalhes da página, como capturas de tela e URLs.

 **Devoluções** 

Retorna uma Promise que é resolvida com o valor retornado pela função ` functionToExecute`. Para ver um exemplo de script, consulte [Código de exemplo para scripts do canário](CloudWatch_Synthetics_Canaries_Samples.md) neste guia.