Browser chromeテスト

Browser chromeテストスイートは、JavaScriptを用いてアプリケーションのChromeウィンドウをテストできるように設計された、自動テストフレームワークです。現在の所、JavaScriptのコードをFirefoxのメインのブラウザウィンドウと同じスコープで実行し、結果をMochitestテストフレームワークと同じ関数を使って報告することができます。Browser chromeテストスイートはMochitestが無効化されたビルド（--disable-tests オプションを付けたビルド）では動作しません。

Browser chromeテストを実行する

Mochitestを実行するには、あなたが行った変更を含めて、まずMozillaをビルドする必要があります。その後、以下を実行します。

./mach mochitest-browser

このコマンドは、あなたがビルドしたMozillaを起動した上で、「browser chrome tests」というウィンドウを開き、テストを実行します。実行結果はそのウィンドウ内と標準出力に報告されます。

特定のグループのテストのみを実行することもできます。その場合は、Mochitest と同様に、Mozillaソースツリー内のディレクトリまたはテストファイルのパスを引数として指定します。パスがディレクトリを指している場合は、そのディレクトリとサブディレクトリに含まれるすべてのテストが実行されるでしょう。

例えば、browser/base/content/test のテストを実行するコマンドは以下のようになります：

./mach mochitest-browser browser/base/content/test/

machを使わないのであれば、以下のようにします。

TEST_PATH=<path_to_the_tests> make -C <objdir> mochitest-browser-chrome

デバッガ内でテストを実行するには以下のようにして下さい：

./mach mochitest-browser --debugger gdb browser/base/content/test/

その他のオプションについては、./mach help mochitest-browser で見ることができます。

Browser chromeテストを書く

Browser chromeテストはブラウザウィンドウのグローバルな変数スコープで実行されるJavaScriptのコード片です。単純なテストの例はこのようになります：

 function test() {
   ok(gBrowser, "gBrowser exists");
   is(gBrowser, getBrowser(), "gBrowser and tBrowser() are the same");
 }

関数test()は、テストが実行される時にテストハーネスによって呼び出されます。テストのファイルには他の関数を含める事ができますが、それらはtest()によって呼び出される物以外は無視されます。

gBrowserは、browser.js内で定義されている、tabbrowser要素（browser.xul内でid="content"と指定されているtabbrowser）への参照です。

比較関数はMochitestsでサポートされているものと全く同じ物を使えます。詳細を知りたい場合は、Mochitestのドキュメントの比較関数がどのように動作するかを参照してください。 グローバルのスコープに定義された「EventUtils」オブジェクトから、EventUtilsヘルパ関数 を利用する事もできます。

テストファイルの名前は「browser_」で始まり、拡張子は「.js」でなければなりません。このパターンに一致しないファイルはテストハーネスに よって無視されます。単にバグ番号だけを使うよりも、より問題の内容を読み取りやすいファイル名にすることが、強く推奨されます。

あなたは、各テストで共通のユーティリティやヘルパーを head.js というファイル（このファイルは browser-chrome テストと同じフォルダに置かれなければなりません）にまとめる事ができます。このファイルの内容は、同じフォルダに存在する各テストに対して、テストのス コープに注入されることになります。head.js のメインのスコープでのあらゆる関数呼び出しは、メインの test() が実行されるよりも前に行われる事に注意してください。

非同期のテスト

テストスイートでは、Mochitestで用意されている関数と同じ名前の関数を使う事で、非同期のテストも実行することができます。test()の実行が終わるまで待ってから実行結果の報告を受け取りたい場合、test()の中でwaitForExplicitFinish()を呼んでください。テストが完了した後にはfinish()を呼びます。テストが完了するまであまりに長い時間がかかった場合、テストハーネスはそのテストをFAILED（失敗）と見なす事に留意してください（現在の所、タイムアウトまでの時間は30秒です）。

 function test() {
   waitForExplicitFinish();
   setTimeout(completeTest, 1000);
 }
 
 function completeTest() {
   ok(true, "Timeout ran");
   finish();
 }

もしあなたのテストがランダムにタイムアウトした時、それが処理に時間がかかりすぎるせいで起こっていると考えるならば、タイムアウトまでの時間を延ばす事ができます。これは完全な解決ではなく、あなたはなぜそのテストに長い時間がかかっているのか（テストの設計が良くないせいだったり、パフォーマンス上の問題があるせいだったりはしないか）を調査することが望ましいという事に気をつけて下さい。 本当にタイムアウトの時間を延ばす前に、もしテストをもっと短く書く事ができるようであれば、もっと小さいテストに分割したり、あるいは、なぜ長い時間がかかっているのか原因を調べたりといった対策を取るべきです！

 function test() {
   // requestLongerTimeout は既定のタイムアウト秒数の30秒を何倍するかを整数で受け取ります。
   // 2であれば「合計で60秒（2×30秒）待つ」という事になります。
   requestLongerTimeout(2);
   waitForExplicitFinish();
   
   setTimeout(completeTest, 40000);
 }
 
 function completeTest() {
   ok(true, "Timeout did not ran");
   finish();
 }

テスト内での例外

test()内で投げられたあらゆる例外は、捕捉され、テストにおいて失敗として報告されます。test()の外で投げられた例外（タイムアウトした場合、イベントハンドラ内での例外など）は捕捉されませんが、タイムアウトしたテストについては、それらがfinish()の実行を妨げた場合は実行結果において報告されます。

テスト実行後のクリーンアップ

テストを実行し終えた後に何らかの特別なクリーンアップ処理を行う必要がある場合は、テストが完了した後に必ず呼ばれる、クリーンアップ用の関数を登録する事ができます。あなたは registerCleanupFunction() をテストの中の任意の時点で（そのフォルダの中のすべてのテストに対してクリーンアップ用の関数を登録する必要があるのなら、head.js の中でも）呼ぶ事ができます。クリーンアップ用の関数は必要なだけ任意の個数登録できることに注意してください。クリーンアップ用関数はまた、テストがタイムアウトした時にも必ず呼ばれますので、次に実行されるテストを汚染してそれらが失敗してしまうといった事が起こらないように強制する事ができます。

registerCleanupFunction(function() {
  // テスト環境のクリーンアップ処理をここに書く
});

function test() {
  // テストに関する処理をここに書く
}

テストを書く時は、失敗に備えて下さい。registerCleanupFunction()は何があっても必ず実行されるので、registerCleanupFunction()を書くことは、テストの成功後に自分でクリーンアップ処理を行うよりもより望ましいです。例えば、テストの中で設定値を変更していても、それを必ずリセットするようにしておけば、あなたのテストは他のテストに何も影響を及ぼしません。

新しいBrowser chromeテストをツリーに追加する

新しいBrowser chromeテストをツリーに追加するには、テストと同じフォルダにあるbrowser.iniの中にそのファイルを追加して下さい。また、テストファイルの名前は browser chrome テストである事が分かるように "browser_" で始まるようにしなければならない事も憶えておいて下さい。もしディレクトリ内に最初のテストを追加する場合には、support-files内にhead.jsも含まれている事を確認しておいて下さい。

Support-files

browser.ini内のsupport-fileセクションに追加されたサポートファイルは、https://example.com/browser/[path_to_file] あるいはchrome://mochitests/content/browser/[path_to_file]で参照できるようになります。