Synthetics Scripted Browser リファレンス

Scripted Browser は、スクリイプトを書く際に便利な多くの関数を持っています。これは、利用可能な関数に関する公式ドキュメントです。

Scripted Browser のスクリプトに関しては、New Relic のコミュニティフォーラムのSynthetics スクリプト [英語] [external link]のセクションに例がありますので、是非、チェックしてみてください。

トップレベル関数: スクリプトの構築

トップレベルの関数は、$browser インスタンスから直接呼出せます。ここで使える関数は、基本的な多くのアクションを幅広くサポートしています。

関数 戻り値

$browser.actions()

このドライバを使用して、新しいアクションシーケンスを作成します。利用可能なアクションについては、ActionSequence: Link multiple actionsをご覧ください。

void

$browser.addHeader(headerKey: string, headerValue: string)

ランタイムに指定した headerKeyheaderValue のヘッダーを追加します。

void

$browser.addHeaders(headers: ?)

ランタイムに、ヘッダーのマップを追加します。

void

$browser.deleteHeader(header: string)

ランタイムから特定のヘッダーを削除します。

void

$browser.deleteHeaders(header: [string])

ランタイムから、引数として渡された全ヘッダーを削除します。

void

$browser.addHostnameToBlacklist(hostname: string)

ホスト名をブラックリストに追加します。

void

$browser.addHostnamesToBlacklist(hostnameArr: [string])

引数として渡された全ホスト名をブラックリストに追加します。

void

$browser.addHostnameToWhitelist(hostnameArr: [string])

Synthetics においてデフォルトで、ブロックされているホスト名をホワイトリストに追加します。

void

$browser.addHostnamesToWhitelist(hostnameArr: [string])

引数で渡された全ホスト名をホワイトリストに追加します。

void

$browser.deleteHostnameFromBlacklist(hostname: string)

ブラウザインスタンスのブラックリストから、ホスト名を削除します。

void

$browser.deleteHostnamesFromBlacklist(hostnameArr: [string])

ブラックリストから、引数で渡された全ホスト名を削除します。

void

$browser.deleteHostnameFromWhitelist(hostnameArr: [string])

ブラウザインスタンスのホワイトリストから、ホスト名を削除します。

void

$browser.deleteHostnamesFromWhitelist(hostnameArr: [string])

ブラウザインスタンスのホワイトリストから、引数で指定された全ホスト名を削除します。

void

$browser.executeAsyncScript(script: ?, var_args: ?)

現在選択されているフレームやウィンドウのコンテキスト内において JavaScript を非同期実行するコマンドをスケジュールに登録します。

promise

$browser.executeScript(script: ?, var_args: ?)

現在選択されているフレームやウィンドウのコンテキスト内において JavaScript を実行するコマンドをスケジュールに登録します。

promise

$browser.findElement(locator: $driver.Locator)

ページ内の要素を検索するコマンドをスケジュールに登録します。要素が見つからない場合は、エラーが返ります。ロケーターについては、ロケーター: ページ要素の検索をご覧ください。

WebElement

$browser.findElements(locator: $driver.Locator)

ページ内の要素を複数検索するコマンドをスケジュールに登録します。ロケーターについては、ロケーター: ページ要素の検索をご覧ください。

promise

$browser.waitForAndFindElement(locator: $driver.Locator)

ページ内の要素を検索するコマンドをスケジュールに登録します。ロケーターについては、ロケーター: ページ要素の検索をご覧ください。

promise

$browser.get(url: string)

New Relic Synthetics ブラウザにページの内容を読み込みます。

promise

$browser.getAllWindowHandles()

利用可能なウィンドウハンドルの現在のリストを取得するコマンドをスケジュールに登録します。

promise

$browser.getCapabilities()

capabilities オブジェクトを持つ promise 。

promise

$browser.getCurrentUrl()

現在のページの URL を取得するコマンドをスケジュールに登録します。

promise

$browser.getHeaders()

現在設定されているヘッダー情報を MAP で返します。

map

