株式会社クリアコード > フリーソフトウェア開発 > UxU - UnitTest.XUL > テストケース内で利用可能なヘルパーメソッド

テストケース内で利用可能なヘルパーメソッド UxU - UnitTest.XUL

凡例

返り値 メソッド名(引数, [省略可能な引数])

説明

イベントの発行

マウスのイベント

マウスのイベントを発行するメソッドは、以下の各プロパティを持つオブジェクトを追加の引数として渡すことによって、修飾キーを押しながらの操作にすることができます。

Boolean altKey
Altキーを押していたかどうか（省略時はfalse）
Boolean ctrlKey
Ctrlキーを押していたかどうか（省略時はfalse）
Boolean metaKey
Metaキー（MacではCommandキー）を押していたかどうか（省略時はfalse）
Boolean shiftKey
Shiftキーを押していたかどうか（省略時はfalse）

なお、Firefox 2およびThudnerbird 2では、クリックのエミュレートによって発行されたイベントではXUL要素のcommandイベントが発行されません。これはGeckoのバージョンによる制限です。

要素の上でのマウス操作

void action.clickOn([options]) 別名：action.leftClickOn(), actionClickOn(), actionLeftClickOn()
void action.middleClickOn([options]) 別名：actionMiddleClickOn()
void action.rightClickOn([options]) 別名：actionRightClickOn()

引数で指定した要素の上で左クリック、中クリック、あるいは右クリックします。

