株式会社クリアコード > フリーソフトウェア開発 > UxU - UnitTest.XUL > アサーション一覧

アサーション一覧 UxU - UnitTest.XUL

内容の比較

void assert.equals(in Object aExpected, in Object aActual, [in String aMessage]) 別名:assertEqual()

特定の値が期待される場面で使用します。期待通りの任意の値が渡されたかどうかを確認し、第2引数として与えられた値が第1引数として与えられた期待値と異なる場合はAssertionFailed例外を発生させます。値の比較はJavaScriptの==演算子と同じ精度で行われます。プリミティブ値、オブジェクト、DOMノード、配列の比較に対応しています。

assert.equals('expectedValue', object.property);
assert.equals($('node'), object.returnsNode());
// 配列の場合は、値同士の比較となる。
assert.equals([$('node1'), $('node2'), $('node2')],
              object.returnsNodesArray());
// オブジェクトの場合は、各プロパティの値同士の比較となる。
assert.equals({ name : 'foo', value : 'bar' },
              object.getResult());
void assert.strictlyEquals(in Object aExpected, in Object aActual, [in String aMessage]) 別名:assertStrictlyEqual()

assert.equals()について、より厳しい基準で比較を行います。具体的には、値の比較はJavaScriptの===演算子と同じ精度で行われます。

var value = 'expectedValue';
assert.strictlyEquals('expectedValue', value); // success
value = new String('expectedValue');
assert.strictlyEquals('expectedValue', value); // failure
void assert.notEquals(in Object aExpected, in Object aActual, [in String aMessage]) 別名:assertNotEqual()

特定の値が期待されない場面で使用します。任意の値と異なる値が期待通りに渡されたかどうかを確認し、第2引数の値が第1引数の値と等しい場合はAssertionFailed例外を発生させます。値の比較はJavaScriptの!=演算子と同じ精度で行われます。プリミティブ値、オブジェクト、DOMノード、配列の比較に対応しています。

assert.notEquals('true', node.getAttribute('disabled'));
assert.notEquals(object.firstItem, object.lastItem);
void assert.notStrictlyEquals(in Object aExpected, in Object aActual, [in String aMessage]) 別名:assertNotStrictlyEqual()

assert.notEquals()について、より厳しい基準で比較を行います。具体的には、値の比較はJavaScriptの!==演算子と同じ精度で行われます。

var value = '10';
assert.notStrictlyEquals(10, value); // success
assert.notStrictlyEquals(10, parseInt(value)); // failure
void assert.contains(in Object aElementShouldBeContained, in Object aElementsOrRange, [in String aMessage]) 別名:assertContain()

特定の値が含まれていることが期待される場面で使用します。第1引数で渡されたオブジェクトが第2引数で渡されたオブジェクトの中に含まれていない場合は、AssertionFailed例外を発生させます。

第2引数にはnsISelection、DOM Range、DOM Node、配列、または文字列のいずれかを渡すことができます(それ以外の型のオブジェクトはすべて文字列として扱われます)。それぞれの場合の具体的な検証内容は以下の表の通りです。

第2引数第1引数検証の内容
nsISelection DOM Range Rangeが、nsISelectionの示す範囲の中に包含されているかどうか。(※nsISelectionが持つRangeのうち1つでも第1引数のRangeに等しい物があるかどうかではなく、nsISelectionが持つRangeのうち1つでも第1引数のRangeを包含する物があるかどうかを検証します。)
DOM Node NodeがnsISelectionの示す範囲の中に包含されているかどうか。
DOM Range DOM Range 第1引数のRangeが、第2引数のRangeの中に包含されているかどうか。
DOM Node NodeがRangeの中に包含されているかどうか。
DOM Node DOM Range 第1引数のRangeが、第2引数のNodeの子孫に含まれているかどうか。
DOM Node 第1引数のNodeが第2引数のNodeの子孫かどうか。
配列 すべての型のオブジェクト 第1引数のオブジェクトが、第2引数の配列の要素かどうか。
それ以外の組み合わせ 第1引数を文字列化した内容が、第2引数を文字列化した内容の中に含まれているかどうか。(※大文字小文字の違いは区別されます。)
assert.contains('- Firefox', window.document.title);