$browser.getPageSource()

現在のページのソースを取得するコマンドをスケジュールに登録します。取得したソースは、DOM 表現です。サーバーから送信されるレスポンスと同じようにはフォーマットやエスケープされていません。

promise

$browser.getSession()

クライアントセッション用の promise

promise

$browser.getTitle()

現在のページタイトルを取得するコマンドをスケジュールに登録します。

promise

$browser.getWindowHandle()

現在の Window ハンドルを取得するコマンドをスケジュールに登録します。

promise

$browser.isElementPresent(locatorOrElement: $driver.Locator)

ページ上に要素が存在するかをチェックするコマンドをスケジュールに登録します。DOM 要素指定された場合は、現在ドライバーがフォーカスしている document にその要素があるかをチェックします。そうでない場合は、指定された検索内容に沿って、1つ以上の要素が存在するかチェックします。

boolean

$browser.manage()

このインスタンスのオプション操作のインターフェース。クッキー、ログ、タイムアウト、windows オプションを管理できます。全オプションは、オプション: ブラウザインスタンスを管理で確認できます。

void

$browser.navigate()

このインスタンスのナビゲーション・インターフェース。利用可能な関数は、ナビゲート: ブラウザ履歴を利用して移動をご覧ください。

void

$browser.schedule(command: ?, description: string)

このドライバーの CommandExecutor が実行するコマンドをスケジュールに登録します。

promise

$browser.sleep()

指定されている時間、ドライバーがスリープするコマンドをスケジュールに登録します。

promise

$browser.switchTo()

このインスタンスの対象のロケーターインターフェース。

void

$browser.takeScreenshot()

スクリーンショットを撮るコマンドをスケジュールに登録します。

promise

$browser.wait(fn: $driver.until.Condition, timeout: number, opt_message: string)

スクリーンショットを撮るコマンドをスケジュールに登録します。

ユーザーが定義した条件を満たすまで、一定時間待機するコマンドをスケジュールに登録します。利用可能な条件は、条件: 一時停止と待機をご覧ください。

webElement

$browser.waitForPendingRequests(timeout: number)

最初のリクエストが戻ってくるか、タイムアウトまで処理を待機します。ノンブロッキング・リソースを追跡するのに便利です。

promise

オプション: ブラウザインスタンスの管理

以下の関数では、クッキー、タイムアウト、ウィンドウサイズなどのブラウザの情報を管理します。$browser.manage() 関数を通して以下の関数にアクセスします。.

関数 戻り値

$browser.manage().addCookie(name: string, value: string, opt_path: string, opt_domain: string, opt_isSecure: boolean, opt_expiry: number)

クッキーを追加するコマンドをスケジュールに登録します。

promise

$browser.manage().deleteAllCookies()

現在のページで存在する全クッキーを削除するコマンドをスケジュールに登録します。

promise

$browser.manage().deleteCookie(name: string)

指定した名前のクッキーを削除するコマンドをスケジュールに登録します。指定した名前のクッキーが存在しない場合は、何も起きません。

promise

$browser.manage().getCookie(name: string)

指定した名前のクッキーを取得するコマンドをスケジュールに登録します。クッキーが見つからない場合は、null が返ります。見つかった場合は、WebDriver ワイヤープロトコルで記述された JSON オブジェクトでクッキーを返します。

promise

$browser.manage().getCookies()

現在のページに存在する全クッキーを取得するコマンドをスケジュールに登録します。各クッキーは、WebDriver ワイヤープロトコルで記述された JSON オブジェクトでクッキーを返されます。

promise

$browser.manage().timeouts().implicitlyWait(ms: number)

検索しても、すぐに要素が見つからない場合に、明示的にドライバが待機する時間を指定します。待ち時間を 0 に設定すると、暗黙の待機を無効にします。待機のタイムアウト時間を増やすと、テスト実行時間がその分長くなることに注意してください。XPath のような位置検索の遅い方法では特に注意が必要です。Synthetics におけるこのデフォルト値は 10 秒です。

promise

