プラグインのUIテストを書く方法 – Piwikのプラットフォームの紹介
私たちがPiwikのプラットフォームの機能を紹介するブログシリーズの新しい投稿です。(以前の投稿はプラグインのためのユニットテストを書く方法でした)今回は、PiwikでUIテストの書く方法を学びます。このチュートリアルではJavaScript及びPiwikプラットフォームの基本的な知識が必要となります。
UIテストとは？
UIテストの下にある「CSSテスト」または「スクリーンショットテスト」等の言葉をいくつか知っているかもしれません。私たちは、UIテストの話をするときに、URLのスクリーンショットをキャプチャし、その結果を予測されるイメージとを比較する自動的なテストのことを指しています。 イメージが全く異なる場合、テストは失敗します。詳細については、UIテストについての私たちのブログの記事をお読みください。
UIテストは何の役に立つのですか？
PHPのコントローラ、Twigテンプレート、CSSをテストするためにUIテストを使用して間接的にJavaScriptをテストします。通常はコントローラのユニットまたは統合テストの書き込みをしないでください。例えば、インストール、ログイン、更新プロセスが期待通りに動作することを確認するために、UIテストを使用しています。私たちは、ほとんどのページ、レポート、設定等のためのテストをも持っています。UIテストを書くと製品の品質が向上し、保守が容易となり多くの時間を節約できます。すべてのUIテストは、各コミット後にトラビス上で実行し予想されるスクリーンショットと比較されています。
入門
この投稿では、すでにPiwikの2.11.0インストール以降にgitを経由して、開発環境をセットアップし、プラグインを作成されていることを前提としています。まだ行われていない場合は、プラグインを開発するために役立つガイド、Piwik開発者のゾーンからセットアップチュートリアルをご覧ください。
次にUIテストを実行するために必要なパッケージをインストールする必要があります。
UIテストを作成してみましょう
新しい UI テストを作成するには、Piwikのコンソールを使用して開始します：
./console generate:test --testtype ui
コマンドは、作成したテストに属している必要があるため、プラグインの名前を入力するように要求されます。プラグイン名「ウィジェット化」を使用します。次にテストの名前を要求します。通常ここでは、ページまたはテストしたいレポートの名前を入力します。この例では、「WidgetizePage」名を使用します。今すぐ簡単に開始できるよう例が含まれたplugins/Widgetize/tests/UI/WidgetizePage_spec.jsファイルがあります：
describe("WidgetizePage", function () {
var generalParams = 'idSite=1&period=day&date=2010-01-03';
it('should load a simple page by its module and action', function (done) {
var screenshotName = 'simplePage';
// will save image in "processed-ui-screenshots/WidgetizePageTest_simplePage.png"
expect.screenshot(screenshotName).to.be.capture(function (page) {
var urlToTest = "?" + generalParams + "&module=Widgetize&action=index";
page.load(urlToTest);
}, done);
});
});
ここで何が起きているのか
この例では、メソッド it(description, func) を呼び出して新しいスペック、 describe(name, callback) を呼び出すことで、その内の一連の新しいスペックを宣言します。ロードするスペックの中で、URLと一度ロードされるページ全体のスクリーンショットをキャプチャします。キャプチャされたスクリーン ショットは、定義された screenshotName の下に保存されます。BDD形式でUIテストを書く事に気づきましたでしょうか。
ページの一部のみを取り込む
常に完全なページをキャプチャしないことをお勧めします。例えば、多くのページには、メニューが含まれているため、そのメニューを変更した場合、すべてのスクリーンショットのテストが失敗してしまいます。この問題を回避するには、代わりになるあなたのメニューのための別のテストを必要とします。ページの一部だけをキャプチャするには、単純にjQueryのセレクタを指定し、capture するのではなく、メソッドの captureSelector を呼び出します:
var contentSelector = '#selector1, .selector2 .selector3';
// Only the content of both selectors will be in visible in the captured screenshot
expect.screenshot('page_partial').to.be.captureSelector(contentSelector, function (page) {
page.load(urlToTest);
}, done);
非表示コンテンツ
スパークラインの既知の問題で、ランダムにテストを失敗してしまいます。また、バージョン番号または日付変更は、実際、エラーを持たずに時々テストに失敗するかもしません。これを避けるために我々 はテストの実行中に HTML 要素に uiTest と呼ばれる CSS クラスを追加し、CSS を使ってキャプチャしたスクリーン ショットでは表示されない要素を防ぐことができます。
.uiTest .version { visibility:hidden }
テストの実行
以前に生成されたテストを実行するには、コマンドを使用してください。tests:run-ui:
./console tests:run-ui WidgetizePage
初めてのテストを実行した後、あなたのプラグインの新しくできたフォルダ plugins/PLUGINNAME/tests/UI/processed-ui-screenshots に気づくでしょう。すべてが動作した場合は、画像がキャプチャされたすべてのスクリーンショットになります。結果に問題がなければ、都度expected-ui-screenshotsフォルダにスクリーンショットが保存され、結果が不満であれば望む結果を得るまでテストする必要があります。これからは、新たにキャプチャさスクリーンショットは、あなたがテストを実行するたびに、予想される画像と比較されます。
テストの修正
いくつかの点で UI テストは失敗します：例えば期待される CSS の変更のため。テストを修正するには、expected-ui-screenshots フォルダーにprocessed-ui-screenshotsフォルダーからキャプチャされたスクリーン ショットをコピーします。
トラヴィスの UI テストを実行
プラグインの .travis.yml ファイルを生成していない場合は、次のコマンドを実行することによってこれを行うことができます：
./console generate:travis-yml --plugin PLUGINNAME
次にリポジトリのトラビスをアクティブにする必要があります。
高度な機能
UIテストの作成は難しいでしょうか？私たちも、ファイルを作成したことはありません！もし作成したい場合には多くを達成することができます。たとえば、プラグインがカスタム データを必要なときに有益なテストを実行する前に挿入されるフィクスチャを指定できます。マウスの移動やテキストの入力など、まるで人がクリックしたかのようにブラウザを制御できます。より多くの機能を検出したい場合は、私達のテストケースを見てください。
API または Piwik デベロッパーゾーンの手順に関してのフィードバックもお気軽にお寄せ下さい。
Thomas Steur