var terms = ['extracted', 'extended', 'expected'];
assert.contains('expected', terms); // success

assert.contains(doc.body.firstChild,
                doc.body); // success

var range = doc.createRange();
range.selectNode(doc.body);
assert.contains(doc.body, range); // success
assert.contains(doc.body.firstChild, range); // success
assert.contains(doc.documentElement, range); // failure
void assert.notContains(in Object aElementShouldNotBeContained, in Object aElementsOrRange, [in String aMessage]) 別名:assertNotContain()

特定の値が含まれていないことが期待される場面で使用します。assert.contains()を反転した動作をします。

assert.notContains('error', object.getResultsArray());
assert.notContains('out of selection', content.getSelection());
void assert.contained(in Object aElementsOrRangeShouldContain, in Object aElement, [in String aMessage]) 別名:assertContained()

特定の範囲や文字列などの中に含まれる値が期待される場面で使用します。第2引数で渡されたオブジェクトが第1引数で渡されたオブジェクトに含まれていない場合、AssertionFailed例外を発生させます。

第1引数と第2引数の種類によって若干動作が変わります。詳しくはassert.contains()の説明をご覧下さい。

assert.contained('Start - Firefox', myAddon.brandName);

var terms = ['extracted', 'extended', 'expected'];
assert.contained(terms, myAddon.lastTerm);

assert.contained(doc.body,
                 doc.body.firstChild); // success

var range = doc.createRange();
range.selectNode(doc.body);
assert.contained(range, doc.body.firstChild); // success
assert.contained(range, doc.documentElement); // failure
void assert.notContained(in Object aElementsOrRangeShouldNotContain, in Object aElement, [in String aMessage]) 別名:assertNotContaied()

特定の範囲や文字列などの中に含まれない値が期待される場面で使用します。assert.contained()を反転した動作をします。

assert.notContained('error,failure', myAddon.lastStatus);
assert.notContained(content.getSelection(), myAddon.getNextNodeOfSelection());
void assert.isTrue(in aExpression, [in String aMessage]) 別名:assert.true(), assert(), assertTrue()

値として真(または空でない文字列、0以外の数値など、真偽値として見たときに真となる値)が期待される場面で使用します。期待に反して偽が渡された場合はAssertionFailed例外を発生させます。

checkbox.setAttribute('checked', true);
assert.isTrue(checkbox.checked);
void assert.isFalse(in aExpression, [in String aMessage]) 別名:assert.false(), assertFalse()

値として偽(または空文字列、数値の0、null、undefinedなど、真偽値として見たときに偽となる値)が期待される場面で使用します。期待に反して真が渡された場合はAssertionFailed例外を発生させます。

checkbox.removeAttribute('checked');
assert.isTrue(checkbox.checked);
void assert.inDelta(in Number aExpected, in Number aActual, in Number aDelta, [in String aMessage]) 別名:assertInDelta()

値として一定の範囲内に収まる数値が期待される場面で使用します。値が指定された範囲の外にある(aActual < aExpected - aDelta または aActual > aExpected + aDelta である)場合はAssertionFailed例外を発生させます。

var array = '0,1,2,3,4,5,6,7,8,9'.split(',');
// 約半分の項目をランダムに抽出する
var extracted = array.filter(function(aItem) {
		return Math.random() > 0.5;
	});
// 誤差として±2までを許容
assert.inDelta(5, extracted.length, 2);
void assert.difference(in Fuction aGetter, in Number aExpectedDifference, in Function aTestTask, [in Object aScope], [in String aMessage]) 別名:assertDifference()

TBD

TBD
void assert.noDifference(in Fuction aGetter, in Function aTestTask, [in Object aScope], [in String aMessage]) 別名:assertNoDifference()

TBD

TBD
void assert.compare(in Number aExpected, in String aOperator, in Number aActual, [in String aMessage]) 別名:assertCompare()

第1引数と第3引数を第2引数の演算子で比較します。期待に反して結果が偽の場合はAssertionFailed例外を発生させます。比較演算子には ==, ===, !=, !==, <, <=, >, >= のいずれかを指定します。比較演算子以外を渡した場合はエラーになります。

assert.compare(100, '<=', func1());
assert.compare(100, '>', func2());

値の比較の注意事項

