# 可用于使用 Selenium 的 Python 金丝雀脚本的库函数
<a name="CloudWatch_Synthetics_Canaries_Library_Python"></a>

本节列出了可用于 Python 金丝雀脚本的 Selenium 库函数。

**Topics**
+ [适用于所有金丝雀的 Python 和 Selenium 库类和函数](#CloudWatch_Synthetics_Library_allcanaries_Python)
+ [仅适用于 UI 金丝雀的 Python 和 Selenium 库类和函数](#CloudWatch_Synthetics_Library_Python_UIcanaries)

## 适用于所有金丝雀的 Python 和 Selenium 库类和函数
<a name="CloudWatch_Synthetics_Library_allcanaries_Python"></a>

以下用于 Python 的 CloudWatch Synthetics 库函数适用于所有金丝雀。

**Topics**
+ [SyntheticsConfiguration 类](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)
+ [SyntheticsLogger 类](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python)

### SyntheticsConfiguration 类
<a name="CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python"></a>

您可以使用 SyntheticsConfiguration 类来配置 Synthetics 库函数的行为。例如，您可以使用此类将 ` executeStep()` 函数配置为不捕获屏幕截图。

您可以在全局级别设置 CloudWatch Synthetics 配置。

函数定义：

#### set\$1config(options)
<a name="CloudWatch_Synthetics_Library_setConfig_Python"></a>

```
from aws_synthetics.common import synthetics_configuration
```

` options ` 是一个对象，它是一组适用于您的金丝雀的可配置选项。以下各节将介绍 ` options ` 中的可能字段。
+ `screenshot_on_step_start`（布尔值）– 是否在开始步骤之前捕获屏幕截图。
+ `screenshot_on_step_success`（布尔值）– 是否在成功完成步骤后捕获屏幕截图。
+ `screenshot_on_step_failure`（布尔值）– 是否在步骤失败后捕获屏幕截图。

 **with\$1screenshot\$1on\$1step\$1start(screenshot\$1on\$1step\$1start)** 

接受一个布尔参数，该参数指示是否在开始步骤之前捕获屏幕截图。

 **with\$1screenshot\$1on\$1step\$1success(screenshot\$1on\$1step\$1success)** 

接受一个布尔参数，该参数指示是否在成功完成步骤后捕获屏幕截图。

 **with\$1screenshot\$1on\$1step\$1failure(screenshot\$1on\$1step\$1failure)** 

接受一个布尔参数，该参数指示是否在步骤失败后捕获屏幕截图。

 **get\$1screenshot\$1on\$1step\$1start()** 

返回是否在开始步骤之前捕获屏幕截图。

 **get\$1screenshot\$1on\$1step\$1success()** 

返回是否在成功完成步骤后捕获屏幕截图。

 **get\$1screenshot\$1on\$1step\$1failure()** 

返回是否在步骤失败后捕获屏幕截图。

 **disable\$1step\$1screenshots()** 

禁用所有屏幕截图选项（get\$1screenshot\$1on\$1step\$1start、get\$1screenshot\$1on\$1step\$1success 和 get\$1screenshot\$1on\$1step\$1failure）。

 **enable\$1step\$1screenshots()** 

启用所有屏幕截图选项（get\$1screenshot\$1on\$1step\$1start、get\$1screenshot\$1on\$1step\$1success 和 get\$1screenshot\$1on\$1step\$1failure)。预设情况下，这些方法均未启用。

 **CloudWatch 指标的相关 setConfig(options)** 

对于使用 `syn-python-selenium-1.1` 或更新版本的金丝雀，**setConfig** 的 **(options)** 可包含以下布尔参数，这些参数决定将由金丝雀发布的指标。其中每个选项的默认值均为 `true`。以 ` aggregated` 开头的选项决定是否不带 ` CanaryName` 维度发出指标。您可以使用该等指标查看所有金丝雀的聚合结果。其他选项决定是否带 `CanaryName` 维度发出指标。您可以使用该等指标查看每个金丝雀的结果。

有关金丝雀发出的 CloudWatch 指标的列表，请参阅 [金丝雀发布的 CloudWatch 指标](CloudWatch_Synthetics_Canaries_metrics.md)。
+ `failed_canary_metric`（布尔值）– 是否发出此金丝雀的 ` Failed` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `failed_requests_metric`（布尔值）– 是否发出此金丝雀的 `Failed requests` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `2xx_metric`（布尔值）– 是否发出此金丝雀的 `2xx` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `4xx_metric`（布尔值）– 是否发出此金丝雀的 `4xx` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `5xx_metric`（布尔值）– 是否发出此金丝雀的 `5xx` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `step_duration_metric`（布尔值）– 是否发出此金丝雀的 `Step duration` 指标（带 `CanaryName` `StepName` 维度）。默认值为 `true`。
+ `step_success_metric`（布尔值）– 是否发出此金丝雀的 `Step success` 指标（带 `CanaryName` `StepName` 维度）。默认值为 `true`。
+ `aggregated_failed_canary_metric`（布尔值）– 是否发出此金丝雀的 `Failed` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregated_failed_requests_metric`（布尔值）– 是否发出此金丝雀的 `Failed Requests` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregated_2xx_metric`（布尔值）– 是否发出此金丝雀的 ` 2xx` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregated_4xx_metric`（布尔值）– 是否发出此金丝雀的 ` 4xx` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregated_5xx_metric`（布尔值）– 是否发出此金丝雀的 ` 5xx` 指标（不带 `CanaryName` 维度）。默认值为 `true`。

 **with\$12xx\$1metric(2xx\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `2xx` 指标。

 **with\$14xx\$1metric(4xx\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `4xx` 指标。

 **with\$15xx\$1metric(5xx\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `5xx` 指标。

 **withAggregated2xxMetric(aggregated2xxMetric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 `2xx` 指标。

 **withAggregated4xxMetric(aggregated4xxMetric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 `4xx` 指标。

 **with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 `5xx` 指标。

 **with\$1aggregated\$1failed\$1canary\$1metric(aggregated\$1failed\$1canary\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 `Failed` 指标。

 **with\$1aggregated\$1failed\$1requests\$1metric(aggregated\$1failed\$1requests\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 `Failed requests` 指标。

 **with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `Failed` 指标。

 **with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `Failed requests` 指标。

 **with\$1step\$1duration\$1metric(step\$1duration\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `Duration` 指标。

 **with\$1step\$1success\$1metric(step\$1success\$1metric)** 

接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `StepSuccess` 指标。

##### 用于启用或禁用指标的方法
<a name="CloudWatch_Synthetics_Python_setConfig_metrics"></a>

 **disable\$1aggregated\$1request\$1metrics()** 

禁用金丝雀发出以不带 ` CanaryName` 维度形式发出的所有请求指标。

 **disable\$1request\$1metrics()** 

禁用所有请求指标，包括每个金丝雀的指标和跨所有金丝雀聚合的指标。

 **disable\$1step\$1metrics()** 

禁用所有步骤指标，包括步骤成功指标和步骤持续时间指标。

 **enable\$1aggregated\$1request\$1metrics()** 

启用金丝雀发出以不带 ` CanaryName` 维度形式发出的所有请求指标。

 **enable\$1request\$1metrics()** 

启用所有请求指标，包括每个金丝雀的指标和跨所有金丝雀聚合的指标。

 **enable\$1step\$1metrics()** 

启用所有步骤指标，包括步骤成功指标和步骤持续时间指标。

 **在 UI 金丝雀中的使用情况** 

首先，导入 Synthetics 依赖关系并获取配置。然后，通过使用以下选项之一调用 setConfig 方法来设置每个选项的配置。

```
from aws_synthetics.common import synthetics_configuration

synthetics_configuration.set_config(
     {
        "screenshot_on_step_start": False,
        "screenshot_on_step_success": False,
        "screenshot_on_step_failure": True
     }
)

or
```

Or

```
synthetics_configuration.with_screenshot_on_step_start(False).with_screenshot_on_step_success(False).with_screenshot_on_step_failure(True)
```

若要禁用所有屏幕截图，请使用 disableStepScreenshots() 函数，如本示例所示。

```
synthetics_configuration.disable_step_screenshots()
```

您可以在代码中的任何位置启用和禁用屏幕截图。例如，若要仅禁用一个步骤的屏幕截图，请在运行该步骤之前禁用屏幕截图，然后在该步骤后启用它们。

##### 用于 UI 金丝雀的 set\$1config(options)
<a name="CloudWatch_Synthetics_Library_Python_UI"></a>

从 `syn-python-selenium-1.1` 开始，对于 UI 金丝雀，` set_config` 可包含以下布尔参数:
+ `continue_on_step_failure`（布尔值）– 是否在步骤失败（指 **executeStep** 函数）后继续运行金丝雀脚本。如果任何步骤失败，金丝雀运行仍将被标记为失败。默认值为 `false`。

### SyntheticsLogger 类
<a name="CloudWatch_Synthetics_Library_SyntheticsLogger_Python"></a>

`synthetics_logger` 将日志写入控制台和同一日志级别的本地日志文件。仅当日志级别与所调用的日志函数所需的日志记录级别相同或比其级别低时，此日志文件才会写入到这两个位置。

本地日志文件中的日志记录语句前面加上“DEBUG:”、“INFO:”等，以便与所调用的函数的日志级别相匹配。

如果要创建上载到 Amazon S3 结果位置的日志文件，不需要使用 `synthetics_logger`。您可以在 `/tmp` 文件夹中创建不同的日志文件。在 `/tmp` 文件夹下创建的任何文件都会作为构件上载到 S3 存储桶中的结果位置。

若要使用 `synthetics_logger`：

```
from aws_synthetics.common import synthetics_logger
```

****有用的函数定义：

获取日志级别：

```
log_level = synthetics_logger.get_level()
```

设置日志级别：

```
synthetics_logger.set_level()
```

使用指定级别记录消息。该级别可以是 `DEBUG`、` INFO`、`WARN`，或 `ERROR`，如以下语法示例所示：

```
synthetics_logger.debug(message, *args, **kwargs)
```

```
synthetics_logger.info(message, *args, **kwargs)
```

```
synthetics_logger.log(message, *args, **kwargs)
```

```
synthetics_logger.warning(message, *args, **kwargs)
```

```
synthetics_logger.error(message, *args, **kwargs)
```

有关调试参数的信息，请参阅标准 Python 文档中的 [logging.debug](https://docs.python.org/3/library/logging.html#logging.debug)

在这些日志记录函数中，`message` 为消息格式的字符串。`args` 为合并到使用字符串格式运算符的 `msg` 中的参数。

`kwargs` 中有三个关键字参数：
+ `exc_info` – 如果未评估为 false，则会将异常信息添加到日志记录消息中。
+ `stack_info` – 默认值为 false。如果为 true，则会将堆栈信息添加到日志记录消息中，包括实际的日志记录调用。
+ `extra` – 第三个可选关键字参数，您可以使用该参数将用于填充 `LogRecord`（为具有用户定义属性的日志记录事件而创建）的 `__dict__` 传入字典。

示例：

使用 `DEBUG` 级别记录消息：

```
synthetics_logger.debug('Starting step - login.')
```

使用 `INFO` 级别记录消息。`logger.log` 是 `logger.info` 的同义词：

```
synthetics_logger.info('Successfully completed step - login.')
```

或者

```
synthetics_logger.log('Successfully completed step - login.')
```

使用 `WARN` 级别记录消息：

```
synthetics_logger.warning('Warning encountered trying to publish %s', 'CloudWatch Metric')
```

使用 `ERROR` 级别记录消息：

```
synthetics_logger.error('Error encountered trying to publish %s', 'CloudWatch Metric')
```

记录异常：

```
synthetics_logger.exception(message, *args, **kwargs)
```

使用 `ERROR` 级别记录消息。异常信息将会添加到日志记录消息中。您应该只从异常处理程序调用此函数。

有关异常参数的信息，请参阅标准 Python 文档中的 [logging.exception](https://docs.python.org/3/library/logging.html#logging.exception)

`message` 为消息格式的字符串。`args` 为合并到使用字符串格式运算符的 `msg` 中的参数。

`kwargs` 中有三个关键字参数：
+ `exc_info` – 如果未评估为 false，则会将异常信息添加到日志记录消息中。
+ `stack_info` – 默认值为 false。如果为 true，则会将堆栈信息添加到日志记录消息中，包括实际的日志记录调用。
+ `extra` – 第三个可选关键字参数，您可以使用该参数将用于填充 `LogRecord`（为具有用户定义属性的日志记录事件而创建）的 `__dict__` 传入字典。

示例：

```
synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric')
```

## 仅适用于 UI 金丝雀的 Python 和 Selenium 库类和函数
<a name="CloudWatch_Synthetics_Library_Python_UIcanaries"></a>

以下用于 Python 的 CloudWatch Synthetics Selenium 库函数仅适用于 UI 金丝雀。

**Topics**
+ [SyntheticsBrowser 类](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser)
+ [SyntheticsWebDriver 类](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)

### SyntheticsBrowser 类
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsBrowser"></a>

**注意**  
Chrome 是唯一支持 `SyntheticsBrowser` 的浏览器。

当您通过调用 `synthetics_webdriver.Chrome()` 创建浏览器实例时，返回的浏览器实例类型为 `SyntheticsBrowser`。` SyntheticsBrowser` 类继承自 WebDriver 类，并提供对 [WebDriver](https://www.selenium.dev/documentation/webdriver/) 公开的所有方法的访问权限。它控制 ChromeDriver，并使 Canary 脚本能够驱动浏览器，从而允许 Selenium WebDriver 使用 Synthetics。

**注意**  
Synthetics 重写了 WebDriver 的 [quit](https://www.selenium.dev/selenium/docs/api/py/selenium_webdriver_firefox/selenium.webdriver.firefox.webdriver.html) 方法，使其不执行任何操作。您无需担心关闭浏览器的问题，因为 Synthetics 会为您处理此事。

除了标准的 Selenium 方法之外，它还提供了以下方法。

**Topics**
+ [set\$1viewport\$1size(width, height)](#CloudWatch_Synthetics_Library_set_viewport_size)
+ [save\$1screenshot(filename, suffix)](#CloudWatch_Synthetics_Library_save_screenshot)

#### set\$1viewport\$1size(width, height)
<a name="CloudWatch_Synthetics_Library_set_viewport_size"></a>

设置浏览器的视区。示例：

```
browser.set_viewport_size(1920, 1080)
```

#### save\$1screenshot(filename, suffix)
<a name="CloudWatch_Synthetics_Library_save_screenshot"></a>

将屏幕截图保存到 `/tmp` 目录。屏幕截图将上载到 S3 存储桶中的金丝雀构件文件夹。

*filename* 是屏幕截图的文件名，*suffix* 是用于命名屏幕截图的可选字符串。

示例：

```
browser.save_screenshot('loaded.png', 'page1')
```

### SyntheticsWebDriver 类
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver"></a>

要使用此类，请在脚本中使用以下内容：

```
from aws_synthetics.selenium import synthetics_webdriver
```

**Topics**
+ [add\$1execution\$1error(errorMessage, ex);](#CloudWatch_Synthetics_Library_Python_addExecutionError)
+ [add\$1user\$1agent(user\$1agent\$1str)](#CloudWatch_Synthetics_Library_add_user_agent)
+ [execute\$1step(step\$1name, function\$1to\$1execute)](#CloudWatch_Synthetics_Library_Python_execute_step)
+ [get\$1http\$1response(url)](#CloudWatch_Synthetics_Library_Python_get_http_response)
+ [Chrome()](#CloudWatch_Synthetics_Library_Python_Chrome)

#### add\$1execution\$1error(errorMessage, ex);
<a name="CloudWatch_Synthetics_Library_Python_addExecutionError"></a>

`errorMessage` 描述错误，`ex` 指遇到的异常

您可以使用 `add_execution_error` 来设置金丝雀的执行错误。它会在不中断脚本执行的情况下导致金丝雀失败。它也不会影响 `successPercent` 指标。

只有当错误对于指示金丝雀脚本成功或故障并不重要时，才应将错误作为执行错误进行跟踪。

以下是使用 `add_execution_error` 的示例。您将会监控端点的可用性，并在页面加载完成后捕获屏幕截图。由于捕获屏幕截图故障并不会决定端点的可用性，因此您可以捕获在截图时遇到的任何错误，并将它们添加为执行错误。可用性指标仍会指示端点已启动并正在运行，但金丝雀状态会被标记为失败。以下示例代码块将会捕获此类错误并将其添加为执行错误。

```
try:
    browser.save_screenshot("loaded.png")  
except Exception as ex:
   self.add_execution_error("Unable to take screenshot", ex)
```

#### add\$1user\$1agent(user\$1agent\$1str)
<a name="CloudWatch_Synthetics_Library_add_user_agent"></a>

将 `user_agent_str` 的值附加到浏览器的用户代理标头。您必须在创建浏览器实例之前分配 `user_agent_str`。

示例：

```
await synthetics_webdriver.add_user_agent('MyApp-1.0')
```

`add_user_agent` 应在 `async` 函数内使用。

#### execute\$1step(step\$1name, function\$1to\$1execute)
<a name="CloudWatch_Synthetics_Library_Python_execute_step"></a>

处理一个函数。它还执行以下操作：
+ 记录步骤开始。
+ 获取名为 `<stepName>-starting` 的屏幕截图。
+ 启动计时器。
+ 执行提供的函数。
+ 如果函数正常返回，则计为通过。如果函数引发异常，则计为失败。
+ 结束计时器。
+ 记录步骤是通过还是失败
+ 获取名为 `<stepName>-succeeded` 或 ` <stepName>-failed` 的屏幕截图。
+ 发出 `stepName` `SuccessPercent` 指标，100 表示通过，0 表示失败。
+ 发出 `stepName` `Duration` 指标，指标的值基于步骤开始和结束时间。
+ 最后，返回 `functionToExecute` 返回的内容或重新抛出 `functionToExecute` 抛出的内容。

示例：

```
from selenium.webdriver.common.by import By

def custom_actions():
        #verify contains
        browser.find_element(By.XPATH, "//*[@id=\"id_1\"][contains(text(),'login')]")
        #click a button
        browser.find_element(By.XPATH, '//*[@id="submit"]/a').click()

    await synthetics_webdriver.execute_step("verify_click", custom_actions)
```

#### get\$1http\$1response(url)
<a name="CloudWatch_Synthetics_Library_Python_get_http_response"></a>

对提供的 URL 发出 HTTP 请求并返回 HTTP 请求的响应代码。如果 HTTP 请求期间发生异常，则返回值为“error”的字符串。

示例：

```
response_code = syn_webdriver.get_http_response(url)
if not response_code or response_code == "error" or response_code < 200 or response_code > 299:
    raise Exception("Failed to load page!")
```

#### Chrome()
<a name="CloudWatch_Synthetics_Library_Python_Chrome"></a>

启动 Chromium 浏览器的实例并返回创建的浏览器实例。

示例：

```
browser = synthetics_webdriver.Chrome()
browser.get("https://example.com/)
```

要以隐身模式启动浏览器，请遵循以下说明:

```
add_argument('——incognito')
```

要添加代理设置，请遵循以下说明:

```
add_argument('--proxy-server=%s' % PROXY)
```

示例：

```
from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_argument("——incognito")
browser = syn_webdriver.Chrome(chrome_options=chrome_options)
```