テストケース内で利用可能なヘルパーメソッド
- 凡例
- イベントの発行
- テスト用ウィンドウの制御
- ブラウザ関連操作（Firefox限定）
- メール関連操作（Thunderbird限定）
- ファイル操作
- 文字列操作
- スクリプトの読み込み
- 設定の読み書き
- アプリケーションの情報の取得
- その他
凡例
- 返り値
メソッド名(引数, [省略可能な引数]) - 説明
イベントの発行
- void
action.fireMouseEvent(in DOMWindow aWindow, [in Object aOptions]) - 指定されたウィンドウに対してマウス操作のイベントを発行します。以下の各プロパティを持つオブジェクトを引数として渡すことで、発生するイベントの内容を指定できます。
type- イベント名（click, dblclick, mousedown, mouseupのいずれか。省略時はclick）
button- クリックしたボタン（省略時は0）
detail- クリック回数（省略時は1）
screenX- クリックした位置の画面上でのX座標（省略時は0）
screenY- クリックした位置の画面上でのY座標（省略時は0）
x- クリックした位置のフレーム内でのX座標（省略時は0）
y- クリックした位置のフレーム内でのY座標（省略時は0）
altKey- Altキーを押していたかどうか（省略時はfalse）
ctrlKey- Ctrlキーを押していたかどうか（省略時はfalse）
metaKey- Metaキー（MacではCommandキー）を押していたかどうか（省略時はfalse）
shiftKey- Shiftキーを押していたかどうか（省略時はfalse）
- void
action.fireMouseEventOnElement(in DOMElement aElement, [in Object aOptions]) - 指定された要素の中央でマウス操作のイベントを発行します。action.fireMouseEventと同様のオプションを指定できます。
- void
action.fireKeyEventOnElement(in DOMElement aElement, [in Object aOptions]) - 指定された要素に対してキーボード操作のイベントを発行します。以下の各プロパティを持つオブジェクトを引数として渡すことで、発生するイベントの内容を指定できます。
type- イベント名（keydown, keyup, keypressのいずれか。省略時はkeypress）
keyCode- 押されたキーのキーコード（省略時は0）
charCode- 押されたキーの文字の文字コード（省略時は0）
altKey- Altキーを押していたかどうか（省略時はfalse）
ctrlKey- Ctrlキーを押していたかどうか（省略時はfalse）
metaKey- Metaキー（MacではCommandキー）を押していたかどうか（省略時はfalse）
shiftKey- Shiftキーを押していたかどうか（省略時はfalse）
Components.interfaces.nsIDOMKeyEventのDOM_VK_RETURNなどの定数プロパティで指定できます。 - void
action.inputTextToField(in DOMElement aElement, in String aValue[, in Boolean aAppend][, in Boolean aDontFireKeyEvents]) - 指定されたテキストフィールドに文字列を入力します。入力はキー入力操作のエミュレーションによって行われ、各文字入力に対してkeyup、keydown、keypress、inputイベントが発行されます（キーボードから直接入力できない日本語の文字などについては、IMEを通した入力の操作とみなします）。通常はテキストフィールドに元々入力されていた内容を削除してから新しい内容を入力しますが、第3引数にtrueを渡すと元々の内容に追加して入力されます。第4引数にtrueを渡すと、コピー＆ペースト時のように、キーイベントを発行せずに文字を挿入します（Ver.0.2.8以前と互換の動作）。
- DOMElement
action.getElementFromScreenPoint(in DOMWindow aWindow, in Number aScreenX, in Number aScreenY) - 画面上の座標から、その位置にある要素のDOMノードを取得します。その位置に要素がない場合はnullを返します。
- DOMWindow
action.getWindowFromScreenPoint(in DOMWindow aWindow, in Number aScreenX, in Number aScreenY) - 画面上の座標から、その位置にあるフレームのWindowオブジェクトを取得します。その位置にフレームがない場合はnullを返します。
以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
actionFireMouseEvent(),
actionFireMouseEventOnElement(),
actionFireKeyEventOnElement(),
actionInputTextToField(),
actionGetElementFromScreenPoint(),
actionGetWindowFromScreenPoint()
テスト用ウィンドウの制御
- DOMWindow
utils.getTestWindow([in Object aOptions]) - テスト用のFirefoxまたはThunderbirdウィンドウを取得します。テスト用ウィンドウが開かれていない場合はnullを返します。
- DOMWindow
utils.openTestWindow([in Object aOptions]) - テスト用のFirefoxまたはThunderbirdウィンドウを開きます。テスト用ウィンドウがすでに開かれている場合はそのウィンドウを返します。
- void
utils.closeTestWindow([in Object aOptions]) - テスト用のFirefoxまたはThunderbirdウィンドウを閉じます。テスト用ウィンドウが開かれていない場合は何もしません。
- Object
utils.setUpTestWindow([in Function aContinuation], [in Object aOptions]) - テスト用のFirefoxまたはThunderbirdウィンドウを初期化します。実行するとウィンドウが開かれていない場合はウィンドウを開き、
valueプロパティにfalseがセットされたオブジェクトを返します。ロード完了後、返り値として返したオブジェクトのvalueプロパティをtrueにセットし、continuation関数が渡されていた場合はそれを実行します。// 利用例：テスト用ウィンドウの初期化が終わるのを待って次に進む yield utils.setUpTestWindow(); var win = utils.getTestWindow(); - void
utils.tearDownTestWindow([in Object aOptions]) - テスト用のFirefoxまたはThunderbirdウィンドウを閉じます。テスト用ウィンドウが開かれていない場合は何もしません。（utils.closeTestWindowへのエイリアスです）
- Array
utils.getChromeWindows([in Object aOptions]) - 特にテスト用としては開かれていない、すでにあるウィンドウを取得します。返り値はDOMWindowの配列です。
ウィンドウを開く時やウィンドウを取得する時は、オプションで詳細を指定できます。オプションは以下の書式で指定し、いずれのプロパティも省略可能です。uriとtypeの両方が省略された場合や、全くオプションを指定しなかった場合は、ブラウザウィンドウ（Thunderbirdではメインウィンドウ）が指定されたものと見なされます。
var options = {
uri : 'chrome://browser/content/browser.xul', // 省略可
type : 'navigator:browser', // 省略可（省略時は null ）
name : '_blank', // 省略可（省略時は _blank ）
flags : 'chrome,all,dialog=no', // 省略可（省略時は chrome,all ）
arguments : ['http://...', 'http://...'] // 省略可（省略時は空の配列）
};また、以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
getTestWindow(),
openTestWindow(),
closeTestWindow(),
setUpTestWindow(),
tearDownTestWindow(),
getChromeWindows()
ブラウザ関連操作
これらの機能はFirefox上でテストを実行する場合にのみ利用可能です。
- DOMWindow
utils.content - DOMWindow
utils.contentWindow - プロパティとしてアクセスすると、テスト用のFirefoxの内容領域のDOMWindowオブジェクトを返します。テスト用ウィンドウが開かれていない場合はテストランナー内のテスト用フレームの内容を返します。
- DOMDocument
utils.contentDocument - プロパティとしてアクセスすると、テスト用のFirefoxの内容領域のDOMDocumentオブジェクトを返します。テスト用ウィンドウが開かれていない場合はテストランナー内のテスト用フレームの内容を返します。
- DOMElement
utils.getBrowser() - テスト用のFirefoxウィンドウのgBrowserオブジェクト（
<tabbrowser/>要素）を返します。テスト用ウィンドウが開かれていない場合は、テストランナー内のテスト用フレームを含む<browser/>要素を返します。 - DOMElement
utils.gBrowser - プロパティとしてアクセスすると、
utils.getBrowser()と同じ内容を返します。 - DOMNodeList
utils.getTabs() - テスト用のFirefoxウィンドウで開かれているタブのノードリストを返します。ウィンドウが開かれていない場合はnullを返します。
- Object
utils.loadURI(in String aURI) - テスト用のFirefoxウィンドウの現在のタブで、指定したURIを読み込みます。テスト用ウィンドウが開かれていない場合は、テストランナー内のテスト用フレームにURIを読み込みます。実行すると、
valueプロパティにfalseがセットされたオブジェクトを返し、ロード完了後にそのオブジェクトのvalueプロパティをtrueにセットします。// 利用例：読み込み完了を待って次に進む yield utils.loadURI('http://www.clear-code.com/'); var win = utils.getTestWindow(); assert.equals('http://www.clear-code.com/', win.content.location.href); - Object
utils.addTab(in String aURI) - テスト用のFirefoxウィンドウで新しいタブを開き、指定したURIをそのタブに読み込みます。実行すると、テスト用ウィンドウが開かれていない場合はnullを、ウィンドウが開かれている場合は
valueプロパティにfalseがセットされたオブジェクトを返します。ロード完了後、返り値として返したオブジェクトのvalueプロパティをtrueにセットし、tabプロパティに開かれたタブをセットします。// 利用例：読み込み完了を待って次に進む var win = utils.getTestWindow(); var obj = utils.addTab('http://www.clear-code.com/'); yield obj; assert.equals('ClearCode Inc.', obj.tab.getAttribute('label'));
utils.loadURI()およびutils.addTab()に相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。
また、以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
content,
contentWindow,
contentDocument,
getBrowser(),
gBrowser,
getTabs(),
loadURI(),
addTab()
メール関連操作
これらの機能はThunderbird上でテストを実行する場合にのみ利用可能です。
- nsIMsgFolder
mail.getFolderByURI(in String aURI) mailbox://nobody@Local%20Folders/...のような形式のURIでメールフォルダを取得します。- nsIMsgFolder
mail.localFolder - ローカルフォルダアカウントのルートフォルダを返します。
- void
mail.deleteFolder(in nsIMsgFolder aFolder) - nsIMsgFolder形式で渡されたメールフォルダを削除します。ごみ箱への移動ではなく、フォルダ内のメッセージも含めての完全削除となります。
- void
mail.deleteFolderByURI(in String aURI) mailbox://nobody@Local%20Folders/...のような形式のURIで指定されたメールフォルダを削除します。ごみ箱への移動ではなく、フォルダ内のメッセージも含めての完全削除となります。
ファイル操作
- String
utils.readFrom(in Object aFile, [in String aEncoding]) - 指定されたファイルの内容をテキストファイルとして読み込み、内容を返します。第1引数にはパス文字列、File URL、またはnsIFileのオブジェクトを指定します。第2引数としてエンコーディングを指定すると、そのエンコーディングからFirefoxの内部処理用エンコーディング（UCS-2）に変換した結果を返します。エンコーディング指定を省略すると読み込んだままのデータを返します。例えばUTF-8で記述されたファイルを読み込む場合は
utils.readFrom(file, "UTF-8")と指定して下さい。 - nsIFile
utils.writeTo(in String aContent, in Object aFile, [in String aEncoding]) - 渡された文字列を、指定されたファイルに書き出します。第2引数にはパス文字列、File URL、またはnsIFileのオブジェクトを指定します。第3引数としてエンコーディングを指定すると、内部エンコーディング（UCS-2）からそのエンコーディングに変換して出力します。エンコーディング指定を省略すると内部エンコーディングのまま出力します。例えばUTF-8でファイルを出力する場合は
utils.writeTo(content, file, "UTF-8")と指定して下さい。なお、すでに存在するファイルを指定した場合は確認無しに上書きされます。 - nsIFile
utils.cosmeticClone(in Object aOriginalFile, in Object aDestinationFolder, in String aName) - 第一引数で渡されたファイルまたはフォルダを、第二引数で渡されたフォルダの中に、第三引数で渡された名前で複製します。フォルダを複製する場合、中に含まれているファイルやフォルダのうち、不可視のファイル（Windowsの隠しファイル、Linuxの「.」で始まる名前のファイルなど）は複製されません。返り値は複製されたファイルまたはフォルダです。
- nsIFile
utils.makeTempFile([in Object aOriginalFile], [in Boolean aCosmetic]) - プラットフォームのテンポラリフォルダ内にテンポラリファイル生成し、それを返します。第一引数にパス文字列、File URL、またはnsIFileのオブジェクトを渡した場合、生成されるテンポラリファイルはそのファイルの複製になります。第二引数にtrueを渡した場合、
utils.cosmeticClone()と同様に、隠しファイルを無視して複製します。 - nsIFile
utils.normalizeToFile(in Object aFile) - パス文字列、File URL、またはnsIFileのオブジェクトで渡された内容を、nsIFileファイルのオブジェクトとして返します。
- void
utils.cleanUpTempFiles() - そのテストケース内で生成したすべてのテンポラリファイルを消去します。ただし、使用中であるなどの理由でロックされていて削除できないファイルはそのまま残ります。
- nsIFile
utils.getFileFromURL(in nsIFile aFileURL) - nsIFileURL形式で指定されたファイルに対応するnsIFileのオブジェクトを生成します。
- nsIFile
utils.getFileFromURLSpec(in String aFileURLSpec) - File URL文字列で指定されたファイルに対応するnsIFileのオブジェクトを生成します。
- nsIFile
utils.getFileFromKeyword(in String aKeyword) - 指定されたキーワードに対応するnsIFileのオブジェクトを生成します。利用可能なキーワードについてはnsDirectoryServiceDefs.hやnsXULAppAPI.hなどを参照してください。
- String
utils.getFilePathFromURL(in nsIFileURL aFileURL) - nsIFileURL形式で指定されたファイルについて、そのプラットフォームでのパス文字列を得ます。
- String
utils.getFilePathFromURLSpec(in String aFileURLSpec) - File URL文字列で指定されたファイルについて、そのプラットフォームでのパス文字列を得ます。
- String
utils.getFilePathFromKeyword(in String aKeyword) - 指定されたキーワードに対応するファイルについて、そのプラットフォームでのパス文字列を得ます。利用可能なキーワードについてはnsDirectoryServiceDefs.hやnsXULAppAPI.hなどを参照してください。
- nsIURI
utils.getURLFromFile(in nsIFile aFile) - nsIFile形式で指定されたファイルについて、対応するFile URLのnsIFileURL形式のオブジェクトを得ます。
- nsIURI
utils.getURLFromFilePath(in String aFilePath) - プラットフォームのパス文字列で指定されたファイルについて、対応するFile URLのnsIFileURL形式のオブジェクトを得ます。
- String
utils.getURLSpecFromFile(in nsIFile aFileURL) - nsIFile形式で指定されたファイルについて、対応するFile URLのURL文字列を得ます。
- String
utils.getURLSpecFromFilePath(in String aFileURL) - プラットフォームのパス文字列で指定されたファイルについて、対応するFile URLのURL文字列を得ます。
- void
utils.scheduleToRemove(in Object aFile) - 渡されたファイルを削除します。nsIFileの
remove()メソッドによってその場ですぐに削除するのではなく、数ミリ秒後に遅れて削除を実行し、失敗した場合は一定回数・一定時間の間自動的に削除を再試行します。
utils.readFrom()およびutils.writeTo()に相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。
また、以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
readFrom(),
writeTo(),
makeTempFile(),
normalizeToFile(),
cleanUpTempFiles(),
getFileFromURL(),
getFileFromURLSpec(),
getFilePathFromURL(),
getFilePathFromURLSpec(),
getURLFromFile(),
getURLFromFilePath(),
getURLSpecFromFile(),
getURLSpecFromFilePath(),
scheduleToRemove()
文字列操作
- String
utils.UTF8ToUCS2(in String aInput) - String
utils.UTF8ToUnicode(in String aInput) - UTF8バイト列をMozilla内部で一般的に使われているUCS2（Unicode）の文字列に変換します。
- String
utils.UCS2ToUTF8(in String aInput) - String
utils.UnicodeToUTF8(in String aInput) - UCS2（Unicode）の文字列をUTF8バイト列に変換します。
- String
utils.XToUCS2(in String aInput, in String aEncoding) - String
utils.XToUnicode(in String aInput, in String aEncoding) - Shift_JISやEUC-JPでエンコードされた文字列を、Mozilla内部で一般的に使われているUCS2（Unicode）の文字列に変換します。第1引数は変換する文字列、第2引数は変換元のエンコーディング名です。
- String
utils.UCS2ToX(in String aInput, in String aEncoding) - String
utils.UnicodeToX(in String aInput, in String aEncoding) - UCS2（Unicode）の文字列を、Shift_JISやEUC-JPでエンコードされた文字列に変換します。第1引数は変換する文字列、第2引数は変換先のエンコーディング名です。
- String
inspect(in Object aObject) - 渡された内容を可読性の高い文字列に変換します。具体的には以下のルールに則って文字列化します。
Array型- 配列のすべての要素を
inspect()したものを返します。 Object型（オブジェクトリテラル、ハッシュ、カスタムクラスのインスタンス）- 持っているすべてのプロパティの名前と値（
inspect()した結果）を列挙したものを返します。
- String
utils.inspectDOMNode(in DOMNode aNode) - 渡されたDOMノードからソース文字列を得ます。HTML文書やXML文書の処理結果を構造まで含めて簡易的に比較する場合などに利用できます。
また、以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
UTF8ToUCS2(),
UTF8ToUnicode(),
UCS2ToUTF8(),
UnicodeToUTF8(),
XToUCS2(),
XToUnicode(),
UCS2ToX(),
UnicodeToX(),
inspect(),
inspectDOMNode()
スクリプトの読み込み
- void
utils.include(in Object aFile, [in Object aContext], [in String aEncoding]) - パス、File URL、nsIFileのオブジェクトで指定されたファイルの内容をスクリプトとして読み込み、テストケースの実行コンテキストで実行します。第2引数としてオブジェクトを渡した場合、そのオブジェクトが実行コンテキストになります。ファイルのエンコーディングは初期状態ではUTF-8として認識しますが、第3引数としてエンコーディングを指定すると、そのエンコーディングとして認識します。
utils.include()に相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。
また、以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
include()
設定の読み書き
- value
utils.getPref(in String aKey) - FirefoxまたはThunderbirdの設定値を取得します。値の型（真偽値、整数値、文字列値）を問わず動作します。
- void
utils.setPref(in String aKey, in Object aValue) - 渡された値をFirefoxまたはThunderbirdの設定値として保存します。値の型（真偽値、整数値、文字列値）は自動判別されます。テストの中で行った変更はテスト終了後に元に戻されます。
- void
utils.clearPref(in String aKey) - FirefoxまたはThunderbirdの設定値を削除します。テストの中で行った変更はテスト終了後に元に戻されます。
また、以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
getPref(),
setPref(),
clearPref()
アプリケーションの情報の取得
- nsIFile
utils.productExecutable - 現在テストが動作しているアプリケーションの実行ファイルをnsIFile形式で取得します。例えばWindows版Firefoxであれば、C:\Program Files\Mozilla Firefox\firefox.exeなどです。
また、以上のプロパティはグローバル変数としても利用できます。グローバル変数として利用する場合の名前は以下のようになります：
productExecutable
その他
- void
utils.log(in String aMessage) - void
utils.dump(in String aMessage) - FirefoxまたはThunderbirdのエラーコンソール上にメッセージを出力します。複数の引数を渡した場合は改行して出力します（どちらも全く同じ働きをします）。
- void
utils.notify(in nsISupports aSubject, in String aTopic, in String aData) - すでに登録されているオブザーバに対して、nsIObserverServiceの機能を使ってメッセージを送出します。
また、以上のユーティリティメソッドはグローバル関数としても利用できます。グローバル関数として利用する場合の名前は以下のようになります（引数等の利用法は全く同一です）：
log(),
dump(),
notify()
Window.dump()を使用する場合は、明示的にwindow.dump()と書く必要があることに注意してください。単にdump()とだけ書いた場合は、上記のユーティリティメソッドの方が実行されます。