ライブラリ仕様
(マルチデバイス)テスト実行
テスト実行には次のクラスおよび設定を使用します
PtlTestBase
テストの基底クラスです。このクラスを拡張したテストクラスを実装することで、
本ページで述べる機能の利用、およびSelenium Gridでの複数ブラウザ・端末並列テストが可能となります。
AssertionView
assertの機能を持つテストツールのRuleです。テストクラスの@Ruleを指定したpublicプロパティとして指定します。
PtlTestBaseを拡張した場合は、すでに定義済みなので指定する必要はありません。
ResultCollector
結果の収集・出力を行うRuleClassです。テスト実行中に取得した画像の情報、および期待画像との比較結果を出力します。
PtlTestBaseを拡張した場合は、すでに定義済みなので指定する必要はありません。
PtlWebDriver
WebDriverの実装クラスです。各ブラウザごとにこのクラスを拡張したdriverクラスが存在します。
PtlWebDriverのインスタンスはAssertViewのcreateWebDriverメソッドから取得します。
RemoteWebDriverと同じメソッドに加えて以下のメソッドを持ちます。
- executeJavaScript(script, params)
RemoteWebDriverのexecuteScriptをラップしたメソッドです。戻り値を自動でキャストします。
- takeScreenshot(...)
いくつかのオーバーロードがあるメソッドです。リグレッションテスト用のスクリーンショットを撮影します。
詳細はtakeScreenshotを参照下さい。
- getEntirePageScreenshot()
全画面スクリーンショットを撮影し、BufferedImageを返します。
Google Chrome等の可視範囲しか撮影されないブラウザでも全画面スクリーンショットを撮影します。
PtlWebDriverStrategy
PtlWebDriverStrategyはJUnitのテストクラスに設定するアノテーションです。PitaliumがどうWebDriverを扱うかについて設定することができます。（v1.0.1以降）
以下のプロパティを持ちます。
| プロパティ名 | 必須 | デフォルト値 | 説明 |
|---|---|---|---|
| sessionLevel | USE_CONFIG | PitaliumがWebDriverのセッションを生成、または破棄（実際のブラウザを起動する、閉じる）するタイミングを変更します。 USE_CONFIG：初期値です。設定を変更しません。 TEST_CASE：テストケース毎にWebDriverセッションを生成、破棄します。WebDriverセッションはテストケース開始時、終了時に自動で生成、クローズされます。 TEST_CLASS：テストクラスに含まれる全テストケースで同一のWebDriverセッションを利用します。WebDriverセッションはテストクラスの開始時、終了時に自動で生成、クローズされます。 GLOBAL：全てのテストケースで同一のWebDriverセッションを利用します。WebDriverセッションは自動で生成されますが、テスト実行中はクローズされることはありません。 PERSISTED：複数のテスト実行をまたいで同一のWebDriverセッションを使いまわします。1回のテスト実行中の振る舞いはGLOBALと同じですが、テスト終了時もWebDriverセッションをクローズせず、セッション情報をファイルに保存し、次のテストで読み出すことで同一のセッションを使い続けることができます。 |
※上記と同様の設定をテストクラス全体へ適用するEnvironmentConfigのwebDriverSessionLevel設定があります。PtlWebDriverStrategyのsessionLevelを設定しない、またはUSE_CONFIGに設定する場合を除きPtlWebDriverStrategyの設定が優先されます。
※TEST_CLASSやGLOBAL、PERSISTEDを設定した場合複数のテストケースで同一のWebDriverセッションを利用しますが、テストケース毎にクッキーのリセット等は自動で行われません。必要に応じてリセット処理を行ってください。
設定
本テストツールにおける設定は、次の箇所で行えます。
- testAppConfig.json：テスト対象のページの共通設定
- environmentConfig.json：ツールを実行するための共通設定
- persisterConfig.json：入出力に関する共通設定
- JVMのパラメータ：上記ファイルのパスおよびテストの実行モード
- capabilities.json： テストを行うブラウザ・マシンの指定、および各ブラウザでの設定
- currentExpectedIds.json：テストメソッドごとにどのテスト結果IDを期待画像として使用するかの設定
testAppConfig.json
| プロパティ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|
| baseUrl | テスト対象ページのベースURL。この項目を指定した場合、PtlWebDriver#get(url)に渡したURLはこのURLからの相対URLとみなされます。ただし、http、httpsから始まる場合は、絶対URLとみなされます | ||
| windowHeight | 800 | PCでテストを実行する場合の、初期状態のウィンドウの高さを指定します | |
| windowWidth | 1280 | PCでテストを実行する場合の、初期状態のウィンドウの幅を指定します |
environmentConfig.json
| プロパティ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|
| execMode | SET_EXPECTED | SET_EXPECTED、TAKE_SCREENSHOT、RUN_TEST SET_EXPECTED：画像の取得のみを行い、比較は行いません。取得した画像は以降のテストの期待画像として扱われます TAKE_SCREENSHOT：画像の取得のみを行い、比較は行いません。取得した画像を以降のテストで期待画像として扱うこともしません RUN_TEST：画像の取得、および期待画像との比較を行い、テストの合否判定をします | |
| capabilitiesFilePath | クラスパス直下のcapabilities.json | テストで使用するcapabilities.jsonのファイルパス | |
| hubHost | localhost | Selenium Gridのhubのホスト名 | |
| hubPort | 4444 | Selenium Gridのポート番号 | |
| maxThreadCount | 16 | テストスレッドの同時最大実行数 | |
| maxThreadExecuteTime | 600 | 各スレッドの最大実行時間（秒） | |
| webDriverSessionLevel | TEST_CASE | PitaliumがWebDriverのセッションを生成、または破棄（実際のブラウザを起動する、閉じる）するタイミングを変更します。 USE_CONFIG：初期値です。設定を変更しません。 TEST_CASE：テストケース毎にWebDriverセッションを生成、破棄します。WebDriverセッションはテストケース開始時、終了時に自動で生成、クローズされます。 TEST_CLASS：テストクラスに含まれる全テストケースで同一のWebDriverセッションを利用します。WebDriverセッションはテストクラスの開始時、終了時に自動で生成、クローズされます。 GLOBAL：全てのテストケースで同一のWebDriverセッションを利用します。WebDriverセッションは自動で生成されますが、テスト実行中はクローズされることはありません。 PERSISTED：複数のテスト実行をまたいで同一のWebDriverセッションを使いまわします。1回のテスト実行中の振る舞いはGLOBALと同じですが、テスト終了時もWebDriverセッションをクローズせず、セッシ | |
| autoResizeWindow | false | trueを指定した場合、AssertionView#assertView()でスクリーンショットを取得する際、現在のページサイズに合わせて自動的にウィンドウをリサイズします。 |
※TEST_CLASSまたはGLOBALを設定した場合複数のテストケースで同一のWebDriverセッションを利用しますが、テストケース毎にクッキーのリセット等は自動で行われません。必要に応じてリセット処理を行ってください。
persisterConfig.json
| プロパティ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|
| resultDirectory | プロジェクト直下のresultsディレクトリ | スクリーンショット、およびテストを実行した結果を格納するディレクトリ | |
| targetResultFileName | スクリーンショットID毎の結果を出力するJSONファイル名のフォーマット | ||
| screenshotFileName | スクリーンショットのファイル名のフォーマット | ||
| diffFileName | RUN_TESTモードで実行中に期待値の画像とテスト中に取得した画像に差分がある場合、その差分画像を保存するファイル名のフォーマット |
※ファイル名のフォーマットは「{platformName}_{platformVersion}_{browserName}_{version}.json」等となります。拡張子を含み、中括弧で囲われた中の文字列をcapabilities.jsonに記述した値と置換します。
capabilities.json
一般的なcapabilityの設定については、Capabilityを参照してください
本ツールで独自に定義しているプロパティは以下となります。
| パラメータ名 | 必須 | デフォルト値 | 説明 |
|---|---|---|---|
| headerHeight | iPhone、iPad: 128 その他: 0 | ブラウザのヘッダ（アドレスバーなど）の高さ。指定した高さ分、取得したスクリーンショットの上部を削除する | |
| footerHeight | iPhone: 88 その他: 0 | ブラウザのフッタ（ツールバーなど）の高さ。指定した高さ分、取得したスクリーンショットの下部を削除する |
currentExpectedIds.json
テストメソッドごとにどのテスト結果IDを期待画像として使用するかを定義します。
テスト結果IDはテスト結果が格納されている、テスト結果フォルダ直下のフォルダ名です(ver.1.0ではテスト結果IDは実行時刻のタイムスタンプ)。
形式は以下のようになります。
"テストクラス名": {
"テストメソッド名": "テスト結果ID"
}
}
このファイルは、SET_EXPECTEDモードで実行した場合に、結果フォルダ直下に自動生成（上書き）されます。
以下はファイルの例です。
"hifiveSampleTest": {
"testCaptureTop":"2015_04_11_23_55_23"
"testCaptureTop13":"2015_04_11_23_55_23",
"testCaptureTutorialTop":"2015_04_11_23_55_23"
},
"SmapleTest": {
}
}
JVMのパラメータ
| プロパティ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|
| com.htmlhifive.pitalium.execMode | EnvironmentConfig.jsonで指定した値 | テストの実行モード。JVMのパラメータを指定している場合、こちらを優先する |
スクリーンショット取得
ページのスクリーンショットの取得方法には以下があります。
- PtlWebDriver#takeScreenshot
PtlWebDriver#takeScreenshot
テストを実行しているブラウザの全体スクリーンショット、および指定した要素または範囲のスクリーンショットを取得します。
- takeScreenshot(screenshotId)
- takeScreenshot(screenshotId, compareTargets)
- takeScreenshot(screenshotId, compareTargets, hiddenElementSelectors)
- takeScreenshot(arg) ※1.0.1で追加予定
引数の説明
| プロパティ | 型 | 説明 | |
|---|---|---|---|
| screenshotId | String | どのスクリーンショットかを識別するためのID。compareTargetを複数指定した場合、すべてのtargetごとのスクリーンショットは同じIDを持つ | |
| comapreTargets | CompareTarget[] or List<CompareTarget> | スクリーンショットを取得するDOM要素の条件の配列またはリスト。空配列(リスト)またはnullが指定された場合、ページ全体(body)のスクリーンショットを取得する | |
| hiddenElementSelectors | DomSelector[] or List<DomSelector> | スクリーンショット取得時に非表示にする要素の配列またはリスト | |
| arg | ScreenshotArgument | スクリーンショットを取得するために必要な情報。 screenshotId、compareTargets、hiddenElementSelectorsを併せ持つ。 |
メソッドの説明
テストを実行しているブラウザの、メソッドが呼ばれたタイミングでのスクリーンショットを取得し、画像ファイルを生成します。
ページ全体に縦スクロールがある場合、スクロールして表示される内容もすべて含んだスクリーンショットが取得できます。
※ 横スクロールや、ページ(body)以外の要素にスクロールがある場合は未対応です。
スクリーンショットは全体だけはなく、DOM要素を指定してその部分のスクリーンショットも指定できます（複数可）。DOM要素の指定は、セレクタまたはxpathで指定します。設定したセレクタやxpathにマッチする要素が複数ある場合、それらの要素すべてのスクリーンショットを取得します。
※ (body以外の)要素にスクロールがあっても、現在表示されている内容しか取得することはできません。
compareTargetを指定しない場合、ページ全体(bodyを指定した場合と同じ）のスクリーンショットを取得します。
返り値は、各DOM要素ごとにスクリーンショットを取得した結果をまとめたオブジェクトです
DOM要素の指定方法
DOM要素の指定は、CompareTargetクラスのScreenArea型のcompareAreaで指定します。
CompareTarget
| プロパティ | 型 | 説明 |
|---|---|---|
| compareArea | ScreenArea | 比較対象のDOM要素または領域 |
| excludes | ScreenArea[] | 比較時に除外するDOM要素または領域の配列 |
| moveTarget | boolean | スクリーンショットを取得する前に、要素を定位置に移動するか |
| scrollTarget | boolean | 要素がスクロールできる場合、スクロール分を含めてスクリーンショットを撮影するか |
ScreenArea
| プロパティ | 型 | 説明 |
|---|---|---|
| type | SelectorType | DOM要素を選択する際に使用するセレクタタイプ |
| value | String | 選択するDOM要素の条件式 |
typeは次の値を持つSelectorTyle型のEnumです。
| 値 | 説明 |
|---|---|
| ID | ID属性に一致する要素を取得するためのセレクタタイプ |
| CLASS_NAME | クラス属性に含まれる要素を取得するためのセレクタタイプ |
| CSS_SELECTOR | CSSセレクタを表すセレクタタイプ |
| NAME | name属性に一致する要素を取得するためのセレクタタイプ |
| LINK_TEXT | リンク名に（完全）一致する要素を取得するためのセレクタタイプ |
| PARTIAL_LINK | リンク名に部分一致する要素を取得するためのセレクタタイプ |
| TAG_NAME | タグに一致する要素を取得するためのセレクタタイプ |
| XPATH | xpathに一致する要素を取得するためのセレクタタイプ |
valueには各SelectorTypeの条件での検索条件を表す文字列を指定します。
DomSelector
| プロパティ | 型 | 説明 |
|---|---|---|
| type | SelectorType | DOM要素を選択する際に使用するセレクタタイプ |
| value | String | 選択するDOM要素の条件式 |
ScreenshotArgument
ScreenshotArgumentはスクリーンショット取得に必要なパラメーターを持つイミュータブルなオブジェクトです。 （※Pitalium v1.0.1で追加予定）
以下のプロパティを有しています。
| プロパティ | 型 | 説明 |
|---|---|---|
| screenshotId | String | どのスクリーンショットかを識別するためのID。 |
| comapreTargets | List<CompareTarget> | スクリーンショットを取得するDOM要素の条件の配列またはリスト。 |
| hiddenElementSelectors | List<DomSelector> | スクリーンショット取得時に非表示にする要素の配列またはリスト。 |
用例はこちらを参照ください。
ScreenshotArgumentBuilder
ScreenshotArgumentBuilderはScreenshotArgumentを生成するためのビルダークラスです。ScreenshotArgumentクラスbuilderメソッドでビルダーの新規インスタンスを取得します。（※Pitalium v1.0.1で追加予定）
主なメソッドを下に記します。
| メソッド名 | 説明 |
|---|---|
| build() | 新しいScreenshotArgumentオブジェクトを生成します。 |
| addNewTarget() | スクリーンショットを撮影する対象を追加します。 （new CompareTargetと同じくBODYタグを対象としたスクリーンショットを取得します。） |
| addNewTarget(CompareTarget) | 既存のCompareTargetで示された要素をスクリーンショット取得対象として追加します。 |
| addNewTarget(SelectorType, String) | スクリーンショット取得対象を要素を指定して追加します。 |
| addNewTargetById(String) | スクリーンショット取得対象の要素をIDを指定して追加します。 |
| addNewTargetByCssSelector(String) | スクリーンショット取得対象の要素をCSSセレクタを指定して追加します。 |
| addExclude(SelectorType, String) | 直前のaddNewTargetで追加したスクリーンショット取得対象に対して、比較除外対象の要素を追加します。 |
| addExcludeById(String) | 直前のaddNewTargetで追加したスクリーンショット取得対象に対して、比較除外対象の要素をIDを指定して追加します。 |
| addExcludeByCssSelector(String) | 直前のaddNewTargetで追加したスクリーンショット取得対象に対して、比較除外対象の要素をCSSセレクタを指定して追加します。 |
| moveTarget(boolean) | 直前のaddNewTargetで追加したスクリーンショット取得対象に対して、スクリーンショット撮影時に指定領域を定位置に移動するか否かを指定します。 |
| addHiddenElementSelector(SelectorType, String) | スクリーンショット取得時に非表示にする要素を追加します。 |
| addHiddenElementSelectorById(String) | スクリーンショット取得時に非表示にする要素をIDを指定して追加します。 |
| addHiddenElementSelectorByCssSelector(String) | スクリーンショット取得時に非表示にする要素をCSSセレクタで追加します。 |
返り値の説明
返り値はScreenshotResultオブジェクトです。以下のプロパティを持ちます。
ScreenshotResult
| プロパティ | 型 | 説明 | |
|---|---|---|---|
| screenshotId | String | takeScreenshotの引数で指定したscreenshotId | |
| targetResults | List<TargetResult> | compareTargetで指定した要素ごとに生成される結果オブジェクトの配列。1つのcomapreTargetで複数の要素が対象となる場合、各要素ごとに生成される | |
| capabilities | Map<String, ?> | テストを実行しているブラウザのCapabilities一覧 | |
| entireScreenshotImage | ScreenshotImage | ブラウザの全体（body）スクリーンショットの画像オブジェクト |
TargetResult
| プロパティ | 型 | 説明 |
|---|---|---|
| image | ScreenshotImage | 指定した要素のスクリーンショットの画像オブジェクト |
| target | ScreenAreaResult | 取得対象の要素の情報を持つオブジェクト |
| excludes | List<ScreenAreaResult> | 比較時に除外する要素の情報のリスト |
| moveTarget | boolean | 取得時にこの要素を移動したか |
| hiddenElementSelectors | List<DomSelector> | スクリーンショット撮影時に非表示としたDOM要素のリスト |
細かい仕様
- takeScreenshotメソッドに渡したCompareTargetのmoveTargetについて：この値をtrueに設定している場合、スクリーンショット取得対象の要素の左上座標が特定の位置となるようにページ全体を移動します。これにより要素の座標が小数点以下の値を含んでいた時に発生する差異を抑制することが出来ます。
- marginについて：要素にmarginが指定されているとき、スクリーンショットにmarginは含まれません。ただし、bodyにmarginが指定してあるときのみ、marginを含んだ「ページ全体」のスクリーンショットを取得します。
表示内容の検証
- AssertionView#assertView
- AssertionView#assertScreenshot
AssertionView#assertView
テストを実行しているブラウザの、メソッドを呼んだタイミングでのスクリーンショットを取得し、テスト実行モードがRUN_TESTの場合は期待画像と一致するかの検証を行います。一致しなければdiff画像を生成し、テストを失敗として中断します。
- assertView(screenshotId)
- assertView(message, screenshotId)
- assertView(screenshotId, compareTargets)
- assertView(message, screenshotId, compareTargets)
- assertView(screenshotId, compareTargets, hiddenElementSelectors)
- assertView(message, screenshotId, compareTargets, hiddenElementSelectors)
引数の説明
| プロパティ | 型 | 説明 |
|---|---|---|
| message | String | 失敗時に表示するメッセージ |
| screenshotId | String | どのスクリーンショットかを識別するためのID。compareTargetを指定している場合、すべてのtargetごとのスクリーンショットは同じIDを持つ |
| comapreTargets | CompareTarget[] or List<CompareTarget> | スクリーンショットを取得するDOM要素の条件の配列またはリスト。空配列(リスト)またはnullが指定された場合、ページ全体(body)のスクリーンショットを取得する |
| hiddenElementSelectors | DomSelector[] or List<DomSelector> | スクリーンショット取得時に非表示にする要素の配列またはリスト |
CompareTargetのexcludesが指定された場合、その要素は比較対象外（要素の表示内容が異なっていてもテストを失敗としない）となります。
CompareTargetのcompareAreaで指定した要素内にexcludesで指定した要素がない場合でも、テストはそのまま実行されます。
（つまり、その指定は無視されます）
メソッドの説明
テストを実行しているブラウザのメソッドを呼んだタイミングでのスクリーンショットを取得し、期待画像と一致するかの検証を行います。
期待画像は、currentExpectedIds.jsonに記述されている期待結果IDのフォルダ名の配下にある画像ファイルで、指定したスクリーンショットIDを持つファイルを使用します。
compareTargetsを指定しない、もしくはbody要素を指定した場合、縦スクロールがあれば、スクロールして表示される内容もすべて含んだスクリーンショットが取得できます。
compareTargetを指定すると、指定した要素のスクリーンショットを取得し、比較を行います。
テストの実行モードによって動作に以下の違いがあります。
| モード名 | スクリーンショット取得 | currentExpectedIds.jsonの更新 | 画像の比較 |
|---|---|---|---|
| SET_EXPECTED | ○ | ○ | |
| TAKE_SCREENSHOT | ○ | ||
| RUN_TEST | ○ | ○ |
注：compareTargetを変更したり、compareTarget内のexcludesを変更した場合は、再度SET_EXPECTEDモードを実行してください。変更後すぐにRUN_TESTモードを実行しても、エラーまたは期待した結果が得られなくなります。
AssertionView#assertScreenshot
すでに取得したスクリーンショットについて、期待画像と一致するかの検証を行います。一致しなければdiff画像を生成し、テストを失敗として中断します。
- assertScreenshot(screenshotResult)
- assertScreenshot(message, screenshotResult)
引数の説明
| プロパティ | 型 | 説明 |
|---|---|---|
| message | String | 失敗時に表示するメッセージ |
| screenshotResult | ScreenshotResult | takeScreenshotを実行して取得した結果オブジェクト |