$browser.manage().timeouts().pageLoadTimeout(ms: number)

読み込みが完了するまでの制限時間を設定します。負の値を渡された場合、ページ読み込みが完了するまで待ちます。デフォルト値は 60 秒です。

promise

$browser.manage().timeouts().setScriptTimeout(ms: number)

非同期スクリプトの完了までのタイムアウト時間をミリ秒で指定します。Synthetics におけるこのデフォルト値は 30 秒です。

promise

$browser.manage().window().getPosition()

ウィンドウの現在の位置情報を取得します。スクリーンの左上からの相対値になります。

promise

$browser.manage().window().getSize()

ウィンドウの現在のサイズを取得します。

promise

$browser.manage().window().maximize()

現在のウィンドウを最大化します。

promise

$browser.manage().window().setPosition(x: number, y: number)

現在のウィンドウの位置を変更します。

promise

$browser.manage().window().setSize(width: number, height: number)

現在のウィンドウをリサイズします。

promise

Locators: ページ要素の検索

Locator インスタンスを作成するためのファクトリー関数の集合です。Locator は、$browser.findElement$browser.isElementPresent のような関数に渡せる DOM 要素を探します。$driver.By を使って呼び出します。

関数 戻り値

$driver.By.className(className: string)

クラス名に一致する要素を探します。返されるロケーターは、CSS セレクタ .clazz で要素を検索したものと同じです。

locator

$driver.By.css(cssName: string)

CSS セレクターを使って、要素を探します。

locator

$driver.By.id(id: string)

ID に一致する要素を探します。

locator

$driver.By.linkText(linkText: string)

指定した文字列に一致する表示されているテキストを持つリンク要素を探します。

locator

$driver.By.js(js: string)

JavaScript の式を評価して要素を探します。

locator

$driver.By.name(name: string)

指定した値と同じ名前属性の要素を探します。

locator

$driver.By.partialLinkText(partialLinkText: string)

指定した文字列が、表示されている getText に含まれているリンク要素を探します。

locator

$driver.By.tagName(tagName: string)

指定したタグ名の要素を探します。返されるロケーターは、getElementsByTagName DOM 関数を同じものとなります。

locator

$driver.By.xpath(xpath: string)

XPath セレクターに一致する要素を探します。

locator

WebElement: ページ要素とのインタラクション

$browser.findElement$browser.waitForAndFindElement のような関数が、 WebElement への参照を返す場合、以下の関数を使って、その要素とインタラクションできます。ボタンをクリックしたり、フォームのインプットフィールドにテキストを入力したり、要素の属性を取得したりできます。

関数 戻り値

click()

この要素をクリックします。

void

sendKeys(var_args: ?)

このインスタンスの DOM 要素に一覧の入力をタイプするコマンドをスケジュールに登録します。

WebElement

getTagName()

この要素のタグ/ノード名を取得するコマンドをスケジュールに登録します。

WebElement

getCssValue(name: string)