assert.equals()assert.notEquals()assert.strictlyEquals()assert.notStrictlyEquals()assert.compare()に以下の型のオブジェクトを渡した場合は、特別なルールに則って比較が行われます。

Date

両者のオブジェクトが保持している時刻を比較します。

Array

配列の長さ、各要素を比較します。

Object型(オブジェクトリテラル、ハッシュ、カスタムクラスのインスタンス)

持っているすべてのプロパティの名前と値を比較します。

型の比較

void assert.isBoolean(in aExpression, [in String aMessage]) 別名:assert.boolean(), assertBoolean()

値が真偽値であることが期待される場面で使用します。期待に反して真偽型でない値が渡された場合はAssertionFailed例外を発生させます。

assert.isBoolean(checkbox.checked);
assert.isBoolean(checkbox.disabled);
assert.isBoolean(utility.getPref('some.boolean.pref'));
void assert.isNotBoolean(in aExpression, [in String aMessage]) 別名:assert.notBoolean(), assertNotBoolean()

値が真偽型でないことが期待される場面で使用します。渡された値が期待に反して真偽値である場合はAssertionFailed例外を発生させます。

assert.isNotBoolean(notInitializedObject.booleanProperty);
void assert.isString(in aExpression, [in String aMessage]) 別名:assert.string(), assertString()

値が文字列であることが期待される場面で使用します。期待に反して文字列型でない値が渡された場合はAssertionFailed例外を発生させます。

assert.isString(input.value);
assert.isString(element.getAttribute('undefined-attribute'));
assert.isString(utility.getPref('some.string.pref'));
void assert.isNotString(in aExpression, [in String aMessage]) 別名:assert.notString(), assertNotString()

値が文字列型でないことが期待される場面で使用します。渡された値が期待に反して文字列である場合はAssertionFailed例外を発生させます。

assert.isNotString(notInitializedObject.stringProperty);
void assert.isNumber(in aExpression, [in String aMessage]) 別名:assert.notNumber(), assertNumber()

値が数値であることが期待される場面で使用します。期待に反して数値型でない値が渡された場合はAssertionFailed例外を発生させます。

assert.isNumber(httpClient.errorCode);
assert.isNumber(utility.getPref('some.integer.pref'));
void assert.isNotNumber(in aExpression, [in String aMessage]) 別名:assertNotNumber()

値が数値型でないことが期待される場面で使用します。渡された値が期待に反して数値である場合はAssertionFailed例外を発生させます。

assert.isNotString(notInitializedObject.intProperty);
void assert.isFunction(in aExpression, [in String aMessage]) 別名:assert.function(), assertFuction()

値が関数であることが期待される場面で使用します。期待に反して関数でない値が渡された場合はAssertionFailed例外を発生させます。

assert.isFunction(element.hasAttribute);
assert.isFunction(instance.inheritedMethod);
void assert.isNotFunction(in aExpression, [in String aMessage]) 別名:assert.notFunction(), assertNotFunction()

値が関数でないことが期待される場面で使用します。渡された値が期待に反して関数である場合はAssertionFailed例外を発生させます。

assert.isNotFunction(instanceOfSuperClass.methodOfSubClass);
void assert.isDefined(in aExpression, [in String aMessage]) 別名:assert.defined(), assertDefined()

定義済み(数値、文字列、真偽値、nullなど)の値が期待される場面で使用します。渡された値が期待に反して未定義(undefined)である場合はAssertionFailed例外を発生させます。

assert.isDefined(instance.inheritedProperty);
assert.isDefined(Ci.myICustomInterface);
void assert.isUndefined(in aExpression, [in String aMessage]) 別名:assert.undefined(), assertUndefined()

未定義(undefined)の値が期待される場面で使用します。何らかの値が期待に反して渡された場合はAssertionFailed例外を発生させます。

assert.isUndefined(checkbox.valid);
assert.isUndefined(Ci.myIOldCustomInterface);
void assert.isNull(in aExpression, [in String aMessage]) 別名:assert.null(), assertNull()

nullが期待される場面で使用します。nullでない値(falseやundefinedなども含む)が期待に反して渡された場合はAssertionFailed例外を発生させます。

