# Selenium を使用する Python Canary スクリプトで利用可能なライブラリ関数
このセクションでは、Python Canary スクリプトで使用できる Selenium ライブラリ関数の一覧を示しています。
**Topics**
+ [すべての Canary に適用される Python および Selenium ライブラリクラスおよび関数](#CloudWatch_Synthetics_Library_allcanaries_Python)
+ [UI Canary のみに適用される Python および Selenium ライブラリクラスおよび関数](#CloudWatch_Synthetics_Library_Python_UIcanaries)
## すべての Canary に適用される Python および Selenium ライブラリクラスおよび関数
以下の Python 用の CloudWatch Synthetics Selenium ライブラリ関数は、すべての Canary について有用です。
**Topics**
+ [SyntheticsConfiguration クラス](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)
+ [SyntheticsLogger クラス](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python)
### SyntheticsConfiguration クラス
SyntheticsConfiguration クラスを使用して、Synthetics ライブラリ関数の動作を設定できます。例えば、このクラスを使用して、スクリーンショットをキャプチャしないように ` executeStep()` 関数を設定できます。
CloudWatch Synthetics の設定は、グローバルレベルで設定できます。
関数の定義:
#### set\$1config(options)
```
from aws_synthetics.common import synthetics_configuration
```
` options ` はオブジェクトです。これは Canary の設定可能なオプションのセットです。以下のセクションでは、` 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 (オプション)**
`syn-python-selenium-1.1` 以降を使用する Canary の場合、**setConfig** の **(オプション)** には、Canary によって発行されるメトリクスを決定する次のブール値パラメータを含めることができます。これらの各オプションのデフォルトは `true` です。` aggregated` で始まるオプションは、` CanaryName` ディメンションなしでメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、すべての Canary の集計結果を確認できます。その他のオプションは、`CanaryName` ディメンションを含むメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、個々の Canary の結果を確認できます。
Canary から発行される CloudWatch メトリクスのリストについては、「[Canary によって発行される CloudWatch メトリクス](CloudWatch_Synthetics_Canaries_metrics.md)」を参照してください。
+ `failed_canary_metric` (ブール値) – この Canary の ` Failed` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `failed_requests_metric` (ブール値) – この Canary の `Failed requests` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `2xx_metric` (ブール値) – この Canary の `2xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `4xx_metric` (ブール値) – この Canary の `4xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `5xx_metric` (ブール値) – この Canary の `5xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `step_duration_metric` (ブール値) – この Canary の `Step duration` メトリクス (`CanaryName` `StepName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `step_success_metric` (ブール値) – この Canary の `Step success` メトリクス (`CanaryName` `StepName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `aggregated_failed_canary_metric` (ブール値) – この Canary の `Failed` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。
+ `aggregated_failed_requests_metric` (ブール値) – この Canary の `Failed Requests` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。
+ `aggregated_2xx_metric` (ブール値) – この Canary の ` 2xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。
+ `aggregated_4xx_metric` (ブール値) – この Canary の ` 4xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。
+ `aggregated_5xx_metric` (ブール値) – この Canary の ` 5xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルト: `true`。
**with\$12xx\$1metric(2xx\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対して `2xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。
**with\$14xx\$1metric(4xx\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対して `4xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。
**with\$15xx\$1metric(5xx\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対して `5xx` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。
**withAggregated2xxMetric(aggregated2xxMetric)**
ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `2xx` メトリクスを出力するかどうかを指定します。
**withAggregated4xxMetric(aggregated4xxMetric)**
ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `4xx` メトリクスを出力するかどうかを指定します。
**with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `5xx` メトリクスを出力するかどうかを指定します。
**with\$1aggregated\$1failed\$1Canary\$1metric(aggregated\$1failed\$1Canary\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `Failed` メトリクスを出力するかどうかを指定します。
**with\$1aggregated\$1failed\$1requests\$1metric(aggregated\$1failed\$1requests\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない `Failed requests` メトリクスを出力するかどうかを指定します。
**with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対して `Failed` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。
**with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対して `Failed requests` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。
**with\$1step\$1duration\$1metric(step\$1duration\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対して `Duration` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。
**with\$1step\$1success\$1metric(step\$1success\$1metric)**
ブール引数を受け入れます。この引数は、この Canary に対して `StepSuccess` ディメンションを持つ `CanaryName` メトリクスを出力するかどうかを指定します。
##### メトリクスを有効または無効にする方法
**disable\$1aggregated\$1request\$1metrics()**
Canary が ` CanaryName` ディメンションなしで出力されるすべてのリクエストメトリクスを出力するのを無効にします。
**disable\$1request\$1metrics()**
Canary ごとのメトリクスとすべての Canary で集計されたメトリクスの両方を含む、すべてのリクエストメトリクスを無効にします。
**disable\$1step\$1metrics()**
ステップ成功メトリクスとステップ期間メトリクスの両方を含む、すべてのステップメトリクスを無効にします。
**enable\$1aggregated\$1request\$1metrics()**
Canary が ` CanaryName` ディメンションなしで出力されるすべてのリクエストメトリクスを送信できるようにします。
**enable\$1request\$1metrics()**
Canary ごとのメトリクスとすべての Canary で集計されたメトリクスの両方を含む、すべてのリクエストメトリクスを有効にします。
**enable\$1step\$1metrics()**
ステップ成功メトリクスとステップ期間メトリクスの両方を含む、すべてのステップメトリクスを有効にします。
**UI Canary での使用**
まず、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()
```
コード内の任意の個所でスクリーンショットを有効または無効にすることができます。例えば、1 つのステップでのみスクリーンショットを無効にするには、そのステップを実行する前にスクリーンショットを無効にしてステップの実行後に有効にします。
##### UI Canary の set\$1config(options)
`syn-python-selenium-1.1` から始まり、UI Canary については、` set_config` は次のブールパラメータを含めることができます。
+ `continue_on_step_failure` (ブール値) – ステップが失敗した後も Canary スクリプトの実行を続行するかどうか (これは **executeStep** 関数を参照します)。いずれかのステップが失敗しても、Canary 実行は失敗としてマークされます。デフォルト: `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.warning(message, *args, **kwargs)
```
```
synthetics_logger.error(message, *args, **kwargs)
```
デバッグパラメータの詳細については、[logging.debug](https://docs.python.org/3/library/logging.html#logging.debug) の標準 Python ドキュメントをご参照ください。
これらのロギング関数では、`message` はメッセージフォーマット文字列です。`args` は、文字列フォーマット演算子を使用して `msg` にマージされる引数です。
`kwargs` には、次の 3 つのキーワード引数があります。
+ `exc_info` – false と評価されない場合、ログメッセージに例外情報を追加します。
+ `stack_info` – デフォルト設定は false です。true の場合、実際のロギング呼び出しを含むスタック情報をロギングメッセージに追加します。
+ `extra` – 3 番目のオプションのキーワード引数。ロギングイベント用に作成された `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` のメッセージをログに記録します。例外情報は、ロギングメッセージに追加されます。この関数は、例外ハンドラからのみ呼び出す必要があります。
例外パラメータの詳細については、[logging.exception](https://docs.python.org/3/library/logging.html#logging.exception) の標準 Python ドキュメントをご参照ください
`message` はメッセージフォーマット文字列です。`args` は引数で、文字列フォーマット演算子を使用して `msg` にマージされます。
`kwargs` には、次の 3 つのキーワード引数があります。
+ `exc_info` – false と評価されない場合、ログメッセージに例外情報を追加します。
+ `stack_info` – デフォルト設定は false です。true の場合、実際のロギング呼び出しを含むスタック情報をロギングメッセージに追加します。
+ `extra` – 3 番目のオプションのキーワード引数。ロギングイベント用に作成された `LogRecord` の `__dict__` を設定するために使用されるディクショナリでユーザー定義属性を渡すために使用できます。
例:
```
synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric')
```
## UI Canary のみに適用される Python および Selenium ライブラリクラスおよび関数
以下の Python 用の CloudWatch Synthetics Selenium ライブラリ関数は、UI Canary についてのみ有用です。
**Topics**
+ [SyntheticsBrowser クラス](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser)
+ [SyntheticsWebDriver クラス](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)
### SyntheticsBrowser クラス
**注記**
`SyntheticsBrowser` は Chrome ブラウザでのみサポートされています。
`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 (幅、高さ)](#CloudWatch_Synthetics_Library_set_viewport_size)
+ [save\$1screenshot(ファイル名, サフィックス)](#CloudWatch_Synthetics_Library_save_screenshot)
#### set\$1viewport\$1size (幅、高さ)
ブラウザのビューポートを設定します。例:
```
browser.set_viewport_size(1920, 1080)
```
#### save\$1screenshot(ファイル名, サフィックス)
スクリーンショットを `/tmp` ディレクトリに保存します。スクリーンショットは、そこから S3 バケットの Canary アーティファクトフォルダにアップロードされます。
*filename* はスクリーンショットのファイル名で、*suffix* はスクリーンショットの命名に使用されるオプションの文字列です。
例:
```
browser.save_screenshot('loaded.png', 'page1')
```
### SyntheticsWebDriver クラス
このクラスを使用するには、スクリプトで以下を使用します。
```
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);
`errorMessage` はエラーの詳細を示し、`ex` は発生した例外を示します
`add_execution_error` を使用すると、Canary の実行エラーを設定できます。これにより、スクリプトの実行を中断することなく Canary を失敗させることができます。また、`successPercent` メトリクスにも影響を与えません。
Canary スクリプトの成功または失敗を確認するために重要でない場合にのみ、エラーを実行エラーとして追跡するようにします。
`add_execution_error` の使用例を次に示します。ここでは、エンドポイントの可用性をモニターリングしながら、ページが読み込まれた後にスクリーンショットを取得しています。スクリーンショットの作成に失敗したとしても、エンドポイントの可用性が判断されるわけではないため、スクリーンショットの作成中に発生したすべてのエラーは、キャッチした上で実行エラーとして追加します。可用性に関するメトリックスには、依然としてエンドポイントが起動し実行中であることが示されていますが、Canary のステータスは失敗としてマークされています。次に示すコードブロックのサンプルでは、このようなエラーをキャッチし、実行エラーとして追加します。
```
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)
`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)
1 つの関数を処理します。また、次の操作も行います。
+ ステップが開始されたことをログに記録します。
+ `-starting` という名前でスクリーンショットを作成します。
+ タイマーを開始します。
+ 指定された関数を実行します。
+ 関数が正常に戻ると、合格としてカウントします。関数がスローされると、失敗としてカウントします。
+ タイマーを終了します。
+ ステップが合格したか失敗したかをログに記録します。
+ `-succeeded` や ` -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)
指定された 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)
```