action.clickOn($('button'));
action.clickOn($('button'), { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleClickOn({ shiftKey : true }, $('link'));
void action.dblclickOn([options]) 別名：action.dblClickOn(), action.leftDblclickOn(), action.leftDblClickOn(), actionDblclickOn(), actionDblClickOn(), actionLeftDblclickOn(), actionLeftDblClickOn()
void action.middleDblclickOn([options]) 別名：action.middleDblClickOn(), actionMiddleDblclickOn(), actionMiddleDblClickOn()
void action.rightDblclickOn([options]) 別名：action.rightDblClickOn(), actionRightDblclickOn(), actionRightDblClickOn()

引数で指定した要素の上でダブルクリック、中ボタンのダブルクリック、あるいは右ボタンのダブルクリックを行います。

action.dblclickOn($('button'));
action.dblclickOn($('button'), { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleDblclickOn({ shiftKey : true }, $('link'));
void action.mousedownOn([options]) 別名：action.dblClickOn(), action.leftMousedownOn(), action.leftMouseDownOn(), actionMousedownOn(), actionMouseDownOn(), actionLeftMousedownOn(), actionLeftMouseDownOn()
void action.middleMousedownOn([options]) 別名：action.middleMouseDownOn(), actionMiddleMousedownOn(), actionMiddleMouseDownOn()
void action.rightMousedownOn([options]) 別名：action.rightMouseDownOn(), actionRightMousedownOn(), actionRightMouseDownOn()

引数で指定した要素の上で左ボタン、中ボタン、あるいは右ボタンを押下します。クリックではなく、ボタンを押し下げるだけの操作です。

action.mousedownOn($('button'));
action.mousedownOn($('button'), { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleMousedownOn({ shiftKey : true }, $('link'));
void action.mouseupOn([options]) 別名：action.dblClickOn(), action.leftMouseupOn(), action.leftMouseUpOn(), actionMouseupOn(), actionMouseUpOn(), actionLeftMouseupOn(), actionLeftMouseUpOn()
void action.middleMouseupOn([options]) 別名：action.middleMouseUpOn(), actionMiddleMouseupOn(), actionMiddleMouseUpOn()
void action.rightMouseupOn([options]) 別名：action.rightMouseUpOn(), actionRightMouseupOn(), actionRightMouseUpOn()

引数で指定した要素の上で左ボタン、中ボタン、あるいは右ボタンを放します。action.mousedownOn()等でmousedownイベントを発行させた直後に、これらのメソッドで同じボタンを放す操作を行うと、クリックとして扱われます。

action.mouseupOn($('button'));
action.mouseupOn($('button'), { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleMouseupOn({ shiftKey : true }, $('link'));

指定の座標の位置でのマウス操作

座標指定系のメソッドは、引数として数値を2つ取り、1つ目の数値がX座標、2つ目の数値がY座標になります。座標は画面の左上が原点（0, 0）となりますが、DOMWindowを引数に渡すと、そのDOMWindowに対応するフレームの左上が原点となります。

void action.clickAt([options]) 別名：action.leftClickAt(), actionClickAt(), actionLeftClickAt()
void action.middleClickAt([options]) 別名：actionMiddleClickAt()
void action.rightClickAt([options]) 別名：actionRightClickAt()

指定された座標の位置で左クリック、中クリック、あるいは右クリックします。

action.clickAt(300, 250);
action.clickAt(content, 20, 5, { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleClickAt({ shiftKey : true }, 100, 100, content.frames[2]);
void action.dblclickAt([options]) 別名：action.dblClickAt(), action.leftDblclickAt(), action.leftDblClickAt(), actionDblclickAt(), actionDblClickAt(), actionLeftDblclickAt(), actionLeftDblClickAt()
void action.middleDblclickAt([options]) 別名：action.middleDblClickAt(), actionMiddleDblclickAt(), actionMiddleDblClickAt()
void action.rightDblclickAt([options]) 別名：action.rightDblClickAt(), actionRightDblclickAt(), actionRightDblClickAt()

指定された座標の位置でダブルクリック、中ボタンのダブルクリック、あるいは右ボタンのダブルクリックを行います。

action.dblclickAt(300, 250);
action.dblclickAt(content, 20, 5, { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleDblclickAt({ shiftKey : true }, 100, 100, content.frames[2]);
void action.mousedownAt([options]) 別名：action.mouseDownAt(), action.leftMousedownAt(), action.leftMouseDownAt(), actionMousedownAt(), actionMouseDownAt(), actionLeftMousedownAt(), actionLeftMouseDownAt()
void action.middleMousedownAt([options]) 別名：action.middleMouseDownAt(), actionMiddleMousedownAt(), actionMiddleMouseDownAt()
void action.rightMousedownAt([options]) 別名：action.rightMouseDownAt(), actionRightMousedownAt(), actionRightMouseDownAt()

指定された座標の位置で左ボタン、中ボタン、あるいは右ボタンを押下します。クリックではなく、ボタンを押し下げるだけの操作です。

action.mousedownAt(300, 250);
action.mousedownAt(content, 20, 5, { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleMousedownAt({ shiftKey : true }, 100, 100, content.frames[2]);
void action.mouseupAt([options]) 別名：action.mosueUpAt(), action.leftMouseupAt(), action.leftMouseUpAt(), actionMouseupAt(), actionMouseUpAt(), actionLeftMouseupAt(), actionLeftMouseUpAt()
void action.middleMouseupAt([options]) 別名：action.middleMouseUpAt(), actionMiddleMouseupAt(), actionMiddleMouseUpAt()
void action.rightMouseupAt([options]) 別名：action.rightMouseUpAt(), actionRightMouseupAt(), actionRightMouseUpAt()

指定された座標の位置で左ボタン、中ボタン、あるいは右ボタンを放します。action.mousedownAt()等でmousedownイベントを発行させた直後に、これらのメソッドで同じボタンを放す操作を行うと、クリックとして扱われます。

action.mouseupAt(300, 250);
action.mouseupAt(content, 20, 5, { ctrlKey : true, shiftKey : true });
// 引数はどの順番で渡しても構いません。
action.middleMouseupAt({ shiftKey : true }, 100, 100, content.frames[2]);

キー操作のイベント

キーボード操作のイベントを発行するメソッドは、以下の各プロパティを持つオブジェクトを追加の引数として渡すことによって、修飾キーを押しながらの操作にすることができます。

Boolean altKey
Altキーを押していたかどうか（省略時はfalse）
Boolean ctrlKey
Ctrlキーを押していたかどうか（省略時はfalse）
Boolean metaKey
Metaキー（MacではCommandキー）を押していたかどうか（省略時はfalse）
Boolean shiftKey
Shiftキーを押していたかどうか（省略時はfalse）

なお、Firefox 2およびThudnerbird 2では、キー操作のエミュレートによって発行されたイベントではXUL要素のcommandイベントが発行されません。これはGeckoのバージョンによる制限です。

一般的なキー操作

void action.keypressOn([options]) 別名：action.keyPressOn(), actionKeypressOn(), actionKeyPressOn()

指定された要素にフォーカスした状態で、指定されたキーを打鍵します。

キー指定は、アルファベットや数字、記号などを1文字だけ渡した場合はそのキーを押したものとして扱います。ファンクションキーなどの特殊なキーを押す場合は、Components.interfaces.nsIDOMKeyEventでDOM_VK_RETURNなどの定数プロパティとして定義されているキーコードか、定数プロパティで使われているキー名の文字列（大文字小文字は区別されません）で指定します。

// Ctrl-A
action.keypressOn($('input'), 'a', { ctrlKey : true });

// FooBarと入力してBarを消す。
action.keypressOn($('input'), 'f', { shiftKey : true });
action.keypressOn($('input'), 'o');
action.keypressOn($('input'), 'o');
action.keypressOn($('input'), 'b', { shiftKey : true });
action.keypressOn($('input'), 'a');
action.keypressOn($('input'), 'r');
action.keypressOn($('input'), Ci.nsIDOMKeyEvent.DOM_VK_BACK_SPACE);
action.keypressOn($('input'), Ci.nsIDOMKeyEvent.DOM_VK_BACK_SPACE);
action.keypressOn($('input'), Ci.nsIDOMKeyEvent.DOM_VK_BACK_SPACE);

// 引数はどの順番で渡しても構いません。
action.keypressOn('F3', { shiftKey : true }, $('searchbar'));
void action.keydownOn([options]) 別名：action.keyDownOn(), actionKeydownOn(), actionKeyDownOn()

指定された要素にフォーカスした状態で、指定されたキーを押下します。文字入力などの通常の打鍵操作ではなく、キーを押し下げてそのままにする操作です。実際のキー操作とは異なり、キーリピートは発生しません。

キー指定は、アルファベットや数字、記号などを1文字だけ渡した場合はそのキーを押したものとして扱います。ファンクションキーなどの特殊なキーを押す場合は、Components.interfaces.nsIDOMKeyEventでDOM_VK_RETURNなどの定数プロパティとして定義されているキーコードか、定数プロパティで使われているキー名の文字列（大文字小文字は区別されません）で指定します。

// Ctrl-Tab
action.keydownOn($('tabbrowser'), 'Control');
action.keypressOn($('tabbrowser'), 'Tab', { ctrlKey : true });
action.keypressOn($('tabbrowser'), 'Tab', { ctrlKey : true });
action.keyupOn($('tabbrowser'), 'Control');

// 引数はどの順番で渡しても構いません。
action.keydownOn(Ci.nsIDOMKeyEvent.DOM_VK_TAB, $('field'), { shiftKey : true });
void action.keyupOn([options]) 別名：action.keyUpOn(), actionKeyupOn(), actionKeyUpOn()

指定された要素にフォーカスした状態で、指定されたキーを放します。action.keydownOn()でキーを押下した直後に同じキーを放すと、keypressイベントが発行されます。

キー指定は、アルファベットや数字、記号などを1文字だけ渡した場合はそのキーが放されたものとして扱います。ファンクションキーなどの特殊なキーを放す場合は、Components.interfaces.nsIDOMKeyEventでDOM_VK_RETURNなどの定数プロパティとして定義されているキーコードか、定数プロパティで使われているキー名の文字列（大文字小文字は区別されません）で指定します。

// Ctrl-Tab
action.keydownOn($('tabbrowser'), 'Control');
action.keypressOn($('tabbrowser'), 'Tab', { ctrlKey : true });
action.keypressOn($('tabbrowser'), 'Tab', { ctrlKey : true });
action.keyupOn($('tabbrowser'), 'Control');

// 引数はどの順番で渡しても構いません。
action.keyupOn(Ci.nsIDOMKeyEvent.DOM_VK_TAB, $('field'), { shiftKey : true });

文字入力のキー操作

void action.inputTo([options]) 別名：actionInputTo()

指定されたテキストフィールドに文字列を入力します。入力はキー入力操作のエミュレーションによって行われ、各文字入力に対してkeydown, keyup, keypress, inputイベントが発行されます（キーボードから直接入力できない日本語の文字などについては、IMEを通した入力の操作とみなします）。

action.appendTo()とは事なり、以前に入力されていた内容は消去されます。

action.inputTo($('yomigana'), 'Sakamoto Ryoma');
action.inputTo($('kanji'), '坂本龍馬');
// 引数はどの順番で渡しても構いません。
action.inputTo('31', $('age'));
void action.appendTo([options]) 別名：actionAppendTo()

指定されたテキストフィールドに文字列を入力します。入力はキー入力操作のエミュレーションによって行われ、各文字入力に対してkeydown, keyup, keypress, inputイベントが発行されます（キーボードから直接入力できない日本語の文字などについては、IMEを通した入力の操作とみなします）。

action.inputTo()とは事なり、以前に入力されていた内容はそのまま残して、その後に続けて文字を入力します。

action.appendTo($('comment'), 'My name is');
action.appendTo($('comment'), ' Sakamoto, Ryoma.');
// 引数はどの順番で渡しても構いません。
action.appendTo(' Nice to meet you!', $('comment'));
void action.pasteTo([options]) 別名：actionPasteTo()

指定されたテキストフィールドに文字列を貼り付けます。コピー＆ペーストした時と同じ扱いでinputイベントが発行されます。

action.additionallyPasteTo()とは事なり、以前に入力されていた内容は消去されます。

action.pasteTo($('yomigana'), 'Sakamoto Ryoma');
action.pasteTo($('kanji'), '坂本龍馬');
// 引数はどの順番で渡しても構いません。
action.pasteTo('31', $('age'));
void action.additionallyPasteTo([options]) 別名：actionAdditionallyPasteTo()

指定されたテキストフィールドに文字列を貼り付けます。コピー＆ペーストした時と同じ扱いでinputイベントが発行されます。

action.pasteTo()とは事なり、以前に入力されていた内容はそのまま残して、その後に続けて文字を貼り付けます。

action.additionallyPasteTo($('comment'), 'My name is');
action.additionallyPasteTo($('comment'), ' Sakamoto, Ryoma.');
// 引数はどの順番で渡しても構いません。
action.additionallyPasteTo(' Nice to meet you!', $('comment'));

モーダルダイアログの操作予約

Function action.readyToOK([in Object aOptions]) 別名：action.readyToOk(), actionReadyToOK(), actionReadyToOk()

このメソッドが呼ばれた後にwindow.alert()、nsIPromptService::alert、またはnsIPromptService::alertCheckによって表示されたモーダルダイアログ1つを、自動的に閉じるように予約します。

myModule.doCommand = function() {
  window.alert('warning! this is a dangerous operation.');
  // ...some operations...
  return true;
};

action.readyToOK();
var result = myModule.doCommand();
assert.isTrue(result);

オプションを指定することで、ダイアログのタイトルやメッセージの内容によって自動的に閉じる対象のダイアログを限定することができます。また、checkedプロパティに真偽値が設定されている場合は、nsIPromptService::alertCheckで開かれたダイアログのチェックボックスの状態をcheckedプロパティの値に応じて変更してからダイアログを閉じます。オプションに指定できる内容は以下の通りです。

String title
自動的に閉じるダイアログのタイトル（省略時はすべてにマッチ）
String message
自動的に閉じるダイアログのメッセージ（省略時はすべてにマッチ）
Boolean checked
チェックボックスの状態の指定（省略時はチェック状態を変更しない）
myModule.doCommand = function() {
  var checked = {};
  PromptService.alertCheck(null, 'my dialog', 'click OK', 'check', checked);
  // ...some operations...
  return checked.value;
};

action.readyToOK({ title : 'my dialog', checked : true });
var result = myModule.doCommand();
assert.isTrue(result);

action.cancelReadiedActionに渡す為の関数オブジェクトが戻り値として返されます。

Function action.readyToConfirm(in Boolean aOK, [in Object aOptions]) 別名：actionReadyToConfirm()

このメソッドが呼ばれた後にwindow.confirm()、nsIPromptService::confirm、nsIPromptService::confirmCheck、またはnsIPromptService::confirmExによって表示されるモーダルダイアログ1つを、自動的に閉じるように予約します。第1引数にtrueを渡した場合は「OK」ボタンを、falseを渡した場合は「キャンセル」ボタンを押下します。nsIPromptService::confirmExで3つのボタンを表示するダイアログが開かれる場合、第1引数にはボタンの番号を示す0～2の整数値を渡します。

myModule.doCommand = function() {
  var confirmed = window.confirm('OK?');
  // ...some operations...
  return confirmed;
};

action.readyToConfirm(true);
var result = myModule.doCommand();
assert.isTrue(result);

オプションを指定することで、ダイアログのタイトルやメッセージの内容によって自動的に閉じる対象のダイアログを限定することができます。また、checkedプロパティに真偽値が設定されている場合は、nsIPromptService::confirmCheckやnsIPromptService::confirmExで開かれたダイアログのチェックボックスの状態をcheckedプロパティの値に応じて変更してからダイアログを閉じます。オプションに指定できる内容は以下の通りです。

String title
自動的に閉じるダイアログのタイトル（省略時はすべてにマッチ）
String message
自動的に閉じるダイアログのメッセージ（省略時はすべてにマッチ）
Boolean checked
チェックボックスの状態の指定（省略時はチェック状態を変更しない）
myModule.doCommand = function() {
  var checked = {};
  var button = PromptService.confirmEx(null, 'my confirm', 'OK?', 
                 (PromptService.BUTTON_POS_0 * PromptService.BUTTON_TITLE_SAVE) |
                 (PromptService.BUTTON_POS_1 * PromptService.BUTTON_TITLE_DONT_SAVE) |
                 (PromptService.BUTTON_POS_2 * PromptService.BUTTON_TITLE_CANCEL),
                 null, null, null,
                 'ask me again', checked);
  // ...some operations...
  return [button, checked.value];
};

action.readyToConfirm(2, { title : 'my confirm', checked : true });
var result = myModule.doCommand();
assert.equals([2, true], result);

action.cancelReadiedActionに渡す為の関数オブジェクトが戻り値として返されます。

Function action.readyToPrompt(in String aInput, [in Object aOptions]) 別名：actionReadyToPrompt()

このメソッドが呼ばれた後にwindow.prompt()、またはnsIPromptService::promptによって表示されるモーダルダイアログ1つを、自動的に閉じるように予約します。第1引数でプロンプトに入力する文字列を指定できます。

myModule.doCommand = function() {
  var name = window.prompt('What is your name?');
  // ...some operations...
  return name;
};

action.readyToPrompt('John');
var name = myModule.doCommand();
assert.equals('John', name);

オプションを指定することで、ダイアログのタイトルやメッセージの内容によって自動的に閉じる対象のダイアログを限定することができます。また、checkedプロパティに真偽値が設定されている場合は、nsIPromptService::promptで開かれたダイアログのチェックボックスの状態をcheckedプロパティの値に応じて変更してからダイアログを閉じます。オプションに指定できる内容は以下の通りです。

String title
自動的に閉じるダイアログのタイトル（省略時はすべてにマッチ）
String message
自動的に閉じるダイアログのメッセージ（省略時はすべてにマッチ）
Boolean checked
チェックボックスの状態の指定（省略時はチェック状態を変更しない）
myModule.doCommand = function() {
  var input = {};
  var checked = {};
  var OK = PromptService.prompt(null, 'my prompt', 'What is your name?',
             input, 'ask me again', checked);
  // ...some operations...
  return [input.value, checked.value];
};

action.readyToPrompt('Jane', { title : 'my prompt', checked : true });
var result = myModule.doCommand();
assert.equals(['Jane', true], result);

action.cancelReadiedActionに渡す為の関数オブジェクトが戻り値として返されます。

Function action.readyToPromptPassword(in String aPassword, [in Object aOptions]) 別名：actionReadyToPromptPassword()

このメソッドが呼ばれた後にnsIPromptService::promptPasswordによって表示されるモーダルダイアログ1つを、自動的に閉じるように予約します。第1引数でプロンプトに入力するパスワード文字列を指定できます。

myModule.doCommand = function() {
  var password = {};
  var checked = {};
  var OK = PromptService.promptPassword(null, 'warning!', 'What is the password?',
             password, 'never show this dialog', checked);
  // ...some operations...
  return [password.value, checked.value];
};

action.readyToPassword('password', { title : 'warning!', checked : true });
var result = myModule.doCommand();
assert.equals(['password', true], result);

オプションを指定することで、ダイアログのタイトルやメッセージの内容によって自動的に閉じる対象のダイアログを限定することができます。また、checkedプロパティに真偽値が設定されている場合は、ダイアログのチェックボックスの状態をcheckedプロパティの値に応じて変更してからダイアログを閉じます。オプションに指定できる内容は以下の通りです。

String title
自動的に閉じるダイアログのタイトル（省略時はすべてにマッチ）
String message
自動的に閉じるダイアログのメッセージ（省略時はすべてにマッチ）
Boolean checked
チェックボックスの状態の指定（省略時はチェック状態を変更しない）

action.cancelReadiedActionに渡す為の関数オブジェクトが戻り値として返されます。

Function action.readyToPromptUsernameAndPassword(in String aUsername, in String aPassword, [in Object aOptions]) 別名：actionReadyToPromptUsernameAndPassword()

このメソッドが呼ばれた後にnsIPromptService::promptUsernameAndPasswordによって表示されるモーダルダイアログ1つを、自動的に閉じるように予約します。第1引数でプロンプトに入力するユーザ名を、第2引数でパスワード文字列を指定できます。

myModule.doCommand = function() {
  var username = {};
  var password = {};
  var checked = {};
  var OK = PromptService.promptUsernameAndPassword(null, 'login', 'Who are you?',
             username, password, 'never show this dialog', checked);
  // ...some operations...
  return [username.value, password.value, checked.value];
};

action.readyToPromptUsernameAndPassword('user', 'password', { title : 'login', checked : true });
var result = myModule.doCommand();
assert.equals(['user', 'password', true], result);

オプションを指定することで、ダイアログのタイトルやメッセージの内容によって自動的に閉じる対象のダイアログを限定することができます。また、checkedプロパティに真偽値が設定されている場合は、ダイアログのチェックボックスの状態をcheckedプロパティの値に応じて変更してからダイアログを閉じます。オプションに指定できる内容は以下の通りです。

String title
自動的に閉じるダイアログのタイトル（省略時はすべてにマッチ）
String message
自動的に閉じるダイアログのメッセージ（省略時はすべてにマッチ）
Boolean checked
チェックボックスの状態の指定（省略時はチェック状態を変更しない）

action.cancelReadiedActionに渡す為の関数オブジェクトが戻り値として返されます。

Function action.readyToSelect(in Number aIndex, [in Object aOptions]) 別名：actionReadyToSelect()

このメソッドが呼ばれた後にnsIPromptService::selectによって表示されるモーダルダイアログ1つを、自動的に閉じるように予約します。第1引数で選択する項目のインデックスを指定できます。

myModule.doCommand = function() {
  var selection = {};
  var OK = PromptService.select(null, 'select!', 'Choose an item.',
             5, ['a', 'b', 'c', 'd', 'e'], selection);
  // ...some operations...
  return selection.value;
};

action.readyToSelect(2, { title : 'select!', checked : true });
var result = myModule.doCommand();
assert.equals(2, result);
// The index "2" means "third item", so "c" is selected.

オプションを指定することで、ダイアログのタイトルやメッセージの内容によって自動的に閉じる対象のダイアログを限定することができます。オプションに指定できる内容は以下の通りです。

String title
自動的に閉じるダイアログのタイトル（省略時はすべてにマッチ）
String message
自動的に閉じるダイアログのメッセージ（省略時はすべてにマッチ）

action.cancelReadiedActionに渡す為の関数オブジェクトが戻り値として返されます。

void action.cancelReadiedAction(in Function aAction) 別名：actionCancelReadiedAction()

action.readToOK、action.readToConfirm、action.readToPrompt、action.readToPromptPassword、action.readyToPromptUsernameAndPassword、action.readyToSelectによって行われた操作の予約を取り消します。これらの各メソッドの戻り値である関数を渡すと、その操作を1つだけキャンセルします。

var act = action.readyToOK();

action.cancelRediedAction(act);
void action.cancelReadiedActions() 別名：actionCancelReadiedActions()

action.readToOK、action.readToConfirm、action.readToPrompt、action.readToPromptPassword、action.readyToPromptUsernameAndPassword、action.readyToSelectによって行われた操作の予約を取り消します。それまでの時点で行われたすべての操作予約が取り消されます。

action.readyToOK();
action.readyToOK();
action.readyToOK();
...
action.cancelRediedActions();

座標からの操作

DOMWindow action.getFrameFromScreenPoint(in Number aScreenX, in Number aScreenY) 別名：action.getWindowFromScreenPoint(), actionGetFrameFromScreenPoint(), actionGetWindowFromScreenPoint()
DOMWindow action.getFrameFromScreenPoint(in DOMWindow aWindow, in Number aScreenX, in Number aScreenY)

画面上の座標から、その位置にあるフレームのWindowオブジェクトを取得します。その位置にフレームがない場合はnullを返します。

フレームの検索は、その位置にある最も手前のFirefox（Thunderbird）のウィンドウに対して行われます。別のウィンドウの下になっているウィンドウの中のフレームを検索する場合は、引数として親ウィンドウまたは親フレームのWindowオブジェクトを指定して下さい。なお、親ウィンドウを指定した場合でも、X座標とY座標は常に画面左上を原点とした指定として扱います。

var frame = action.getWindowFromScreenPoint(500, 200);
assert.isNotNull(frame);
assert.equals($('sidebar', topWindow).contentWindow, frame);

var frame2 = action.getWindowFromScreenPoint(bottomWindow, 500, 200);
DOMElement action.getElementFromScreenPoint(in Number aScreenX, in Number aScreenY) 別名：actionGetElementFromScreenPoint()
DOMElement action.getElementFromScreenPoint(in DOMWindow aWindow, in Number aScreenX, in Number aScreenY)

画面上の座標から、その位置にある要素のDOMノードを取得します。その位置に要素がない場合はnullを返します。

要素の検索は、その位置にある最も手前のFirefox（Thunderbird）のウィンドウに対して行われます。別のウィンドウの下になっているウィンドウの中の要素を検索する場合は、引数として親ウィンドウまたは親フレームのWindowオブジェクトを指定して下さい。なお、親ウィンドウを指定した場合でも、X座標とY座標は常に画面左上を原点とした指定として扱います。

var element = action.getElementFromScreenPoint(240, 10);
assert.equals($('accept-button', topWindow), element);

var element2 = action.getElementFromScreenPoint(bottomWindow, 240, 10);

古いAPI

以下は、旧バージョンとの互換性のために残されている古いAPIです。

void action.fireMouseEvent(in DOMWindow aWindow, [in Object aOptions]) 別名：actionFireMouseEvent()

指定されたウィンドウに対してマウス操作のイベントを発行します。以下の各プロパティを持つオブジェクトを引数として渡すことで、発生するイベントの内容を指定できます。

String type
イベント名（click, dblclick, mousedown, mouseupのいずれか。省略時はclick）
Number button
クリックしたボタン（省略時は0）
Number detail
クリック回数（省略時は1）
Number screenX
クリックした位置の画面上でのX座標（省略時は0）
Number screenY
クリックした位置の画面上でのY座標（省略時は0）
Number x
クリックした位置のフレーム内でのX座標（省略時は0）
Number y
クリックした位置のフレーム内でのY座標（省略時は0）
Boolean altKey
Altキーを押していたかどうか（省略時はfalse）
Boolean ctrlKey
Ctrlキーを押していたかどうか（省略時はfalse）
Boolean metaKey
Metaキー（MacではCommandキー）を押していたかどうか（省略時はfalse）
Boolean shiftKey
Shiftキーを押していたかどうか（省略時はfalse）

すべてのオプションを省略すると、「(0, 0)の位置で左ボタンでシングルクリック」となります。指定された座標に要素がない場合はイベントを発行しません。

function testDblClickOnTarget() {
  action.fireMouseEvent(content, { type    : 'dblclick',
                                   screenX : 120,
                                   screenY : 250,
                                   ctrlKey : true });
}

Firefox 2およびThudnerbird 2では、この機能によってエミュレートされたクリックイベントではcommandイベントが発行されません。これはGeckoのバージョンによる制限です。

void action.fireMouseEventOnElement(in DOMElement aElement, [in Object aOptions]) 別名：actionFireMouseEventOnElement()

指定された要素の中央でマウス操作のイベントを発行します。action.fireMouseEvent()と同様のオプションを指定できます。

action.fireMouseEventOnElement($('button'),
                               { type    : 'dblclick',
                                 ctrlKey : true });

Firefox 2およびThudnerbird 2では、この機能によってエミュレートされたクリックイベントではcommandイベントが発行されません。これはGeckoのバージョンによる制限です。

void action.fireKeyEventOnElement(in DOMElement aElement, [in Object aOptions]) 別名：actionFireKeyEventOnElement()

指定された要素に対してキーボード操作のイベントを発行します。以下の各プロパティを持つオブジェクトを引数として渡すことで、発生するイベントの内容を指定できます。

String type
イベント名（keydown, keyup, keypressのいずれか。省略時はkeypress）
Number keyCode
押されたキーのキーコード（省略時は0）
Number charCode
押されたキーの文字の文字コード（省略時は0）
Boolean altKey
Altキーを押していたかどうか（省略時はfalse）
Boolean ctrlKey
Ctrlキーを押していたかどうか（省略時はfalse）
Boolean metaKey
Metaキー（MacではCommandキー）を押していたかどうか（省略時はfalse）
Boolean shiftKey
Shiftキーを押していたかどうか（省略時はfalse）

キーコードは Components.interfaces.nsIDOMKeyEvent の DOM_VK_RETURN などの定数プロパティで指定できます。

action.fireKeyEventOnElement($('button'),
                             { keyCode : Ci.nsIDOMKeyEvent.DOM_VK_ENTER,
                               ctrlKey : true });

Firefox 2およびThudnerbird 2では、この機能によってエミュレートされたキーイベントではcommandイベントが発行されません。これはGeckoのバージョンによる制限です。

Boolean action.fireXULCommandEvent(in DOMWindow aWindow, [in Object aOptions]) 別名：actionFireXULCommandEvent()

指定されたウィンドウに対して、マウスでのクリック操作によるcommandイベントを発行します。action.fireMouseEvent()と同様のオプションを指定できます。指定された座標にあるXUL要素が操作を受け付けない状態である場合（label要素などのcommandイベントを発行しない要素である、あるいは、disabled属性が設定されているなどの場合）にはイベントを発行しません。イベントを発行できた場合はtrue、イベントを発行しなかった場合はfalseを返します。

action.fireXULCommandEvent(testWindow,
                           { screenX : buttonInTestWindow.boxObject.screenX+5,
                             screenY : buttonInTestWindow.boxObject.screenY+5 });

Firefox 2およびThudnerbird 2では、この機能は利用できません。これはGeckoのバージョンによる制限です。

Boolean action.fireXULCommandEventOnElement(in DOMElement aElement, [in Object aOptions]) 別名：actionFireXULCommandEventOnElement()

指定された要素に対して、マウスでのクリック操作によるcommandイベントを発行します（要素の中央がクリックされたものと見なします）。action.fireMouseEvent()と同様のオプションを指定できます。指定されたXUL要素が操作を受け付けない状態である場合（label要素などのcommandイベントを発行しない要素である、あるいは、disabled属性が設定されているなどの場合）にはイベントを発行しません。イベントを発行できた場合はtrue、イベントを発行しなかった場合はfalseを返します。

action.fireXULCommandEventOnElement($('toolbarbutton', testWindow));

Firefox 2およびThudnerbird 2では、この機能は利用できません。これはGeckoのバージョンによる制限です。

void action.inputTextToField(in DOMElement aElement, in String aValue, [in Boolean aAppend], [in Boolean aDontFireKeyEvents]) 別名：actionInputTextToField()

指定されたテキストフィールドに文字列を入力します。入力はキー入力操作のエミュレーションによって行われ、各文字入力に対してkeydown, keyup, keypress, inputイベントが発行されます（キーボードから直接入力できない日本語の文字などについては、IMEを通した入力の操作とみなします）。

通常はテキストフィールドに元々入力されていた内容を削除してから新しい内容を入力しますが、第3引数にtrueを渡すと元々の内容に追加して入力されます。

第4引数にtrueを渡すと、コピー＆ペースト時のように、キーイベントを発行せずに文字を挿入します（Ver.0.2.8以前と互換の動作）。

action.inputTextToField($('input'), 'message foobar');
action.inputTextToField($('input'), ' and more...', true);

テストケースの位置

String fileURL 別名：utils.fileURL

実行中のテストケースのファイルの位置を返します。

var data = utils.readCSV(fileURL+'.data.csv');
String baseURL 別名：utils.baseURL

実行中のテストケースのファイルが存在しているフォルダの位置を返します。

utils.include(baseURL+'common.inc.js');
utils.include(baseURL+'../content/myadoon/myModule.js');

テスト用ウィンドウの制御

Object utils.setUpTestWindow([in Object aOptions]) 別名：setUpTestWindow()

テスト用のFirefoxまたはThunderbirdウィンドウを初期化します。実行するとウィンドウが開かれていない場合はウィンドウを開きます。

// テスト用ウィンドウの初期化が終わるのを待って次に進む
function setUp() {
  utils.setUpTestWindow();
  var win = utils.getTestWindow();
  assert.isTrue(win.MyAddonService.initialized);
}

オプションによって、ウィンドウとして開くリソースのURI、ウィンドウの位置や大きさなどを指定できます。

このメソッドは、ウィンドウの初期化処理が完了するまでの間、実行中のテストを一時的に停止します。オプションのasyncプロパティにtrueを指定すると、ウィンドウの初期化が完了するのを待たずに次の行に進みます。このメソッドはロード完了まで待つための処理待ち用オブジェクトを返しますので、返り値をyieldやutils.wait()に渡して処理の完了を待つ事ができます。

function setUp() {
  var completed = utils.setUpTestWindow({ async : true });
  // some operations
  yield completed;
  var win = utils.getTestWindow();
  assert.isTrue(win.MyAddonService.initialized);
}
void utils.tearDownTestWindow([in Object aOptions]) 別名：utils.closeTestWindow(), closeTestWindow(), tearDownTestWindow()

utils.setUpTestWindow()によって開かれたテスト用のウィンドウを閉じます。テスト用ウィンドウが開かれていない場合は何もしません。

function tearDown() {
  utils.tearDownTestWindow();
}

オプションによって、閉じるウィンドウを指定できます。

DOMWindow utils.getTestWindow([in Object aOptions]) 別名：getTestWindow()

utils.setUpTestWindow()によって開かれたテスト用のウィンドウを取得します。テスト用ウィンドウが開かれていない場合はnullを返します。

var win = utils.getTestWindow();
assert.isDefined(win.MyAddonService);

オプションによって、条件を指定してウィンドウを取得することができます。

DOMWindow Array utils.getChromeWindows([in Object aOptions]) 別名：getChromeWindows()

特にテスト用としては開かれていない、すでにあるウィンドウを取得します。返り値はDOMWindowの配列です。

var addonManager = utils.getChromeWindows({
      type : 'Extension:Manager'
    });
addonManager = addonManager[0];

オプションによって、条件を指定してウィンドウを取得することができます。

ウィンドウのオプション

ウィンドウを開く時やウィンドウを取得する時は、オプションで詳細を指定できます。オプションは以下の書式で指定し、いずれのプロパティも省略可能です。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://...'],           // 省略時は空の配列
  width     : 200,
  height    : 400,
  screenX   : 100,
  screenY   : 100
};

DOM操作

DOMNode $(in nsIVariant aNodeOrIdString, [in nsIVariant aOwner]) 別名：utils.$()

prototype.jsなどの$()に相当する機能を提供します。以下のような挙動を示します。

  • DOMNodeを渡した場合、それをそのまま返します。
  • 文字列を渡した場合、IDがその文字列である要素ノードを返します。
    • 第2引数を省略すると、contentDocument.getElementById()と同じ結果になります。
    • 第2引数にDOMDocumentを渡すと、aOwner.getElementById()と同じ結果になります。
    • 第2引数にDOMWindowを渡すと、aOwner.document.getElementById()と同じ結果になります。
    • 第2引数にDOMNodeを渡すと、aOwner.ownerDocument.getElementById()と同じ結果になります。
var button = $('button');
var toolbar = $('navigator-toolbox', utils.getTestWindow());
nsIVariant $X(arguments) 別名：utils.$X()

DOM3 XPathのためのシンタックスシュガーに相当する機能を提供します。以下のような挙動を示します。

nsIVariant $X(in String aExpression)
contentDocument.evaluate(aExpression, contentDocument, null, XPathResult.ANY_TYPE, null)の結果に応じて、値を真偽値、数値、文字列、または単一のDOMノードで返します。
nsIVariant $X(in String aExpression, in DOMNode aContext)
(aContext.ownerDocument || aContext).evaluate(aExpression, aContext, null, XPathResult.ANY_TYPE, null)の結果に応じて、値を真偽値、数値、文字列、または単一のDOMノードで返します。
nsIVariant $X(in String aExpression, in DOMNode aContext, in Number aResultType)
(aContext.ownerDocument || aContext).evaluate(aExpression, aContext, null, aResultType, null)の結果に応じて、値を真偽値、数値、文字列、単一のDOMノード、またはノードの配列で返します。
nsIVariant $X(in String aExpression, in DOMNode aContext, in DOMXPathNSResolver aNSResolver, in Number aResultType)
(aContext.ownerDocument || aContext).evaluate(aExpression, aContext, aNSResolver, aResultType, null)の結果に応じて、値を真偽値、数値、文字列、単一のDOMノード、またはノードの配列で返します。
var disabledItems = $X(
      '/descendant::*[local-name()="menuitem" and @disabled="true"]',
      utils.getTestWindow()
    );
disabledItems.forEach(function(aItem) {
  assert.isTrue(aItem.disabled);
});

ブラウザ関連操作

これらの機能はFirefox上でテストを実行する場合にのみ利用可能です。

DOMWindow content 別名：contentWindow, utils.content, utils.contentWindow

プロパティとしてアクセスすると、utils.setUpTestWindow()によって開かれたテスト用Firefoxウィンドウの内容領域のDOMWindowオブジェクトを返します。テスト用ウィンドウが開かれていない場合はテストランナー内のテスト用フレームの内容を返します。

assert.equals('selected', content.getSelection());
content.close();
DOMDocument contentDocument 別名：utils.contentDocument

プロパティとしてアクセスすると、utils.setUpTestWindow()によって開かれたテスト用Firefoxウィンドウの内容領域のDOMDocumentオブジェクトを返します。テスト用ウィンドウが開かれていない場合はテストランナー内のテスト用フレームの内容を返します。

assert.equals('UxU - UnitTest.XUL',
              contentDocument.title);
assert.contains('password', contentDocument.cookie);
DOMElement gBrowser 別名：utils.gBrowser

utils.setUpTestWindow()によって開かれたテスト用FirefoxウィンドウのgBrowserオブジェクト（<tabbrowser/>要素）を返します。テスト用ウィンドウが開かれていない場合は、テストランナー内のテスト用フレームを含む<browser/>要素を返します。

assert.equals('www.example.com', gBrowser.currentURI.host);
assert.equals('tabbrowser', gBrowser.localName);
DOMElement utils.getBrowser() 別名：getBrowser()

gBrowserと同じ内容を返します。

assert.equals('www.example.com', utils.getBrowser().currentURI.host);
assert.equals('tabbrowser', utils.getBrowser().localName);
DOMElement Array utils.getTabs() 別名：getTabs()

utils.setUpTestWindow()によって開かれたテスト用Firefoxウィンドウで開かれているタブの配列を返します。ウィンドウが開かれていない場合は空の配列を返します。

assert.equals(3, utils.getTabs().length);
assert.equals('true', utils.getTabs()[1].getAttribute('selected'));
Object utils.loadURI(in String aURI, [in Object aOptions]) 別名：loadURI()

utils.setUpTestWindow()によって開かれたテスト用Firefoxウィンドウの現在のタブで、指定したURIを読み込みます。テスト用ウィンドウが開かれていない場合は、テストランナー内のテスト用フレームにURIを読み込みます。

// 読み込み完了を待って次に進む
utils.loadURI('http://www.clear-code.com/');
var win = utils.getTestWindow();
assert.equals('http://www.clear-code.com/', win.content.location.href);

オプションとしてリファラを指定することもできます。

utils.loadURI('http://www.clear-code.com/',
              { referrer: 'http://www.clear-code.com/about.html' });

このメソッドは、ページの読み込みが完了するまでの間、実行中のテストを一時的に停止します。オプションのasyncプロパティにtrueを指定すると、読み込みが完了するのを待たずに次の行に進みます。このメソッドはロード完了まで待つための処理待ち用オブジェクトを返しますので、返り値をyieldやutils.wait()に渡して処理の完了を待つ事ができます。

var completed = utils.loadURI('http://www.clear-code.com/', { async : true });
// some operations
utils.wait(completed);
Object utils.addTab(in String aURI, [in Object aOptions]) 別名：addTab()

utils.setUpTestWindow()によって開かれたテスト用Firefoxウィンドウで新しいタブを開き、指定したURIをそのタブに読み込みます。実行すると、テスト用ウィンドウが開かれている場合はロード完了まで待つための処理待ち用オブジェクトを、テスト用ウィンドウが開かれていない場合はnullを返します。また、タブのロード完了後は、戻り値のオブジェクトのtabプロパティで、開かれたタブにアクセスすることもできます。

// 読み込み完了を待って次に進む
var win = utils.getTestWindow();
var result = utils.addTab('http://www.clear-code.com/');
assert.equals('ClearCode Inc.', obj.tab.getAttribute('label'));

オプションとしてリファラを指定することもできます。

utils.addTab('http://www.clear-code.com/',
        { referrer: 'http://www.clear-code.com/about.html' });

このメソッドは、ページの読み込みが完了するまでの間、実行中のテストを一時的に停止します。オプションのasyncプロパティにtrueを指定すると、読み込みが完了するのを待たずに次の行に進みます。このメソッドは処理待ち用オブジェクトを返しますので、返り値をyieldやutils.wait()に渡して処理の完了を待つ事ができます。

var result = utils.addTab('http://www.clear-code.com/', { async : true });
// some operations
utils.wait(result);

utils.loadURI()およびutils.addTab()に相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。

メール関連操作

これらの機能は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で指定されたメールフォルダを削除します。ごみ箱への移動ではなく、フォルダ内のメッセージも含めての完全削除となります。

メッセージ編集ウィンドウの操作

DOMWindow mail.compose.window

すでに開かれているメッセージ編集ウィンドウの中で、最初の1つを返します。

Object mail.compose.setUp()

実行すると、新しくメッセージ編集ウィンドウを開き、準備が完了するまで待つための処理待ち用オブジェクトを返します。Thunderbirdのメインウィンドウが1つも開かれていない場合は、メインウィンドウも同時に開きます。

void mail.compose.tearDown()

実行すると、mail.compose.setUp()によって開かれたメッセージ編集ウィンドウを1つ閉じます。mail.compose.setUp()によってメインウィンドウも同時に開かれ、すべてのメッセージ編集ウィンドウが閉じられた場合は、そのメインウィンドウも閉じられます。

Object Array mail.compose.recipients

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、送信先として入力されているすべてのメールアドレスを収集し、以下のプロパティを持つオブジェクトの配列として返します。

String type
選択されている種類（to、cc、bcc、reply-to、followup-to、newsgroupsのいずれか）
String address
入力されているメールアドレス
mail.compose.recipients = Object Array

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、送信先として、与えられた配列のメールアドレスを入力します。すでに入力されていたアドレスはすべて消去されます。

配列の内容はtypeとaddressの各プロパティを持つオブジェクトか、またはメールアドレスの文字列です。メールアドレスの文字列の配列を渡した場合は、すべてのアドレスが「To」として入力されます。

String mail.compose.subject

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、件名として入力されている内容を返します。

mail.compose.subject = String

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、与えられた文字列を件名として入力します。すでに入力されていた件名は失われます。

DOMElement mail.compose.body

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、本文として入力されている内容を返します。返り値の形式は、本文編集用のフレームにおけるBODY要素（DOMElement）です。プレーンテキスト形式のメールの場合でもBODY要素を返すことに注意してください。

mail.compose.body = contents

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、与えられた内容を本文に入力します。すでに入力されていた内容はすべて失われます。

内容には、文字列、DOMNode、DOMDocumentFragmentのいずれかを受け付けます。これら以外の形式の値を渡した場合は、文字列として扱います。

nsIFile Array mail.compose.attachments

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、添付ファイルをnsIFile形式のオブジェクトの配列として取得します。

mail.compose.attachments = Object Array

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、与えられた内容を添付ファイルとして設定します。添付ファイルとしては、パス文字列、File URL、またはnsIFileのオブジェクトを指定することができます。なお、すでに入力されていた添付ファイルはすべては失われます。

メール送信操作

void mail.compose.send(in Boolean aAsync, [in DOMWindow aComposeWindow])

mail.compose.windowで参照されるメッセージ編集ウィンドウについて、編集中のメッセージを送信します。ただし、実際にはSMTPによるメール送信は行わず、送信されていたはずの内容を模したオブジェクトをmail.deliveriesに格納して処理を終えます。

Object Array mail.deliveries

mail.compose.send()で送信したメールの内容を返します。各メールに相当するオブジェクトは以下のプロパティを持ちます。

  • String from
  • String replyTo
  • String to
  • String cc
  • String bcc
  • String subject
  • String organization
  • String priority
  • String messageId
  • String characterSet
  • String body
  • String newsgroups
  • String newshost
  • String newspostUrl
  • String followupTo

ファイル操作

ファイルの読み書き

String utils.readFrom(in Object aFile, [in String aEncoding]) 別名：readFrom()

指定されたファイルの内容をテキストファイルとして読み込み、内容を返します。第1引数にはパス文字列、File URL、またはnsIFileのオブジェクトを指定します。

第2引数としてエンコーディングを指定すると、そのエンコーディングからFirefoxの内部処理用エンコーディング（UCS-2）に変換した結果を返します。エンコーディング指定を省略すると読み込んだままのデータを返します。例えばUTF-8で記述されたファイルを読み込む場合はutils.readFrom(file, "UTF-8")と指定して下さい。

var contents = utils.readFrom('../../fixtures/data.txt', 'Shift_JIS');
nsIFile utils.writeTo(in String aContent, in Object aFile, [in String aEncoding]) 別名：writeTo()

渡された文字列を、指定されたファイルに書き出します。第2引数にはパス文字列、File URL、またはnsIFileのオブジェクトを指定します。

第3引数としてエンコーディングを指定すると、内部エンコーディング（UCS-2）からそのエンコーディングに変換して出力します。エンコーディング指定を省略すると内部エンコーディングのまま出力します。例えばUTF-8でファイルを出力する場合はutils.writeTo(content, file, "UTF-8")と指定して下さい。

なお、すでに存在するファイルを指定した場合は確認無しに上書きされます。

utils.writeTo(result.join('\n'), tempFile, 'Shift_JIS');

これらのメソッドに相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。

ファイルの生成/コピー/削除

nsIFile utils.cosmeticClone(in Object aOriginalFile, in Object aDestinationFolder, in String aName) 別名：cosmeticClone()

第1引数で渡されたファイルまたはフォルダを、第2引数で渡されたフォルダの中に、第3引数で渡された名前で複製します。第3引数を省略した場合は、元のファイルと同じ名前で複製します。

フォルダを複製する場合、中に含まれているファイルやフォルダのうち、不可視のファイル（Windowsの隠しファイル、Linuxの「.」で始まる名前のファイルなど）は複製されません。

返り値は複製されたファイルまたはフォルダです。

utils.cosmeticClone('./logs', logDir, Date.now());
nsIFile utils.makeTempFile([in Object aOriginalFile]) 別名：utils.createTempFile(), makeTempFile(), createTempFile()

プラットフォームのテンポラリフォルダ内にテンポラリファイルを生成し、それを返します。第1引数にパス文字列、File URL、またはnsIFileのオブジェクトを渡した場合、生成されるテンポラリファイルはそのファイルの複製になります。第1引数でフォルダを指定した場合、utils.makeTempFolder()と同じ動作になります。

var newTempFile = utils.makeTempFile();
var cloned = utils.makeTempFile('../fixtures/file.txt');
nsIFile utils.makeTempFolder([in Object aOriginalFolder], [in Boolean aCosmetic]) 別名：utils.makeTempDirectory(), utils.makeTempDir(), utils.createTempFolder(), utils.createTempDirectory(), utils.createTempDir(), makeTempFolder(), makeTempDirectory(), makeTempDir(), createTempFolder(), createTempDirectory(), createTempDir()

プラットフォームのテンポラリフォルダ内にテンポラリフォルダを生成し、それを返します。第1引数にパス文字列、File URL、またはnsIFileのオブジェクトを渡した場合、生成されるテンポラリフォルダはそのフォルダの複製になります。第2引数にtrueを渡した場合、不可視のファイル（Windowsの隠しファイル、Linuxの「.」で始まる名前のファイルなど）は複製されません。

var newTempFolder = utils.makeTempFolder();
var cloned = utils.makeTempFolder('../fixtures', true);
void utils.cleanUpTempFiles() 別名：cleanUpTempFiles()

そのテストケース内でutils.makeTempFile()およびutils.makeTempFolder()によって生成されたすべてのテンポラリファイルを消去します。ただし、使用中であるなどの理由でロックされていて削除できないファイルはそのまま残ります。

function tearDown() {
  utils.cleanUpTempFiles();
}
void utils.scheduleToRemove(in Object aFile) 別名：scheduleToRemove()

渡されたファイルを削除します。nsIFileのremove()メソッドによってその場ですぐに削除するのではなく、数ミリ秒後に遅れて削除を実行し、失敗した場合は一定回数・一定時間の間自動的に削除を再試行します。

utils.scheduleToRemove('temp/tempFile.zip');

これらのメソッドに相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。

ファイルURLとファイルパスの相互変換

nsIFile utils.normalizeToFile(in Object aFile) 別名：normalizeToFile()

パス文字列、File URL、nsIFileURL、またはnsIFileのオブジェクトで渡された内容を、nsIFileファイルのオブジェクトとして返します。相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。

var file1 = utils.normalizeToFile('c:\\file.txt');
var file2 = utils.normalizeToFile(baseURL+'/file.txt');
nsIFile utils.makeFileWithPath(in String aFilePath) 別名：utils.getFileFromPath(), makeFileWithPath(), getFileFromPath()

プラットフォームのパス文字列で指定されたファイルに対応するnsIFileのオブジェクトを生成します。

var file = utils.makeFileWithPath('d:\\test\\file.txt');
nsIFile utils.getFileFromURL(in nsIFile aFileURL) 別名：getFileFromURL()

nsIFileURL形式で指定されたファイルに対応するnsIFileのオブジェクトを生成します。

var file = utils.getFileFromURL(gBrowser.currentURI);
nsIFile utils.getFileFromURLSpec(in String aFileURLSpec) 別名：getFileFromURLSpec()

File URL文字列で指定されたファイルに対応するnsIFileのオブジェクトを生成します。

var file = utils.getFileFromURLSpec(gBrowser.currentURI.spec);
nsIFile utils.getFileFromKeyword(in String aKeyword) 別名：getFileFromKeyword()

指定されたキーワードに対応するnsIFileのオブジェクトを生成します。利用可能なキーワードについてはnsDirectoryServiceDefs.hやnsXULAppAPI.hなどを参照してください。

var extensions = utils.getFileFromKeyword('ProfD');
extensions.append('extensions');
String utils.getFilePathFromURL(in nsIFileURL aFileURL) 別名：getFilePathFromURL()

nsIFileURL形式で指定されたファイルについて、そのプラットフォームでのパス文字列を得ます。

var path = utils.getFilePathFromURL(gBrowser.currentURI);
String utils.getFilePathFromURLSpec(in String aFileURLSpec) 別名：getFilePathFromURLSpec()

File URL文字列で指定されたファイルについて、そのプラットフォームでのパス文字列を得ます。

var path = utils.getFilePathFromURL(gBrowser.currentURI.spec);
String utils.getFilePathFromKeyword(in String aKeyword) 別名：getFilePathFromKeyword()

指定されたキーワードに対応するファイルについて、そのプラットフォームでのパス文字列を得ます。利用可能なキーワードについてはnsDirectoryServiceDefs.hやnsXULAppAPI.hなどを参照してください。

var path = utils.getFilePathFromKeyword('ProfD');
nsIURI utils.getURLFromFile(in nsIFile aFile) 別名：getURLFromFile()

nsIFile形式で指定されたファイルについて、対応するFile URLのnsIFileURL形式のオブジェクトを得ます。

var parentURL = utils.getURLFromFile(profile.parent);
nsIURI utils.getURLFromFilePath(in String aFilePath) 別名：getURLFromFilePath()

プラットフォームのパス文字列で指定されたファイルについて、対応するFile URLのnsIFileURL形式のオブジェクトを得ます。

var fileURL = utils.getURLFromFilePath('d:\\test\\file.txt');
String utils.getURLSpecFromFile(in nsIFile aFileURL) 別名：getURLSpecFromFile()

nsIFile形式で指定されたファイルについて、対応するFile URLのURL文字列を得ます。

image.src = utils.getURLSpecFromFile(imageFile);
String utils.getURLSpecFromFilePath(in String aFileURL) 別名：getURLSpecFromFilePath()

プラットフォームのパス文字列で指定されたファイルについて、対応するFile URLのURL文字列を得ます。

image.src = utils.getURLSpecFromFilePath('d:\\test\\image.jpg');

ファイルのハッシュの取得

String utils.computeHashFromFile(in Object aFile, in String aAlgorithm) 別名：computeHash()

第2引数で指定されたハッシュ関数を用いて、第1引数のファイルの内容のハッシュ値を計算し、その文字列を返します。ハッシュ関数名としてmd2、md5、sha1、sha256、sha384、sha512のうちのいずれかを利用できます。

assert.equals('7BD6E50A060F9D63CDD89082CC215025A800333E',
              utils.computeHashFromFile('../result.jpg', 'sha1'));
String utils.md2FromFile(in Object aFile) 別名：md2FromFile()

渡されたファイルの内容のMD2ハッシュ値の文字列を返します。utils.computeHashFromFile(aFile, 'md2')と同じ働きをします。

String utils.md5FromFile(in Object aFile) 別名：md5FromFile()

渡されたファイルの内容のMD5ハッシュ値の文字列を返します。utils.computeHashFromFile(aFile, 'md5')と同じ働きをします。

String utils.sha1FromFile(in Object aFile) 別名：sha1FromFile()

渡されたファイルの内容のSHA-1ハッシュ値の文字列を返します。utils.computeHashFromFile(aFile, 'sha1')と同じ働きをします。

String utils.sha256FromFile(in Object aFile) 別名：sha256FromFile()

渡されたファイルの内容のSHA-256ハッシュ値の文字列を返します。utils.computeHashFromFile(aFile, 'sha256')と同じ働きをします。

String utils.sha384FromFile(in Object aFile) 別名：sha384FromFile()

渡されたファイルの内容のSHA-384ハッシュ値の文字列を返します。utils.computeHashFromFile(aFile, 'sha384')と同じ働きをします。

String utils.sha512FromFile(in Object aFile) 別名：sha512FromFile()

渡されたファイルの内容のSHA-512ハッシュ値の文字列を返します。utils.computeHashFromFile(aFile, 'sha512')と同じ働きをします。

utils.computeHashFromFile()に相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。

文字列操作

String utils.UTF8ToUCS2(in String aInput) 別名：utils.UTF8ToUnicode(), UTF8ToUCS2(), UTF8ToUnicode()

UTF-8バイト列をMozilla内部で一般的に使われているUCS-2（Unicode）の文字列に変換します。

var string = utils.UTF8ToUCS2(someXPCOMComponent.getResult());
String utils.UCS2ToUTF8(in String aInput) 別名：utils.UnicodeToUTF8(), UCS2ToUTF8(), UnicodeToUTF8()

UCS-2（Unicode）の文字列をUTF-8バイト列に変換します。

someXPCOMComponent.setValue(utils.UCS2ToUTF8(string));
String utils.XToUCS2(in String aInput, in String aEncoding) 別名：utils.XToUnicode(), XToUCS2(), XToUnicode()

Shift_JISやEUC-JPでエンコードされた文字列を、Mozilla内部で一般的に使われているUCS-2（Unicode）の文字列に変換します。第1引数は変換する文字列、第2引数は変換元のエンコーディング名です。

var string = utils.XToUCS2(string, 'EUC-JP');
String utils.UCS2ToX(in String aInput, in String aEncoding) 別名：utils.UnicodeToX(), UCS2ToX(), UnicodeToX()

UCS-2（Unicode）の文字列を、Shift_JISやEUC-JPでエンコードされた文字列に変換します。第1引数は変換する文字列、第2引数は変換先のエンコーディング名です。

var string = utils.UCS2ToX(string, 'EUC-JP');
String utils.inspect(in Object aObject, [in String aIndent]) 別名：inspect()

渡された内容を可読性の高い文字列に変換します。具体的には以下のルールに則って文字列化します。

Array型
配列のすべての要素をutils.inspect()したものを返します。
Object型（オブジェクトリテラル、ハッシュ、カスタムクラスのインスタンス）
持っているすべてのプロパティの名前と値（utils.inspect()した結果）を列挙したものを返します。

第2引数として文字列を渡すと、その文字列でインデントして整形した結果を返します。例えば" "（半角スペース2つ）を渡せば、2インデントの結果が返されます。

utils.log(utils.inspect(result));
String utils.inspectDOMNode(in DOMNode aNode) 別名：inspectDOMNode()

渡されたDOMノードからソース文字列を得ます。HTML文書やXML文書の処理結果を構造まで含めて簡易的に比較する場合などに利用できます。

assert.equals(utils.inspectDOMNode($('template')),
              utils.inspectDOMNode(generated));
String utils.getClipBoard() 別名：getClipBoard()

システムのクリップボードに格納された内容を文字列として取得します。クリップボードの内容が文字列でない場合、相当する内容が文字列化された物、もしくは空文字が返ります。

assert.equals('copied', utils.getClipBoard());
void utils.setClipBoard(in String aString) 別名：setClipBoard()

システムのクリップボードに文字列をコピーします。

utils.setClipBoard('foobar');
assert.equals('foobar', service.getStringFromClipBoard());
String utils.processTemplate(in String aString, [in Object aScope]) 別名：processTemplate()

文字列の中に埋め込まれたJavaScriptのコードを解釈し、結果の文字列を返します。<%で始まり%>で終わる箇所は、通常のJavaScriptとして評価されます。<%=で始まり%>で終わる箇所は、内容として書かれたJavaScriptを式として評価した時の値に置き換えられます。

埋め込まれたコードは第2引数として渡されたオブジェクトまたはテストケースの実行コンテキストで実行され、第2引数のオブジェクトのプロパティは埋め込まれたコードから変数として参照できます。

var source = <![CDATA[
      大切な事なので3回言います。
      <% for (var i = 0; i < 3; i++) { %>
        今日は<%= today %>です。
      <% } %>
      オーケー？
    ]]>.toString();
var params = {
      today : (new Date()).toString()
    };
var result = utils.processTemplate(source, params);
Boolean utils.compareVersions(in String aVersionA, in String aOperator, in String aVersionB) 別名：compareVersions()

2つのバージョン番号文字列を第2引数で指定した比較演算子で比較して、結果を真偽値で返します。比較演算子には ==, !=, <, <=, >, >= のいずれかを指定します。比較演算子以外を渡した場合はエラーになります。

utils.compareVersions('2.0.0.16', '<', '3.0.10'); // true
utils.compareVersions('3.0', '==', '3.0.0'); // true
utils.compareVersions('3.6a1pre', '>=', '3.5b5'); // true
Number utils.compareVersions(in String aVersionA, in String aVersionB)

utils.compareVersions()のに引数を2つだけ渡した場合、こちらの挙動になります。

2つのバージョン番号文字列を比較して、aVersionA < aVersionBであれば-1を、aVersionA > aVersionBであれば1を、両者が等しければ0を返します。

utils.compareVersions('2.0.0.16', '3.0.10'); // -1
utils.compareVersions('3.0', '3.0.0'); // 0
utils.compareVersions('3.6a1pre', '3.5b5'); // 1
String utils.computeHash(in String aString, in String aAlgorithm) 別名：computeHash()

第2引数で指定されたハッシュ関数を用いて、第1引数の文字列のハッシュ値を計算し、その文字列を返します。ハッシュ関数名としてmd2、md5、sha1、sha256、sha384、sha512のうちのいずれかを利用できます。

assert.equals('2AAE6C35C94FCFB415DBE95F408B9CE91EE846ED',
              utils.computeHash('hello world', 'sha1'));
String utils.md2(in String aString) 別名：md2()

渡された文字列のMD2ハッシュ値の文字列を返します。utils.computeHash(aString, 'md2')と同じ働きをします。

String utils.md5(in String aString) 別名：md5()

渡された文字列のMD5ハッシュ値の文字列を返します。utils.computeHash(aString, 'md5')と同じ働きをします。

String utils.sha1(in String aString) 別名：sha1()

渡された文字列のSHA-1ハッシュ値の文字列を返します。utils.computeHash(aString, 'sha1')と同じ働きをします。

String utils.sha256(in String aString) 別名：sha256()

渡された文字列のSHA-256ハッシュ値の文字列を返します。utils.computeHash(aString, 'sha256')と同じ働きをします。

String utils.sha384(in String aString) 別名：sha384()

渡された文字列のSHA-384ハッシュ値の文字列を返します。utils.computeHash(aString, 'sha384')と同じ働きをします。

String utils.sha512(in String aString) 別名：sha512()

渡された文字列のSHA-512ハッシュ値の文字列を返します。utils.computeHash(aString, 'sha512')と同じ働きをします。

JSONの利用

Object utils.readJSON(in Object aFile, [in String aEncoding], [in Object aScope]) 別名：readJSON()

指定されたファイルの内容をテキストとして読み込み、eval()した結果を返します。第1引数にはパス文字列、File URL、またはnsIFileのオブジェクトを指定します。ファイルのエンコーディングは初期状態ではUTF-8として認識しますが、第2引数でエンコーディングを明示することもできます。

第3引数としてオブジェクトを渡すと、ファイルの内容をeval()する前に、その引数を実行コンテキストとしてutils.processTemplate()を実行します。

var data1 = utils.readJSON('../fixtures/data.json');

var data2 = utils.readJSON(
              '../fixtures/SJIS.json',
              'Shift_JIS',
              { date : Date.now() }
            );

CSVの利用

String Array utils.parseCSV(in String aCSV) 別名：parseCSV()

渡された文字列をCSVとして解釈し、結果を2次元の配列として返します。解釈のルールは以下の通りです。

  • CSVの形式はRFC4180と見なす。
  • 各フィールド（セル）の値はすべて文字列として解釈する。
  • フィールド内の改行文字はすべて\nに変換する。
  • タブや数式などは、通常の文字列として解釈する。
var CSV = <![CDATA[name,party,country
麻生 太郎,自民党,Japan
鳩山 由紀夫,民主党,Japan
ジョージ・W・ブッシュ,共和党,USA
バラク・オバマ,民主党,USA]]>.toString();

assert.equals(
  [['name', 'party', 'country'],
   ['麻生 太郎', '自民党', 'Japan'],
   ['鳩山 由紀夫', '民主党', 'Japan'],
   ['ジョージ・W・ブッシュ', '共和党', 'USA'],
   ['バラク・オバマ', '民主党', 'USA']],
  utils.parseCSV(CSV)
);
String Array utils.readCSV(in Object aFile, [in String aEncoding], [in Object aScope]) 別名：readCSV()

指定されたファイルの内容をテキストとして読み込み、utils.parseCSV()した結果を返します。第1引数にはパス文字列、File URL、またはnsIFileのオブジェクトを指定します。ファイルのエンコーディングは初期状態ではUTF-8として認識しますが、第2引数でエンコーディングを明示することもできます。

第3引数としてオブジェクトを渡すと、ファイルの内容をutils.parseCSV()する前に、その引数を実行コンテキストとしてutils.processTemplate()を実行します。

var data1 = utils.readCSV('../fixtures/data.csv');

var data2 = utils.readCSV(
              '../fixtures/SJIS.csv',
              'Shift_JIS',
              { date : Date.now() }
            );
Object utils.readParametersFromCSV(in Object aFile, [in String aEncoding], [in Object aScope]) 別名：readParametersFromCSV(), readParameterFromCSV(), readParamsFromCSV(), readParamFromCSV(), utils.readParameterFromCSV(), utils.readParamsFromCSV(), utils.readParamFromCSV()

指定されたファイルの内容をテキストとして読み込み、utils.parseCSV()した上で、後述のルールに則り解釈した結果のオブジェクト（データ駆動型テスト用のパラメータ）を返します。第1引数にはパス文字列、File URL、またはnsIFileのオブジェクトを指定します。ファイルのエンコーディングは初期状態ではUTF-8として認識しますが、第2引数でエンコーディングを明示することもできます。

第3引数としてオブジェクトを渡すと、ファイルの内容をutils.parseCSV()する前に、その引数を実行コンテキストとしてutils.processTemplate()を実行します。

var data = utils.readParametersFromCSV('../fixtures/data.csv', 'UTF-8');
test_myFunc.parameters = data;
function test_myFunc(aParameter) {
  assert.equals(aParameter.expected, myFunc(aParameter.input));
}

CSVからの変換のルールは以下の通りです。

  • 各レコードをハッシュに変換する。
  • 最初のレコード（行）はカラムの定義と見なし、カラム名を以降のレコードに対応するハッシュのキーとする。
  • 最初のレコードの1番目のフィールド（セル）が空の場合は、戻り値をハッシュにして、各レコードの1番目のフィールドの内容をハッシュのキーとする。そうでない場合は、戻り値を配列にする。
  • カラム名の末尾に以下の文字列（大文字小文字は区別しない）がある場合、その部分をカラム名から取り除いた上で、フィールドの値をその型として解釈する。
    指定する文字列値の型
    [string]文字列値
    [char]
    [number]数値（小数）
    [float]
    [double]
    [int]整数値
    [boolean]真偽値
    [bool]
    [object]JSON文字列（JavaScriptのオブジェクトに変換）
    [json]
    それ以外、または無指定trueまたはfalseの場合は真偽値、10進実数の場合は数値、それ以外は文字列値として自動判別
  • 同名のカラムが複数ある場合や、同名のレコードが複数ある場合（戻り値がハッシュの場合）は、2つ目以降の名前の末尾に「(2)」「(3)」のような文字列を付与し、すべてのカラム・すべてのレコードの名前が一意になるようにする。

具体的な変換例：

inputtoString16 [string]toUpperCase16 [string]
10aA
255ffFF

↓

[{ input: 10,  toString16: 'a',  toUpperCase16: 'A' },
 { input: 255, toString16: 'ff', toUpperCase16: 'FF' }]
　inputtoString16 [string]toUpperCase16 [string]
1桁10aA
2桁255ffFF

↓

{ '1桁': { input: 10,  toString16: 'a',  toUpperCase16: 'A' },
  '2桁': { input: 255, toString16: 'ff', toUpperCase16: 'FF' }}
String Array utils.parseTSV(in String aTSV) 別名：parseTSV()

渡された文字列をタブ区切りのCSVとして解釈し、結果を2次元の配列として返します。区切り文字が異なる以外はutils.parseCSV()と同じ動作をしますので、詳細はそちらを参照して下さい。

String Array utils.readTSV(in Object aFile, [in String aEncoding], [in Object aScope]) 別名：readTSV()

指定されたファイルの内容をテキストとして読み込み、utils.parseTSV()した結果を返します。区切り文字が異なる以外はutils.readCSV()と同じ動作をしますので、詳細はそちらを参照して下さい。

Object utils.readParametersFromTSV(in Object aFile, [in String aEncoding], [in Object aScope]) 別名：readParametersFromTSV(), readParameterFromTSV(), readParamsFromTSV(), readParamFromTSV(), utils.readParameterFromTSV(), utils.readParamsFromTSV(), utils.readParamFromTSV()

指定されたファイルの内容をテキストとして読み込み、utils.parseTSV()した上で、utils.readParametersFromCSV()と同様の解釈した結果のオブジェクト（データ駆動型テスト用のパラメータ）を返します。区切り文字が異なる以外はutils.readParametersFromCSV()と同じ動作をしますので、詳細はそちらを参照して下さい。

ローカルHTTPサーバの操作

Object utils.setUpHttpServer(in Number aPort, in Object aDocumentRoot, [in Boolean aAsync]) 別名：utils.setUpHTTPServer(), setUpHttpServer(), setUpHTTPServer()

第2引数で指定したフォルダ（パス、File URL、またはnsIFileのオブジェクトで指定）をドキュメントルートとして、第1引数のポート番号でHTTPサーバデーモンを起動します。実行すると、起動したHTTPサーバデーモンのインスタンスを返します。返り値のHTTPサーバオブジェクトが持つメソッドを使うと、起動したローカルHTTPサーバをモックとして利用できます。

var server = utils.setUpHttpServer(4445, '../fixtures/');
utils.loadURI('http://localhost:4445/sample.html');
assert.equals('sample page', content.document.title);

通常、このメソッドはサーバの起動の完了を待ってから値を返して処理を次に進めます。第3引数にtrueを渡すと、サーバの起動の完了を待たずに処理を次に進めます。この場合、返り値のオブジェクト自体をサーバの起動の完了を待つための処理待ち用オブジェクトとして利用できます。

Object utils.getHttpServer(in Number aPort) 別名：utils.getHTTPServer(), getHttpServer(), getHTTPServer()

第1引数のポート番号で起動しているHTTPサーバデーモンのインスタンスを取得します。そのポートで起動しているHTTPサーバが存在しない場合はnullを返します。返り値のHTTPサーバオブジェクトが持つメソッドを使うと、ローカルHTTPサーバをモックとして利用できます。

var server = utils.getHttpServer(4445);
Object utils.tearDownHttpServer(in Number aPort, [in Boolean aAsync]) 別名：utils.tearDownHTTPServer(), tearDownHttpServer(), tearDownHTTPServer()

utils.setUpHttpServer()によって起動されたHTTPサーバデーモンのうち、第1引数のポート番号で起動したものを終了します。

utils.tearDownHttpServer(4445);

通常、このメソッドはサーバの終了処理の完了を待ってから処理を次に進めます。第2引数にtrueを渡すと、終了処理の完了を待たずに処理を次に進めます。この場合、返り値を終了処理の完了を待つための処理待ち用オブジェクトとして利用できます。

Function utils.tearDownAllHttpServers([in Boolean aAsync]) 別名：utils.tearDownAllHTTPServers(), utils.tearDownHttpServers(), utils.tearDownHTTPServers(), tearDownHttpServers(), tearDownHTTPServers(), tearDownHttpServers(), tearDownHTTPServers()

そのテストケース中で起動したすべてのHTTPサーバデーモンを終了します。

utils.tearDownAllHttpServers();

通常、このメソッドはすべてのサーバの終了処理の完了を待ってから処理を次に進めます。第1引数にtrueを渡すと、終了処理の完了を待たずに処理を次に進めます。この場合、返り値を終了処理の完了を待つための処理待ち用関数として利用できます。

テストケース中で起動されたすべてのサーバデーモンは、テストケース全体の実行終了時に自動的に終了されます。

データベース操作

mozIStorageConnection utils.openDatabase(in Object aFile) 別名：openDatabase()

パス、File URL、またはnsIFileのオブジェクトで指定されたSQLiteデータベースのファイルへ接続し、コネクションオブジェクトを返します。

var dbconn = utils.openDatabase('../fixtures/test.sqlite');
var statement = dbconn.createStatement('SELECT value FROM test_table WHERE key = "foo"');
statement.executeStep();
var value = statement.getString(0);
mozIStorageConnection utils.createDatabase() 別名：createDatabase()

プラットフォームのテンポラリフォルダ内にテンポラリファイルを生成し、SQLiteデータベースとして接続してコネクションオブジェクトを返します。

var dbconn = utils.createDatabase();
dbconn.executeSimpleSQL('CREATE TABLE test_table (key TEXT PRIMARY KEY, value TEXT)');
mozIStorageConnection utils.createDatabaseFromSQL(in String aSQL) 別名：createDatabaseFromSQL()

プラットフォームのテンポラリフォルダ内にテンポラリファイルを生成し、SQLiteデータベースとして接続した上で、指定されたSQL文を実行してからコネクションオブジェクトを返します。

var dbconn = utils.createDatabaseFromSQL(<![CDATA[
               DROP TABLE IF EXISTS "foo_table";
               CREATE TABLE "foo_table" ("key" TEXT PRIMARY KEY  NOT NULL , "value" TEXT);
               INSERT INTO "foo_table" VALUES('foo','bar');
               INSERT INTO "foo_table" VALUES('hoge','fuga');
             ]]>.toString());
var statement = dbconn.createStatement('SELECT value FROM foo_table WHERE key = "foo"');
statement.executeStep();
var value = statement.getString(0);
mozIStorageConnection utils.createDatabaseFromSQLFile(in Object aFile, [in String aEncoding], [in Object aScope]) 別名：createDatabaseFromSQLFile()

プラットフォームのテンポラリフォルダ内にテンポラリファイルを生成し、SQLiteデータベースとして接続した上で、指定されたファイルの内容をSQL文として実行してからコネクションオブジェクトを返します。ファイルのエンコーディングは初期状態ではUTF-8として認識しますが、第2引数でエンコーディングを明示することもできます。

第3引数としてオブジェクトを渡すと、その引数を実行コンテキストとして、ファイルから読み込まれたSQL文に対しutils.processTemplate()を実行します。

var dbconn = utils.createDatabaseFromSQLFile('../fixtures/test.sql', 'Shift_JIS');
var statement = dbconn.createStatement('SELECT value FROM test_table WHERE key = "key1"');
statement.executeStep();
var value = statement.getString(0);

スクリプトの読み込み

Object utils.import(in Object aFile, [inout Object aNamespace]) 別名：import()

パス、File URL、nsIFileのオブジェクトで指定されたファイルの内容をスクリプトとして読み込んでクリーンな環境で実行した上で、実行時のグローバルオブジェクトを返します。スクリプト中でEXPORTED_SYMBOLSで宣言された変数は、テストの実行環境にエクスポートされます。第2引数としてオブジェクトを渡した場合、EXPORTED_SYMBOLSで宣言された変数はそのオブジェクトにエクスポートされます。ファイルのエンコーディングは自動判別されます。

// the module includes:
//   EXPORTED_SYMBOLS = ["myModule"];
utils.import(baseURL+"../../modules/myModule.js");
assert.isDefined(myModule);

var ns = {};
utils.import(baseURL+"../../modules/myModule.js", ns);
assert.isDefined(ns.myModule);

var module = utils.import(baseURL+"../../modules/myModule.js", {}).notExportedVariable;

このメソッドはComponents.utils.import()と同じ要領で利用できます。ただし、Components.utils.import()とは以下の点が異なります。

  • 実行すると、その都度スクリプトを読み込み、新しいグローバルオブジェクトを生成します。
  • 第1引数として、パス、File URL、nsIFileのオブジェクトを受け取ります。
void utils.include(in Object aFile, [in String aEncoding], [in Object aScope]) 別名：include()
void utils.include(in Object aFile, [in Object aScope])

パス、File URL、nsIFileのオブジェクトで指定されたファイルの内容をスクリプトとして読み込み、テストケースの実行コンテキストで実行します。第2引数としてオブジェクトを渡した場合、そのオブジェクトが実行コンテキストになります。ファイルのエンコーディングは自動判別されますが、第3引数でエンコーディングを明示することもできます。

utils.include('../test/basic.js');

var namespace = { window : {} };
utils.include('../../content/library.js', 'Shfit_JIS', namespace);
var service = namespace.window.globalObject;

utils.include()に相対パスを渡すと、現在読み込まれているテストケースのファイルからの相対パスとして解釈します（baseURL + '<相対パス>' と表記するのと同等です）。

設定の読み書き

value utils.getPref(in String aKey) 別名：getPref()

FirefoxまたはThunderbirdの設定値を取得します。値の型（真偽値、整数値、文字列値）を問わず動作します。

var locale = utils.getPref('general.useragent.locale');
void utils.setPref(in String aKey, in Object aValue) 別名：setPref()

渡された値をFirefoxまたはThunderbirdの設定値として保存します。値の型（真偽値、整数値、文字列値）は自動判別されます。テストの中で行った変更はテスト終了後に元に戻されます。

utils.setPref('extensions.myaddon.feature.enabled', true);
void utils.clearPref(in String aKey) 別名：clearPref()

FirefoxまたはThunderbirdの設定値を削除します。テストの中で行った変更はテスト終了後に元に戻されます。

utils.clearPref('browser.tabs.loadInBackground');
Object utils.loadPrefs(in Object aOriginalFile, [out Object aPrefs]) 別名：loadPrefs()

引数で指定されたパス文字列、File URL、またはnsIFileのオブジェクトが示す設定ファイル（prefs.jsやuser.js、アドオンのデフォルト設定ファイルなど、pref(aKey, aValue);もしくはuser_pref(aKey, aValue);の形で設定が記述されているファイル）の内容をすべて読み込み、設定データベースに一時的に反映します。また、返り値として、読み込まれたすべての設定名と値のハッシュを返します。

なお、このメソッドで読み込まれた設定は、テスト終了後に元に戻されます。

第2引数にハッシュとして何らかのオブジェクトを渡した場合、返り値のハッシュと同じ内容を第2引数のオブジェクトに追加します。この場合、読み込まれた設定の内容は設定データベースには反映されません。

設定ファイルの読み込み時の挙動は、Firefox（Thunderbird）が自分自身の初期設定を読み込む時や、アドオンの初期設定が読み込まれる時の挙動を再現します。具体的には、以下のような挙動となります。

  • #で始まるコメントを許容する。
  • 関数で動的に値を生成するなど、不正な表記の設定ファイルを読み込ませようとするとエラーになる。
  • \"、\'、\\、\r、\n、\xXX（16進数表記でのエスケープ）、\uXXXX（Unicodeエスケープ）以外のエスケープはエスケープ文字を含んだ文字列として取得される（例：\tはタブ文字ではなく"\\t"になる）。
function setUp() {
  utils.loadPrefs('../../defaults/preferences/myaddon.js');
}

var prefs = {};
utils.loadPrefs('../fixtures/clearedPrefs.js', prefs);
for (var i in prefs) {
  utils.clearPref(prefs[i]);
}

アプリケーションの情報の取得

String utils.product 別名：product

現在テストが動作しているアプリケーションの名前を取得します。取得できる値は以下の通りです。

アプリケーション取得できる値
FirefoxFirefox
ThunderbirdThunderbird
SunbirdSunbird
Mozilla Application SuiteMozilla
SeaMonkeySeaMonkey
FennecFennec
それ以外空文字
 
var data = utils.readFrom('../fixtures/'+utils.product+'.txt');
String utils.productVersion 別名：productVersion

現在テストが動作しているアプリケーションのバージョン番号を文字列で取得します。

if (utils.compareVersions(utils.productVersion, '>=', '3.0')) {
  // Firefox 3.0以降用の処理
}
String utils.platformVersion 別名：platformVersion

現在テストが動作しているアプリケーションの、Geckoのバージョン番号を文字列で取得します。

if (utils.compareVersions(utils.platformVersion, '>=', '1.9.2')) {
  // Firefox 3.6以降用の処理
}
nsIFile utils.productExecutable 別名：productExecutable

現在テストが動作しているアプリケーションの実行ファイルをnsIFile形式で取得します。例えばWindows版Firefoxであれば、C:\Program Files\Mozilla Firefox\firefox.exeなどです。

var applicationIni = utils.productExecutable.parent;
applicationIni.append('application.ini');

Windowsのレジストリの操作

Windowsのレジストリを操作するヘルパーメソッドは、Windows上でのみ利用できます。他のプラットフォームで実行した場合、例外が発生します。

Object utils.getWindowsRegistry(in String aKey) 別名：getWindowsRegistry()

指定したキーの値を読み込み、返します。戻り値の型はレジストリのデータの型によって変化します（下記の表を参照）。なお、存在しないキーの値を読み込もうとした場合はnullを返します。

レジストリ上のデータ型戻り値
文字列文字列
整数値数値
バイナリバイト列（配列）
その他実際の値の内容に関わらず、キーが存在する場合はtrue
 
var type = utils.getWindowsRegistry('HKCR\\.txt\\Content Type');
// => maybe "text/plain"
var proxySetting = utils.getWindowsRegistry(
                     'HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\'+
                       'CurrentVersion\\Internet Settings\\MigrateProxy'
                   );
Object utils.setWindowsRegistry(in String aKey, in Object aValue) 別名：setWindowsRegistry()

第1引数で指定したキーに、第2引数で指定した値を保存します。すでにキーが存在している場合、既存の値の型に合わせて値の型を変換します。キーが存在していない場合は、渡されたオブジェクトの種類に応じて型を決定します（下記の表を参照）。第2引数の値をそのまま戻り値として返します。

第2引数の型レジストリ上のデータ型
文字列文字列
数値整数値
バイト列（配列）バイナリ
その他値を保存せず、例外を発生させる
 
utils.setWindowsRegistry(
  'HKEY_CLASSES_ROOT\\.foobar\\Content Type',
  'application/x-foobar'
);
void utils.clearWindowsRegistry(in String aKey) 別名：clearWindowsRegistry()

指定したキーを消去します。サブキーが存在する場合、それらもすべて消去します。

utils.clearWindowsRegistry(
  'HKEY_CURRENT_USER\\Software\\My Company\\My Product'
);

その他

void utils.wait(in Object aWaitingCondition) 別名：wait()

その箇所で処理を一時的に停止し、指定された条件に従って待った後、次の行に進みます。Firefox 3、Thunderbird 3など、Gecko 1.9以降の環境でのみ有効です。

詳細は処理待ちの方法の説明をご覧下さい。

Object utils.waitDOMEvent([DOMイベント指定とDOMイベントターゲットのペア]) 別名：utils.waitDOMEvents(), waitDOMEvent(), waitDOMEvents()

指定されたDOMイベントが対になるDOMイベントターゲットに対して発火するまで待って、処理を次に進めます。複数のDOMイベントとイベントターゲットの対を指定した場合、いずれか1つのイベントが発火した時点で処理を次に進めます。

このメソッドはロード完了まで待つための処理待ち用オブジェクトを返します。また、発火したイベントのオブジェクトを返り値のオブジェクトのeventプロパティで取得できます。

window.setTimeout(function() {
  MyComponent.autoSubmit();
}, 100);

var result = utils.waitDOMEvent('submit', content.document,
                                'unload', content.document);
assert.equals('submit', result.event.type);

イベント名の文字列の代わりにハッシュを渡すと、より細かい条件で捕捉対象のイベントを指定することができます。

utils.waitDOMEvent({ type    : 'keypress',
                     keyCode : Ci.nsIDOMKeyEvent.DOM_VK_RETURN,
                     shiftKey : true },
                   $('input'),
                   { type    : 'keypress',
                     keyCode : Ci.nsIDOMKeyEvent.DOM_VK_ESCAPE,
                     capturing : true }, // キャプチャリングフェイズでの監視
                   $('input') );
deferred Deferred() 別名：utils.Deferred()

JSDeferredのコンストラクタ関数です。すべてのクラスメソッドを利用可能です。また、インスタンスも任意に作成できます。

このコンストラクタ関数から生成したDeferredオブジェクトは、処理待ちの復帰条件として利用できます。

utils.include('../modules/mymodule.js');
MyModule.Deferred = Deferred; // UxUの名前空間のDeferredクラスに置換

utils.wait(MyModule.deferredFunction());
void utils.log(in String aMessage) 別名：log()
void utils.dump(in String aMessage) 別名：dump()

テストランナーとエラーコンソールにメッセージを出力します。複数の引数を渡した場合は改行して出力します。

utils.log('step 1:', object.value);
void utils.notify(in nsISupports aSubject, in String aTopic, in String aData) 別名：notify()

すでに登録されているオブザーバに対して、nsIObserverServiceの機能を使ってメッセージを送出します。ObserverService.notifyObservers()のシンタックスシュガーです。

utils.notify(window, 'CustomEvent:CloseRequest', Date.now());

Window.dump()を使用する場合は、明示的にwindow.dump()と書く必要があることに注意してください。単にdump()とだけ書いた場合は、上記のユーティリティメソッドの方が実行されます。