assert.isNull(element.nodeValue);
assert.isNull(utility.getPref('some.undefined.pref'));
void assert.isNotNull(in aExpression, [in String aMessage]) 別名:assert.notNull(), assertNotNull()

nullが期待されない場面で使用します。nullが期待に反して渡された場合はAssertionFailed例外を発生させます。

assert.isNotNull(element.getAttribute('undefined-attribute'));
assert.isNotNull(utility.getPref('some.defined.pref'));
void assert.isInstanceOf(in Object aExpectedClass, in aObject aInstance, [in String aMessage]) 別名:assert.instanceOf(), assert.instanceof(), assert.instance(), assertInstanceOf(), assertInstanceof(), assertInstance()

TBD

TBD
void assert.inplementsInterface(in Object aInterface, in aObject aInstance, [in String aMessage]) 別名:assert.inplementInterface(), assertInplementsInterface(), assertInplementInterface()

オブジェクトが特定のXPCOMインターフェースを備えていることが期待される場面で使用します。インターフェースはComponents.interfaces.nsI*のリファレンス、もしくはインターフェース名の文字列("nsI*")で指定します。

第2引数に渡されたオブジェクトが指定のインターフェースを備えていない場合は、AssertionFailed例外を発生させます。

assert.implementsInterface(Ci.nsIDOMWindow, getWindow());
assert.implementsInterface('nsIDOMWindow', getWindow());
assert.implementsInterface(Ci.nsIDOMRange, getWindow()); // this will fail

例外の発生と確認

Object assert.raises(in Exception aExpected, in Function aTestTask, [in Object aScope], [in String aMessage]) 別名:assert.throws(), assertRaise(), assertThrow()

特定の例外の発生が期待される場面で使用します。第2引数として渡された関数を、第3引数の値をスコープとして実行し、第1引数で指定された物と同じ例外が期待に反して発生しなかった場合はAssertionFailed例外を発生させます。

loader.INVALID_URI_ERROR = 'invalid uri';
loader.open = function(aURI) {
  if (aURI) this.uri = aURI;
  if (!/^https?:/.test(this.uri))
    throw new Error(this.INVALID_URI_ERROR);
  window.open(this.uri);
};
loader.uri = 'mailto:test@example.com';

assert.raises(
  loader.INVALID_URI_ERROR,
  loader.open,
  loader
);
assert.raises(
  loader.INVALID_URI_ERROR,
  function() {
    loader.open('ftp://ftp.example.com');
  },
  {}
);

例外の判定は、JavaScriptの例外オブジェクト自身、例外のコンストラクタ関数、nameプロパティ, messageプロパティ, resultプロパティ、またはハッシュで指定された任意のプロパティに一致するかどうかで行います。以下はすべて妥当な例です。

assert.raises('error',
              function() { throw 'error'; });
assert.raises('error',
              function() { throw new Error('error'); });
assert.raises('SyntaxError',
              function() { eval('{'); });
assert.raises(SyntaxError,
              function() { eval('{'); });
assert.raises(Components.results.NS_NOINTERFACE,
              function() { window.QueryInterface(Ci.nsIDOMDocument); });
assert.raises('NS_NOINTERFACE',
              function() { window.QueryInterface(Ci.nsIDOMDocument); });
assert.raises({ expected : true, actual : false },
              function() { var e = new Error();
                           e.expected = true;
                           e.actual = false;
                           throw e; });

また、このアサーションは返り値として処理待ち用のオブジェクトを返します。実行したい処理が処理待ちを伴う物である場合に利用できます。

yield Do(assert.raises(
    loader.INVALID_URI_ERROR,
    function() {
      loader.open('http://www.example.com');
      yield 500;
      loader.open('ftp://ftp.example.com');
    },
    {}
  ));
Object assert.notRaises(in Exception aExpected, in Function aTestTask, in Object aScope, [in String aMessage]) 別名:assert.notThrows(), assertNotRaise(), assertNotThrow()

特定の例外の発生が期待されない場面で使用します。第2引数として渡された関数を、第3引数の値をスコープとして実行し、第1引数で指定された物と同じ例外が期待に反して発生した場合はAssertionFailed例外を発生させます。例外が一致しているかどうかの判定はassert.raise()と同じ判断基準で行います。

