可用于使用 Selenium 的 Python 金丝雀脚本的库函数
本节列出了可用于 Python 金丝雀脚本的 Selenium 库函数。
适用于所有金丝雀的 Python 和 Selenium 库类和函数
以下用于 Python 的 CloudWatch Synthetics 库函数适用于所有金丝雀。
SyntheticsConfiguration 类
您可以使用 SyntheticsConfiguration 类来配置 Synthetics 库函数的行为。例如,您可以使用此类将 executeStep()
函数配置为不捕获屏幕截图。
您可以在全局级别设置 CloudWatch Synthetics 配置。
函数定义:
set_config(options)
from aws_synthetics.common import synthetics_configuration
是一个对象,它是一组适用于您的金丝雀的可配置选项。以下各节将介绍 options
中的可能字段。options
screenshot_on_step_start
(布尔值)– 是否在开始步骤之前捕获屏幕截图。screenshot_on_step_success
(布尔值)– 是否在成功完成步骤后捕获屏幕截图。screenshot_on_step_failure
(布尔值)– 是否在步骤失败后捕获屏幕截图。
with_screenshot_on_step_start(screenshot_on_step_start)
接受一个布尔参数,该参数指示是否在开始步骤之前捕获屏幕截图。
with_screenshot_on_step_success(screenshot_on_step_success)
接受一个布尔参数,该参数指示是否在成功完成步骤后捕获屏幕截图。
with_screenshot_on_step_failure(screenshot_on_step_failure)
接受一个布尔参数,该参数指示是否在步骤失败后捕获屏幕截图。
get_screenshot_on_step_start()
返回是否在开始步骤之前捕获屏幕截图。
get_screenshot_on_step_success()
返回是否在成功完成步骤后捕获屏幕截图。
get_screenshot_on_step_failure()
返回是否在步骤失败后捕获屏幕截图。
disable_step_screenshots()
禁用所有屏幕截图选项(get_screenshot_on_step_start、get_screenshot_on_step_success 和 get_screenshot_on_step_failure)。
enable_step_screenshots()
启用所有屏幕截图选项(get_screenshot_on_step_start、get_screenshot_on_step_success 和 get_screenshot_on_step_failure)。预设情况下,这些方法均未启用。
CloudWatch 指标的相关 setConfig(options)
对于使用 syn-python-selenium-1.1
或更高版本的金丝雀,setConfig 的 (options) 可包含以下布尔参数,这些参数决定将由金丝雀发布的指标。其中每个选项的默认值均为 true
。以 aggregated
开头的选项决定是否不带 CanaryName
维度发出指标。您可以使用该等指标查看所有金丝雀的聚合结果。其他选项决定是否带 CanaryName
维度发出指标。您可以使用该等指标查看每个金丝雀的结果。
有关金丝雀发出的 CloudWatch 指标的列表,请参阅 金丝雀发布的 CloudWatch 指标。
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_2xx_metric(2xx_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出带 CanaryName
维度的 2xx
指标。
with_4xx_metric(4xx_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出带 CanaryName
维度的 4xx
指标。
with_5xx_metric(5xx_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出带 CanaryName
维度的 5xx
指标。
withAggregated2xxMetric(aggregated2xxMetric)
接受一个布尔参数,该参数指定是否为此金丝雀发出不带维度的 2xx
指标。
withAggregated4xxMetric(aggregated4xxMetric)
接受一个布尔参数,该参数指定是否为此金丝雀发出不带维度的 4xx
指标。
with_aggregated_5xx_metric(aggregated_5xx_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出不带维度的 5xx
指标。
with_aggregated_failed_canary_metric(aggregated_failed_canary_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出不带维度的 Failed
指标。
with_aggregated_failed_requests_metric(aggregated_failed_requests_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出不带维度的 Failed
requests
指标。
with_failed_canary_metric(failed_canary_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出带 CanaryName
维度的 Failed
指标。
with_failed_requests_metric(failed_requests_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出带 CanaryName
维度的 Failed
requests
指标。
with_step_duration_metric(step_duration_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出带 CanaryName
维度的 Duration
指标。
with_step_success_metric(step_success_metric)
接受一个布尔参数,该参数指定是否为此金丝雀发出带 CanaryName
维度的 StepSuccess
指标。
用于启用或禁用指标的方法
disable_aggregated_request_metrics()
禁用金丝雀发出以不带 CanaryName
维度形式发出的所有请求指标。
disable_request_metrics()
禁用所有请求指标,包括每个金丝雀的指标和跨所有金丝雀聚合的指标。
disable_step_metrics()
禁用所有步骤指标,包括步骤成功指标和步骤持续时间指标。
enable_aggregated_request_metrics()
启用金丝雀发出以不带 CanaryName
维度形式发出的所有请求指标。
enable_request_metrics()
启用所有请求指标,包括每个金丝雀的指标和跨所有金丝雀聚合的指标。
enable_step_metrics()
启用所有步骤指标,包括步骤成功指标和步骤持续时间指标。
在 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
或
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_config(options)
从 syn-python-selenium-1.1
开始,对于 UI 金丝雀,set_config
可包含以下布尔参数:
continue_on_step_failure
(布尔值)– 是否在步骤失败(指 executeStep 函数)后继续运行金丝雀脚本。如果任何步骤失败,金丝雀运行仍将被标记为失败。默认为false
。
SyntheticsLogger 类
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.warn(message, *args, **kwargs)
synthetics_logger.error(message, *args, **kwargs)
有关调试参数的信息,请参阅标准 Python 文档中的 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.warn('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
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 库类和函数
以下用于 Python 的 CloudWatch Synthetics Selenium 库函数仅适用于 UI 金丝雀。
SyntheticsBrowser 类
当您通过调用 synthetics_webdriver.Chrome()
创建浏览器实例时,返回的浏览器实例类型为 SyntheticsBrowser
。SyntheticsBrowser
类控制 ChromeDriver,并使金丝雀脚本能够驱动浏览器,从而允许 Selenium WebDriver 使用 Synthetics。
除了标准的 Selenium 方法之外,它还提供了以下方法。
set_viewport_size(width, height)
设置浏览器的视区。示例:
browser.set_viewport_size(1920, 1080)
save_screenshot(filename, suffix)
将屏幕截图保存到 /tmp
目录。屏幕截图将上载到 S3 存储桶中的金丝雀构件文件夹。
filename 是屏幕截图的文件名,后缀是用于命名屏幕截图的可选字符串。
示例:
browser.save_screenshot('loaded.png', 'page1')
SyntheticsWebDriver 类
要使用此类,请在脚本中使用以下内容:
from aws_synthetics.selenium import synthetics_webdriver
主题
add_execution_error(errorMessage, ex);
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_user_agent(user_agent_str)
将 user_agent_str
的值附加到浏览器的用户代理标头。您必须在创建浏览器实例之前分配 user_agent_str
。
示例:
synthetics_webdriver.add_user_agent('MyApp-1.0')
execute_step(step_name, function_to_execute)
处理一个函数。它还执行以下操作:
记录步骤开始。
获取名为
<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_http_response(url)
对提供的 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()
启动 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)