Global variables
Two global variables are declared to execute the assertion tests : __ASSERT__ and __ARGUMENT__.
So, you MUST NOT have variables with these names declared in the scripts being tested otherwise they will conflict with these global variables.
__ASSERT__ methods
The global
__ASSERT__ object exposes a full set of testing methods:
isTrue
Returns true if its argument is true
isFalse
Returns true if its argument is false
isNull
Returns true if its argument is null
isNotNull
Returns true if its argument is not null
isUndefined
Returns true if its argument is undefined
isNotUndefined
Returns true if its argument is defined
isNumber
Returns true if its argument is a number
isNotNumber
Returns true if its argument is not a number
isEqual
Returns true if its first argument and ist second argument are equal
isNotEqual
Returns true if its first argument and ist second argument are not equal
warn
Output the content of its argument with a WARNING header
We've done our best to provide a kind of polymorphism mechanism for these methods.
This key concept of the Object Oriented technology, is not actually implemented in JavaScript, but it can be "emulated". Basically, this mechanism allows you to call a method with a variable number and type of arguments, thus giving each method different possible signatures.
For checking and computing methods (
isTrue up to
isNotNumber), the possible signatures are:
(argument)
(argument, testing)
(argument, comment)
(argument, testing, comment)
where
argument is the argument to test,
testing is a boolean for really executing the test and
comment is a message to output in the assertion report.
For comparing methods (
isEqual,
isNotEqual), the possible signatures are:
(argument1, argument2)
(argument1, argument2, testing)
(argument1, argument2, comment)
(argument, argument, testing, comment)
where
argument1 and
argument2 are the arguments to compare,
testing is a boolean for really executing the test and
comment is a message to output in the assertion report.
__ARGUMENT__ methods
The global
__ARGUMENT__ object exposes a full set of testing methods:
isNumber
Returns true if the type of its argument is Number
isString
Returns true if the type of its argument is String
isNull
Returns true if its argument is null
isBoolean
Returns true if its argument is a boolean value
isArray
Returns true if the type of its argument is Array
isObject
Returns true if the type of its argument is Object
isEmpty
Returns true if its argument is an empty array or object
All these methods have only one signature:
where
argument is the argument to test.
Using assertions
The possibility to conditionally check an assertion is a key feature of the unit testing framework provided by JS Console.
First, you can define a global constant to decide whether assertion checks are to be done. Thus, once your code is right, you're not obliged to remove every assertion instruction. They can stay in line, waiting for future code improvements; they only add a very light processing overhead. All you have to do is to give your global constant a false value to skip the checks.
Second, you can chain assertions: every assertion check returns a true or false boolean value (true if assertion succeeds, false if it fails). This way you can check an assertion according to the result of a previous assertion.
For instance:
var assertResult = __ASSERT__.isTrue(expressionToTest, true);
__ASSERT__.isTrue(anotherExpressionToTest, assertResult);
Third, and it may be the most important trick for those using alert boxes to track bugs in their code, you can do assertion in loops, just affecting the checking condition argument with any boolean expression involving some "hot" value of your looping variable. For example:
var stringArray = ['primo', 'secondo', 'tertio'];
for(var i = 0, m = stringArray.length;i < m; i++){
__ASSERT__.isEqual('primo', stringArray[i], i == 0);
__ASSERT__.isEqual('tertio', stringArray[i], i == (m - 1));
}
When faced with complex looping logic (not as in our simplistic example), this conditional checking ability is crucial, as it allows you to test only sensitive steps or to list, using a warning assertion, the output of the variables included in your loop.
Of course, you can combine these different logics and, for instance, execute the assertion checking in a loop only for a certain value of the loop counter and if a global assertion checking variable is set. It's only a matter of conditional test expression and it can be quite complex if you wish.
One thing to strictly observe to take advantage of the polymorphism mechanism, is that your checking condition MUST be a boolean variable, not a string variable. A string variable will be evaluated as an assertion comment.
JS Console unit testing framework conforms to the ECMA Script 1.0 variable typing : tests use equality operators (== and !=), not the identity operators (=== and !==).
So : null and undefined are equal but not equal to 0, empty string or false.
Empty string or array are considered number (0) as they evaluate to false (false and true are converted to 0 and 1).
Assertion samples
Samples of all types of assertion can be found in two files, coretest.js and signaturetest.js, included in the mozlib package, located in the MOZILLA_INSTALL_DIR/chrome/mozlib/content/lib/js/assert/test/ directory.
You can load them in the Code panel to run them.
Use the context menu to navigate in the documentation pages