loader.INVALID_URI_ERROR = 'invalid uri';
loader.open = function(aURI) {
  if (aURI) this.uri = aURI;
  if (!/^https?:/.test(this.uri))
    throw new Error(this.INVALID_URI_ERROR);
  window.open(this.uri);
};
loader.uri = 'http://www.example.com';

assert.notRaises(
  loader.INVALID_URI_ERROR,
  loader.open,
  loader
);
assert.notRaises(
  loader.INVALID_URI_ERROR,
  function() {
    loader.open('https://secure.example.com');
  },
  {}
);

また、このアサーションは返り値として処理待ち用のオブジェクトを返します。実行したい処理が処理待ちを伴う物である場合に利用できます。

yield Do(assert.notRaises(
    loader.INVALID_URI_ERROR,
    function() {
      loader.open('http://www1.example.com');
      yield 500;
      loader.open('http://www2.example.com');
    },
    {}
  ));

所要時間の確認

Object assert.finishesWithin(in Number aExpectedTime, in Function aTestTask, in Object aScope, [in String aMessage]) 別名:assert.finishWithin(), assertFinishWithin()

一定時間内に処理が完了することが期待される場面で使用します。第2引数として渡された関数を、第3引数の値をスコープとして実行し、処理を完了するまでに第1引数で指定された時間(単位:ミリ秒)以上の時間がかかった場合はAssertionFailed例外を発生させます。

function functionContainsLongLoop() {
  for (var i = 0, maxi = 5000; i < maxi; i++) {
    process(data[i]);
  }
}
assert.finishesWithin(
  5 * 1000, // 5sec.
  functionContainsLongLoop,
  {}
);

また、このアサーションは返り値として処理待ち用のオブジェクトを返します。実行したい処理が処理待ちを伴う場合に利用できます。

var manager = {
    tasks : [],
    func  : loadAndParse,
    timer : null,
    start : function() {
      this.timer = window.setInterval(function(aSelf) {
          if (!aSelf.tasks.length) {
            window.clearInterval(aSelf.timer);
            return;
          }
          aSelf.func(aSelf.tasks.shift());
        }, 10, this);
    }
  };
manager.tasks.push('http://www.example.com/');
manager.tasks.push('http://www.example.jp/');
manager.tasks.push('http://www.example.net/');

utils.wait(assert.finishesWithin(
    10 * 1000, // 10sec.
    function() {
      manager.start();
      while (manager.tasks.length) {
        utils.wait(100);
      }
    },
    {}
  ));
Object assert.finishesOver(in Number aExpectedTime, in Function aTestTask, in Object aScope, [in String aMessage]) 別名:assert.finishOver(), assertFinishOver(), assert.notFinishesWithin(), assert.notFinishWithin(), assertNotFinishWithin()

一定以上の時間が経過した後で処理が完了することが期待される場面で使用します。第2引数として渡された関数を、第3引数の値をスコープとして実行し、処理を完了するまでに第1引数で指定された時間(単位:ミリ秒)を要しなかった場合はAssertionFailed例外を発生させます。

function doWait(aTimeout) {
  ...
}
assert.finishesOver(
  5 * 1000, // 5sec.
  function() {
    doWait(5);
  }
);

また、このアサーションは返り値として処理待ち用のオブジェクトを返します。実行したい処理が処理待ちを伴う場合に利用できます。

アサーション数の確認

Object assert.assertionsCountEquals(in Number aExpectedCount, in Function aTestTask, in Object aScope, [in String aMessage]) 別名:assert.assertionsCountEqual(), assertAssertionsCountEqual()

assertionsプロパティによるアサーション数の明示の局所版です。

テスト仕様やデータ数により、特定の回数のアサーションが行われることが期待される場面で使用します。第2引数として渡された関数を、第3引数の値をスコープとして実行します。その上で、第1引数で指定された回数のアサーションが実行されなかった場合はAssertionFailed例外を発生させます。

assert.assertionsCountEquals(
  2,
  function() {
    assert.isNotNull(value);
    assert.isFunction(value);
  },
  {}
);

また、このアサーションは返り値として処理待ち用のオブジェクトを返します。実行したい処理が処理待ちを伴う場合に利用できます。

utils.wait(assert.assertionsCountEquals(
    10,
    function() {
      assert.isNotNull(value);
      utils.wait(500);
      assert.isFunction(value);
    },
    {}
  ));
