すべての Canary に適用される Python および Selenium ライブラリクラスおよび関数 UI Canary のみに適用される Python および Selenium ライブラリクラスおよび関数

Selenium を使用する Python Canary スクリプトで利用可能なライブラリ関数

このセクションでは、Python Canary スクリプトで使用できる Selenium ライブラリ関数の一覧を示しています。

トピック

すべての Canary に適用される Python および Selenium ライブラリクラスおよび関数
UI Canary のみに適用される Python および Selenium ライブラリクラスおよび関数

すべての Canary に適用される Python および Selenium ライブラリクラスおよび関数

以下の Python 用の CloudWatch Synthetics Selenium ライブラリ関数は、すべての Canary について有用です。

SyntheticsConfiguration クラス

SyntheticsConfiguration クラスを使用して、Synthetics ライブラリ関数の動作を設定できます。例えば、このクラスを使用して、スクリーンショットをキャプチャしないように executeStep() 関数を設定できます。

CloudWatch Synthetics の設定は、グローバルレベルで設定できます。

関数の定義:

set_config(options)


from aws_synthetics.common import synthetics_configuration

options はオブジェクトです。これは Canary の設定可能なオプションのセットです。以下のセクションでは、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 (オプション)

syn-python-selenium-1.1 以降を使用する Canary の場合、setConfig の (options) には、Canary によって発行されるメトリクスを決定する次のブール値パラメータを含めることができます。これらの各オプションのデフォルトは true です。aggregated で始まるオプションは、CanaryName ディメンションなしでメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、すべての Canary の集計結果を確認できます。その他のオプションは、CanaryName ディメンションを含むメトリクスを出力するかどうかを決定します。これらのメトリクスを使用して、個々の Canary の結果を確認できます。

Canary から発行される CloudWatch メトリクスのリストについては、「Canary によって発行される CloudWatch メトリクス」を参照してください。

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_2xx_metric(2xx_metric)

ブール引数を受け入れます。この引数は、この Canary に対して 2xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with_4xx_metric(4xx_metric)

ブール引数を受け入れます。この引数は、この Canary に対して 4xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with_5xx_metric(5xx_metric)

ブール引数を受け入れます。この引数は、この Canary に対して 5xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withAggregated2xxMetric(aggregated2xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 2xx メトリクスを出力するかどうかを指定します。

withAggregated4xxMetric(aggregated4xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 4xx メトリクスを出力するかどうかを指定します。

with_aggregated_5xx_metric(aggregated_5xx_metric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 5xx メトリクスを出力するかどうかを指定します。

with_aggregated_failed_canary_metric(aggregated_failed_canary_metric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない Failed メトリクスを出力するかどうかを指定します。

with_aggregated_failed_requests_metric(aggregated_failed_requests_metric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない Failed requests メトリクスを出力するかどうかを指定します。

with_failed_canary_metric(failed_canary_metric)

ブール引数を受け入れます。この引数は、この Canary に対して Failed ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with_failed_requests_metric(failed_requests_metric)

ブール引数を受け入れます。この引数は、この Canary に対して Failed requests ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with_step_duration_metric(step_duration_metric)

ブール引数を受け入れます。この引数は、この Canary に対して Duration ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with_step_success_metric(step_success_metric)

ブール引数を受け入れます。この引数は、この Canary に対して StepSuccess ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

メトリクスを有効または無効にする方法

disable_aggregated_request_metrics()

Canary が CanaryName ディメンションなしで出力されるすべてのリクエストメトリクスを出力するのを無効にします。

disable_request_metrics()

Canary ごとのメトリクスとすべての Canary で集計されたメトリクスの両方を含む、すべてのリクエストメトリクスを無効にします。

disable_step_metrics()

ステップ成功メトリクスとステップ期間メトリクスの両方を含む、すべてのステップメトリクスを無効にします。

enable_aggregated_request_metrics()

Canary が CanaryName ディメンションなしで出力されるすべてのリクエストメトリクスを送信できるようにします。

enable_request_metrics()

Canary ごとのメトリクスとすべての Canary で集計されたメトリクスの両方を含む、すべてのリクエストメトリクスを有効にします。

enable_step_metrics()

ステップ成功メトリクスとステップ期間メトリクスの両方を含む、すべてのステップメトリクスを有効にします。

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_config(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.warn(message, *args, **kwargs)


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

デバッグパラメータの詳細については、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.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 のメッセージをログに記録します。例外情報は、ロギングメッセージに追加されます。この関数は、例外ハンドラからのみ呼び出す必要があります。

例外パラメータの詳細については、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 についてのみ有用です。

トピック

SyntheticsBrowser クラス
SyntheticsWebDriver クラス

SyntheticsBrowser クラス

synthetics_webdriver.Chrome() を呼び出してブラウザインスタンスを作成すると、返されるブラウザインスタンスのタイプは SyntheticsBrowser となります。SyntheticsBrowser クラスは ChromeDriver を制御し、Canary スクリプトがブラウザを駆動できるように設定し、Selenium WebDriver が Synthetics で動作できるようにします。

標準的な Selenium メソッドに加えて、以下のメソッドも提供します。

set_viewport_size (幅、高さ)

ブラウザのビューポートを設定します。例:


browser.set_viewport_size(1920, 1080)

save_screenshot(ファイル名, サフィックス)

スクリーンショットを /tmp ディレクトリに保存します。スクリーンショットは、そこから S3 バケットの Canary アーティファクトフォルダにアップロードされます。

filename はスクリーンショットのファイル名で、suffix はスクリーンショットの命名に使用されるオプションの文字列です。

例:


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

SyntheticsWebDriver クラス

このクラスを使用するには、スクリプトで以下を使用します。


from aws_synthetics.selenium import synthetics_webdriver

add_execution_error(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_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)

1 つの関数を処理します。また、次の操作も行います。

ステップが開始されたことをログに記録します。
<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)

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)

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Node.js Canary スクリプト用のライブラリ関数

cron を使用して Canary 実行をスケジュールする