このインスタンスの要素で計算されたスタイルを取得するコマンドをスケジュールに登録します。 要素が親から指定した名前のスタイルを継承している場合は、親からその値を取得します。可能な場合、カラー値は、16進数に変換されます(例えば、rgb(0, 255, 0) ではなく、#00ff00 となります)。

promise

getAttribute(name: string)

この要素から指定した属性の値を取得するコマンドをスケジュールに登録します。

promise

getText(name: string)

表示されている (CSS によって、hidden になっていない) この要素の innerText を取得します。先頭や末尾の空白は含みません。サブ要素は含みます。

promise

getSize()

この要素の境界ボックスのサイズの計算結果を取得するコマンドをスケジュールに登録します。単位はピクセル。

promise

getLocation()

ページ空間にあるこの要素の位置を計算した結果を取得するコマンドをスケジュールに登録します。

promise

isEnabled()

このインスタンスの DOM 要素が有効かどうかを取得するコマンドをスケジュールに登録します。有効かどうかは、disabled 属性の値によって決まります。

promise

isSelected()

この要素が選択されているかどうかを問い合わせるコマンドをスケジュールに登録します。

promise

submit()

この要素を含むフォーム (また、要素が FORM 自身の場合は、その要素)をサブミットするコマンドをスケジュールに登録します。要素がフォームに含まれていない場合は、このコマンドを呼び出しても何も起きません。

promise

clear()

この要素の値をクリアするコマンドをスケジュールに登録します。

promise

isDisplayed()

この要素が現在、表示されているかどうか確認するコマンドをスケジュールに登録します。

promise

getOuterHtml()

この要素の outer HTML を取得するコマンドをスケジュールに登録します。

promise

getInnerHtml()

この要素の inner HTML を取得するコマンドをスケジュールに登録します。

promise

ActionSequence: 複数アクションの関連付け

アクションシーケンスは、サイトにおける複雑なユーザーインタラクションを作成できます。 $browser.actions() を利用して、新しいアクションシーケンスを作成します。複数のアクションを関連付けて、シーケンスを作成できます。各シーケンスは、perform() で終了して、その直前のシーケンスが実行されます。アクションが1つのシーケンスの場合も同じです。

詳しくは、WebDriver ActionSequence ドキュメント [英語] [external link]をご覧ください。

関数 戻り値

click(opt_elementOrButton: ?, opt_button: ?)

マウスボタンをクリックします。要素を指定している場合、マウスは、最初、その要素の中心に移動します。WebElement.click() と同じ動作をします。

actionsequence

doubleClick(opt_elementOrButton: ?, opt_button: ?)

マウスボタンをダブルクリックします。要素を指定している場合、マウスは、最初、その要素の中心に移動します。

actionsequence

dragAndDrop(element: ?, location: ?)

「ドラッグアンドドロップ」操作の便利関数です。対象の要素を別の要素の位置に移動させてもいいし、オフセット(ピクセル単位)で移動させてもよいです。location は、2つのプロパティ xy: {x: x_offset, y: y_offset} を持つオブジェクトです。

actionsequence

keyDown(key: ?)

修飾キーを押して実行します。ALTCONTROLSHIFTCOMMANDMETA のいずれかでなければなりません。keyUp()sendKeys() が呼び出されるまで、修飾キーは解放されません。この処理のターゲットは、現在フォーカスしている要素です。

actionsequence

keyUp(key: ?)

修飾キーを放す行為を実行します。現在フォーカスしている要素を対象としています。

actionsequence

mouseDown(opt_elementOrButton: ?, opt_button: ?)

マウスボタンを押します。このシーケンス内か他のシーケンス内でこの呼出を行うかに関係なく、mouseUp が呼び出されるまでマウスボタンは解放されません。(ボタンが既に押されている時に、mouseDown()click() が呼び出されるような) 予期線う順序でイベントが発生した場合の動作は、未定義です。

actionsequence

mouseUp(opt_elementOrButton: ?, opt_button: ?)

マウスボタンを離します。動作は、mouseDown() イベントwo
呼び出さずに、この関数を呼び出した時の動作は未定義です。

actionsequence

mouseMove(location: ?, offset: ?)

マウスを移動します。移動する位置は、マウスの現在位置、要素(この場合、要素の中央地点を使用)、または要素の左上隅からの相対オフセットの地点を指定します。

actionsequence

perform()

このアクションシーケンスを実行します。

promise

sendKeys(args: ?)

複数キーの入力をシミュレートします。シーケンスに出た各修飾キーは、再度そのキーを指定するまで、解放されません。すべてのキーイベントは、現在フォーカスしている要素が対象です。サポートしている非英数字キーの完全なリストは、WebDriver enum key ドキュメント [英語] [external link] をご覧ください。

actionsequence

Promise: アクションを繋いでシーケンスを作成

また、promise 上で直接関数を実行できます。Synthetics はネイティブの Node.js の環境であり、標準の Node.js の promise を使っています。これらの関数は、promise の状態を評価したり、キャンセルしたり、その他のことを行います。具体的には、then() 関数とその兄弟関数である thenFinally()thenCatch() でアクションをつなげていきます。詳しくは、シーケンス・アクションをご覧ください。

関数 戻り値

cancel(string: reason)

プロセスにおける promise 処理を拒否し、この promise の値の計算をキャンセルします。promise がすでに解決されている場合、このメソッドは何も行いません。

void

isPending()

promise の値がまだ計算されているかどうか。

boolean

then(opt_callback: fn(T: ?), opt_errback: fn())

このインスタンスを解決するリスナーを登録します。これは、スクリプト内の同期アクションを関連づけるのに使う基本関数です。

promise

thenFinally(callback: fn())

promise の値が正常に計算されたかに関わらず、promise が解決されたときに呼び出されるリスナーを登録します。

promise

thenCatch(callback: fn())

promise が拒否された際に呼び出されるリスナーを登録します。

promise

$browser.navigate() 関数は、ブラウザ履歴の前後に移動したり、ページをリフレッシュしたり、新規ページに移動するなど多くの関数を持っています。

関数 戻り値

Conditions: 条件がパスするまで一時停止と待機

$browser.wait と一緒に until を使うと、条件が一致するまでスクリプトの実行を一時停止します。詳しくは、WebDriver until ドキュメント[英語] [external link]をご覧ください。

以下は、$driver.until.Condition で利用可能な関数です。

関数 戻り値

ableToSwitchToFrame(frame: ?)

入力ドライバが、指定したフレームに切り替え可能になるまで待機する条件を作成します。対象のフレームは以下の指定が可能です。

  • 現在のフレームの window.frames への数値インデックス
  • webdriver.WebElement。現在のページの FRAME 要素または IFRAME 要素への参照であること。
  • スイッチを試みる前の現在のページの FRAME 要素または IFRAME 要素を特定するロケーター
condition

alertIsPresent()

アラートオープンの待ち条件を作成します。成功した場合、戻り値の promise には、オープンしたアラートのハンドルが含まれています。

condition

elementIsDisabled(element: $driver.WebElement)

指定した要素が無効になるまで待機する条件を作成します。

condition

elementIsEnabled(element: $driver.WebElement)

指定した要素が有効になるまで待機する条件を作成します。

condition

elementIsNotVisible(element: $driver.WebElement)

指定した要素が、DOM にあるが、ユーザーにはまだ見えない間の待機条件を作成する。

condition

elementIsVisible(element: $driver.WebElement)

指定した要素が表示される際の待機条件を作成します。

condition

elementIsSelected(element: $driver.WebElement)

指定した要素が選択される際の待機条件を作成します。

condition

elementLocated(element: $driver.Locator)

指定したロケーターを使って要素が見つかるまでのループする条件を作成します。

condition

elementsLocated(element: $driver.Locator)

指定したロケーターを使って最初の1つ目の要素が見つかるまでのループする条件を作成します。

condition

elementTextContains(element: $driver.WebElement, substr: string)

指定した要素の表示テキストが、指定した部分文字列を含むのを待つ条件を作成します。

condition

elementTextIs(element: $driver.WebElement, text: string)

大文字と小文字を区別。指定した要素の表示テキストが正確に指定したテキストと一致するのを待つ条件を作成します。

condition

elementTextMatches(element: $driver.WebElement, regex: string)

指定した要素の表示テキストが、指定した正規表現と一致するのを待つ条件を作成します。

condition

stalenessOf(element: $driver.WebElement)

指定した要素が無効になるまで待つ条件を作成します。DOM から削除されると、無効な要素と見なされます。もしくは、新しいページがロードされた時です。

condition

titleContains(substr: string)

現在のページのタイトルが指定した部分文字列を含むのを待つ条件を作成します。

condition

titleIs(title: string)

現在のページのタイトルが指定した値に一致するのを待つ条件を作成します。

condition

titleMatches(regex: string)

現在のページのタイトルが、指定した正規表現に一致するのを待つ条件を作成します。

condition

関連情報

関連する情報は以下のとおりです。