Object assert.assertionsMinCount(in Number aExpectedMinCount, in Function aTestTask, in Object aScope, [in String aMessage]) 別名:assert.assertionsMinCount(), assertAssertionsMinCount()

minAssertionsプロパティによるアサーション回数の明示の局所版です。

テスト仕様やデータ数により、特定の回数以上のアサーションが行われることが期待される場面で使用します。第2引数として渡された関数を、第3引数の値をスコープとして実行します。その上で、第1引数で指定された回数未満のアサーションしか実行されなかった場合はAssertionFailed例外を発生させます。

assert.assertionsMinCount(
  2,
  function() {
    myCustomAssertion(value); // includes 2 or more assertions
  },
  {}
);

また、このアサーションは返り値として処理待ち用のオブジェクトを返します。実行したい処理が処理待ちを伴う場合に利用できます。

utils.wait(assert.assertionsCountEquals(
    10,
    function() {
      utils.wait(myCustomAssertion(value));
    },
    {}
  ));
Object assert.assertionsMaxCount(in Number aExpectedMaxCount, in Function aTestTask, in Object aScope, [in String aMessage]) 別名:assert.assertionsMaxCount(), assertAssertionsMaxCount()

maxAssertionsプロパティによるアサーション回数の明示の局所版です。

テスト仕様やデータ数により、特定の回数以下のアサーションが行われることが期待される場面で使用します。第2引数として渡された関数を、第3引数の値をスコープとして実行します。その上で、第1引数で指定された回数より多くアサーションが実行された場合はAssertionFailed例外を発生させます。

assert.assertionsMinCount(
  2,
  function() {
    myCustomAssertion(value); // includes 2 or less assertions
  },
  {}
);

また、このアサーションは返り値として処理待ち用のオブジェクトを返します。実行したい処理が処理待ちを伴う場合に利用できます。

utils.wait(assert.assertionsCountEquals(
    10,
    function() {
      utils.wait(myCustomAssertion(value));
    },
    {}
  ));

正規表現によるマッチング

void assert.matches(in RegExp aExpected, in String aActual, [in String aMessage]) 別名:assertMatch()

特定のパターンの文字列が期待される場面で使用します。第2引数の値が第1引数の正規表現に期待に反してマッチしなかった場合はAssertionFailed例外を発生させます。

assert.matches(/^(success|skip)$/i, module.result);
assert.matches(/https?:\/\//, module.message);
void assert.notMatches(in RegExp aUnexpected, in String aActual, [in String aMessage]) 別名:assertNotMatch()

特定のパターンでない文字列が期待される場面で使用します。第2引数の値が第1引数の正規表現に期待に反してマッチした場合はAssertionFailed例外を発生させます。

assert.notMatches(/^(failure|error)$/i, module.result);
assert.notMatches(/(ftp|nntp):/, module.message);
void assert.pattern(in String aExpected, in RegExp aActual, [in String aMessage]) 別名:assertPattern()

特定のパターンの正規表現が期待される場面で使用します。第2引数の値(正規表現)が第1引数として与えられた文字列に期待に反してマッチしない場合はAssertionFailed例外を発生させます。

var regexp = module.mailAddressRegExp;
assert.pattern('test@example.com', regexp);
assert.pattern('My Name <test@example.com>', regexp);
void assert.notPattern(in String aUnexpected, in RegExp aActual, [in String aMessage]) 別名:assertNotPattern()

特定のパターンの正規表現が期待されない場面で使用します。第2引数の値(正規表現)がが第1引数として与えられた文字列に期待に反してマッチする場合はAssertionFailed例外を発生させます。

var regexp = module.mailAddressRegExp;
assert.notPattern('foobar@', regexp);
assert.notPattern('My Name (test at example.com)', regexp);

アサーションのその他の機能

すべてのアサーションは、追加の引数として例外発生時に表示するメッセージを指定できます。スタックトレース以外で例外が発生した時の詳しい状況を知る必要がある場合などに利用できます。

また、以下のようにしてカスタムアサーションを定義することもできます。

assert.isOK = function(aActualValue) {
  var expected = 'OK';
  assert.equals(expected, aActualValue);
}