Blog

ライブラリ仕様

Last modified by ishikawa on 2018/07/12, 15:50

(マルチデバイス)テスト実行

テスト実行には次のクラスおよび設定を使用します

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とみなされます
windowHeight800PCでテストを実行する場合の、初期状態のウィンドウの高さを指定します
windowWidth1280PCでテストを実行する場合の、初期状態のウィンドウの幅を指定します

environmentConfig.json

プロパティ必須デフォルト値説明
execModeSET_EXPECTEDSET_EXPECTED、TAKE_SCREENSHOT、RUN_TEST
 SET_EXPECTED:画像の取得のみを行い、比較は行いません。取得した画像は以降のテストの期待画像として扱われます
 TAKE_SCREENSHOT:画像の取得のみを行い、比較は行いません。取得した画像を以降のテストで期待画像として扱うこともしません
 RUN_TEST:画像の取得、および期待画像との比較を行い、テストの合否判定をします
capabilitiesFilePathクラスパス直下のcapabilities.jsonテストで使用するcapabilities.jsonのファイルパス
hubHostlocalhostSelenium Gridのhubのホスト名
hubPort4444Selenium Gridのポート番号
maxThreadCount16テストスレッドの同時最大実行数
maxThreadExecuteTime600各スレッドの最大実行時間(秒)
webDriverSessionLevelTEST_CASEPitaliumがWebDriverのセッションを生成、または破棄(実際のブラウザを起動する、閉じる)するタイミングを変更します。
 USE_CONFIG:初期値です。設定を変更しません。
 TEST_CASE:テストケース毎にWebDriverセッションを生成、破棄します。WebDriverセッションはテストケース開始時、終了時に自動で生成、クローズされます。
 TEST_CLASS:テストクラスに含まれる全テストケースで同一のWebDriverセッションを利用します。WebDriverセッションはテストクラスの開始時、終了時に自動で生成、クローズされます。
 GLOBAL:全てのテストケースで同一のWebDriverセッションを利用します。WebDriverセッションは自動で生成されますが、テスト実行中はクローズされることはありません。
 PERSISTED:複数のテスト実行をまたいで同一のWebDriverセッションを使いまわします。1回のテスト実行中の振る舞いはGLOBALと同じですが、テスト終了時もWebDriverセッションをクローズせず、セッシ
autoResizeWindowfalse trueを指定した場合、AssertionView#assertView()でスクリーンショットを取得する際、現在のページサイズに合わせて自動的にウィンドウをリサイズします。


※TEST_CLASSまたはGLOBALを設定した場合複数のテストケースで同一のWebDriverセッションを利用しますが、テストケース毎にクッキーのリセット等は自動で行われません。必要に応じてリセット処理を行ってください。

persisterConfig.json

プロパティ必須デフォルト値説明
resultDirectoryプロジェクト直下のresultsディレクトリスクリーンショット、およびテストを実行した結果を格納するディレクトリ
targetResultFileNameスクリーンショットID毎の結果を出力するJSONファイル名のフォーマット
screenshotFileNameスクリーンショットのファイル名のフォーマット
diffFileNameRUN_TESTモードで実行中に期待値の画像とテスト中に取得した画像に差分がある場合、その差分画像を保存するファイル名のフォーマット

※ファイル名のフォーマットは「{platformName}_{platformVersion}_{browserName}_{version}.json」等となります。拡張子を含み、中括弧で囲われた中の文字列をcapabilities.jsonに記述した値と置換します。

capabilities.json

一般的なcapabilityの設定については、Capabilityを参照してください
本ツールで独自に定義しているプロパティは以下となります。

パラメータ名必須デフォルト値説明
headerHeightiPhone、iPad: 128
その他: 0
ブラウザのヘッダ(アドレスバーなど)の高さ。指定した高さ分、取得したスクリーンショットの上部を削除する
footerHeightiPhone: 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.execModeEnvironmentConfig.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

プロパティ説明
compareAreaScreenArea比較対象のDOM要素または領域
excludesScreenArea[]比較時に除外するDOM要素または領域の配列
moveTargetbooleanスクリーンショットを取得する前に、要素を定位置に移動するか
scrollTargetboolean要素がスクロールできる場合、スクロール分を含めてスクリーンショットを撮影するか

ScreenArea

プロパティ説明
typeSelectorTypeDOM要素を選択する際に使用するセレクタタイプ
valueString選択するDOM要素の条件式

typeは次の値を持つSelectorTyle型のEnumです。

説明
IDID属性に一致する要素を取得するためのセレクタタイプ
CLASS_NAMEクラス属性に含まれる要素を取得するためのセレクタタイプ
CSS_SELECTORCSSセレクタを表すセレクタタイプ
NAMEname属性に一致する要素を取得するためのセレクタタイプ
LINK_TEXTリンク名に(完全)一致する要素を取得するためのセレクタタイプ
PARTIAL_LINKリンク名に部分一致する要素を取得するためのセレクタタイプ
TAG_NAMEタグに一致する要素を取得するためのセレクタタイプ
XPATHxpathに一致する要素を取得するためのセレクタタイプ

valueには各SelectorTypeの条件での検索条件を表す文字列を指定します。

DomSelector

プロパティ説明
typeSelectorTypeDOM要素を選択する際に使用するセレクタタイプ
valueString選択する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

プロパティ説明
screenshotIdStringtakeScreenshotの引数で指定したscreenshotId
targetResultsList<TargetResult>compareTargetで指定した要素ごとに生成される結果オブジェクトの配列。1つのcomapreTargetで複数の要素が対象となる場合、各要素ごとに生成される
capabilitiesMap<String, ?>テストを実行しているブラウザのCapabilities一覧
entireScreenshotImageScreenshotImageブラウザの全体(body)スクリーンショットの画像オブジェクト

TargetResult

プロパティ説明
imageScreenshotImage指定した要素のスクリーンショットの画像オブジェクト
targetScreenAreaResult取得対象の要素の情報を持つオブジェクト
excludesList<ScreenAreaResult>比較時に除外する要素の情報のリスト
moveTargetboolean取得時にこの要素を移動したか
hiddenElementSelectorsList<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)

引数の説明

プロパティ説明
messageString失敗時に表示するメッセージ
screenshotIdStringどのスクリーンショットかを識別するためのID。compareTargetを指定している場合、すべてのtargetごとのスクリーンショットは同じIDを持つ
comapreTargetsCompareTarget[] or List<CompareTarget>スクリーンショットを取得するDOM要素の条件の配列またはリスト。空配列(リスト)またはnullが指定された場合、ページ全体(body)のスクリーンショットを取得する
hiddenElementSelectorsDomSelector[] 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)

引数の説明

プロパティ説明
messageString失敗時に表示するメッセージ
screenshotResultScreenshotResulttakeScreenshotを実行して取得した結果オブジェクト

Copyright (C) 2012-2017 NS Solutions Corporation, All Rights Reserved.