The Assert.jsm JavaScript code module implements the CommonJS Unit Testing specification version 1.1, which provides a basic, standardized interface for performing in-code logical assertions with optional, customizable error reporting. To use it, you first need to import the code module into your JavaScript scope:
Components.utils.import("resource://testing-common/Assert.jsm");
The Assert class offers methods for performing common logical assertions.
Method overview
undefined ok(value, message); |
undefined equal(actual, expected, message); |
undefined notEqual(actual, expected, message); |
undefined deepEqual(actual, expected, message); |
undefined notDeepEqual(actual, expected, message); |
undefined strictEqual(actual, expected, message); |
undefined notStrictEqual(actual, expected, message); |
undefined throws(block, expected, message); |
undefined rejects(promise, expected, message); |
undefined greater(lhs, rhs, message); |
undefined greaterOrEqual(lhs, rhs, message); |
undefined less(lhs, rhs, message); |
undefined lessOrEqual(lhs, rhs, message); |
undefined setReporter(reporterFunc); |
undefined report(failed, actual, expected, message, operator); |
Constructor
Creates a new Assert object.
let assert = new Assert(reporterFunc);
The new Assert instance, assert, uses reporterFunc to report assertion results or throws an AssertionError when an assertion fails, as default behavior.
ok, equal, notEqual, deepEqual, notDeepEqual, strictEqual, notStrictEqual, throws, setReporter, report
Methods
ok()
Pure assertion tests whether a value is truthy, as determined by !!guard.
This statement is equivalent to assert.equal(true, !!guard, message_opt);. To test strictly for the value true, use assert.strictEqual(true, guard, message_opt);.
undefined ok( actual, message );
Parameters
actual- Test subject to be evaluated as truthy
message- Short explanation of the expected result
equal()
The equality assertion tests shallow, coercive equality with ==.
undefined equal( actual, expected, message );
Parameters
actual- Test subject to be evaluated as equivalent to
expected expected- Test reference to evaluate against
actual message- Short explanation of the expected result
notEqual()
The non-equality assertion tests for whether two objects are not equal with !=.
undefined notEqual( actual, expected, message );
Parameters
actual- Test subject to be evaluated as not equivalent to
expected expected- Test reference to evaluate against
actual message- Short explanation of the expected result
deepEqual()
The equivalence assertion tests a deep equality relation.
We check using the most exact approximation of equality between two objects to keep the chance of false positives to a minimum.
JSON.stringify is not designed to be used for this purpose; objects may have ambiguous toJSON() implementations that would influence the test.
undefined deepEqual( actual, expected, message );
Parameters
actual- Test subject to be evaluated as equivalent to
expected, including nested properties expected- Test reference to evaluate against
actual message- Short explanation of the expected result
notDeepEqual()
The non-equivalence assertion tests for any deep inequality.
undefined notDeepEqual( actual, expected, message );
Parameters
actual- Test subject to be evaluated as not equivalent to
expected, including nested properties expected- Test reference to evaluate against
actual message- Short explanation of the expected result
strictEqual()
The strict equality assertion tests strict equality, as determined by ===.
undefined strictEqual( actual, expected, message );
Parameters
actual- Test subject to be evaluated as strictly equivalent to
expected expected- Test reference to evaluate against
actual message- Short explanation of the expected result
notStrictEqual()
The strict non-equality assertion tests for strict inequality, as determined by !==.
undefined notStrictEqual( actual, expected, message );
Parameters
actual- Test subject to be evaluated as not strictly equivalent to
expected expected- Test reference to evaluate against
actual message- Short explanation of the expected result
throws()
Expected to throw an error.
undefined throws( block, expected, message );
Parameters
block- Function block to evaluate and catch eventual thrown errors
expected- Test reference to evaluate against the thrown result from
block message- Short explanation of the expected result
rejects()
Expected to reject a promise.
undefined rejects( promise, expected, message );
Parameters
promise- Promise promise to wait for rejection and catch eventual thrown errors
expected- Test reference to evaluate against the thrown result from
block message- Short explanation of the expected result
greater()
The greater than assertion tests two numbers with the > operator.
undefined greater( lhs, rhs, message );
Parameters
lhs- The left hand side of the operator
rhs- The right hand side of the operator
message- Short explanation of the expected result
greaterOrEqual()
The greater or equal than assertion tests two numbers with the >= operator.
undefined greaterOrEqual( lhs, rhs, message );
Parameters
lhs- The left hand side of the operator
rhs- The right hand side of the operator
message- Short explanation of the expected result
less()
The lesser than assertion tests two numbers with the < operator.
undefined less( lhs, rhs, message );
Parameters
lhs- The left hand side of the operator
rhs- The right hand side of the operator
message- Short explanation of the expected result
lessOrEqual()
The lesser or equal than assertion tests two numbers with the <= operator.
undefined lessOrEqual( lhs, rhs, message );
Parameters
lhs- The left hand side of the operator
rhs- The right hand side of the operator
message- Short explanation of the expected result
setReporter()
Set a custom assertion report handler function.
undefined setReporter( reporterFunc );
Parameters
reporterFunc- Reporter handler function.
Arguments passed in to this function are:err- An error object when the assertion failed or null when it passed
message- Message describing the assertion
stack- Stack trace of the assertion function.
report()
All of the aforementioned functions must throw an AssertionError when a corresponding condition is not met, with a message that may be undefined if not provided.
All assertion methods provide both the actual and expected values to the assertion error for display purposes.
This report method only throws errors on assertion failures, as per spec, but consumers of this module (think: xpcshell-test, mochitest) may want to override this default implementation.
undefined report( failed, actual, expected, message, operator );
Parameters
failed- Indicates if the assertion failed or not
actual- The result of evaluating the assertion
expected- Expected result from the test author
message- Short explanation of the expected result
operator- Operation qualifier used by the assertion method (ex: '==')
Examples
Custom reporter example
Components.utils.import("resource://testing-common/Assert.jsm");
let assert = new Assert();
assert.setReporter(function customReporter(err, message, stack) {
if (err) {
do_report_result(false, err.message, err.stack);
} else {
do_report_result(true, message, stack);
}
});