Quick start
You can use the assertion framework to test your JavaScript code, be it small routines and functions included in your site pages, nice scripts used to monitor some other tools using JavaScript as a scripting utility, or a fine hierarchy of classes ala Java with complex inheritance relationships between a thousand files package.
For that, you only need two lines of code :
const FIRST_ASSERTION = 'JS Console is a nice little tool for cute developers';
__ASSERT__.isTrue(FIRST_ASSERTION);
Run that code and go to the Unit test panel and see... that there is nothing to watch there.
Well, it's better and we hope you'll (almost) never see anything in the Unit test panel. Because, if something is displayed, things are going wrong.
We are going to verify this. So modify our small snippet and append it a few more lines:
const SECOND_ASSERTION = 'JS Console IS NOT a nice little tool for cute developers';
__ASSERT__.isFalse(SECOND_ASSERTION);
Run that code again and go to the Unit test panel.
You see the difference? Now you have lines reporting that your last assertion has failed. Why? Because you wanted to verify that the string constant SECOND_ASSERTION was FALSE. But it isn't false. A non empty string is never false in JavaScript, it's quite true.
Once more, with more informative arguments:
const CHECKING = true;
__ASSERT__.isFalse(SECOND_ASSERTION, CHECKING, 'SECOND_ASSERTION: must be true');
We have now refined the report to indicate in what function the assertion was made and added a boolean constant (CHECKING) to control the assertion checking (should have we put a false value instead of this true one, the assertion would then have been skipped).
All that magic
But what does all that magic mean? Actually it's quite simple:
__ASSERT__ is global object, an instance of the class ASSERT_Tester.
isFalse is a method of that instance whose role is to test whether its first argument (here, SECOND_ASSERTION constant) is a boolean false value.
The first argument is what has to be checked: here, for the isFalse method, the assertion will success only if this argument evaluates to false, but this assertion will trigger a failure if the argument is true (it's a false method, isn't it?).
The second argument is evaluated as a boolean expression to indicate whether the assertion has to be actually checked. So you can localy or globaly enable the checking of any assertion embeded in your scripts.
And the third argument is a comment of your choice, here used to link the information reported by the assertion reporter with your code. The convention is to separate this comment in two parts : the first part is the name of the function containing your assertion, the second part is a true comment to give a quick explanation displayed in the reporter window when the assertion fails. Those two parts are separated by a colon.
But only the first argument is mandatory, the remaining arguments are optional.
It's so good
You understand now the basic principle of unit testing and the way JS Console assertion framework apply it: when you want to be sure that a variable in your script contains really the value it is supposed to contain at runtime, assert that value. If it's right, no problem: everything is transparent and the program runs quietly (and don't be affraid of the overhead, this check takes only a few cycles of your speedy 4GHz new XXX processor).
But if this assertion is false, because may be you forgot to initialize a variable, or you're not yet sure of the value it can take at that instant, then the assertion framework alerts you that you're wrong. It doesn't hurt your script, it doesn't stop it, it runs as quietly as before (unless your wrong assertion throws a fatal exception which stops the JavaScript interpreter). But now, you know it's not so quiet, and why, and where.
You've just won ten or twenty minutes of debugging, avoiding its awfully cluttering code of alert boxes, trying to trap the error.
Not yet convinced? Then, please go to one of the pages where you'll find stories, theories and use cases about programming according to the Test First Design methodology, for instance, this
introduction or this full
description. The principles are quite limpid and astonishing.
Then practice one or two days writing a few scripts and functions using assertions. I'm sure you'll quickly come back here.
We must however admit that just TRUE or FALSE would make a very poor tool to deploy a true assertion testing method.
So the assertion framework provides more testing logic: is this variable null or not null, defined or undefined, is it truly a number or not, does it equal another variable or not...
With this small panoply of tests you can quickly build some pretty useful evaluation or your script behaviour.
And, if it's not enough, try the warn function to send directly in the reporter panel the content of your variables (without beeing disturbed by an interminable chain of alert boxes supposed to inform you upon the state of your script).
Round about jUnit
Some remarks for those who already know
jUnit: JS Console assertion framework has a very different behaviour, because it's used to test JavaScript code which, most of the time is embedded in web pages as to react to visitor input (a click on a button, an entry in a form dialog, etc.).
The jUnit model is not adapted to this kind of behaviour: it has been design to statically check Java classes instances.
On the contrary, JS Console assertion framework has been design to catch these dynamic situations, so it runs in a separate panel, without disturbing the main window beeing tested.
But you can easily adapt it to be run in a "batch" mode as jUnit do: just put all your assertions inside a function and call that function from a specific script. To get a fine report after this call, just put a call to the warn method as the last assertion and it's done: you know how many assertions where checked, etc.
One major advantage of the assertion framework running in a separate panel is that you can save the content of that panel every time you want, to have a snapshot of your tests.
This is really very useful, as the content of the files you save can easily be parsed to extract the informations (thru an XSLT script for instance) and put in database for later comparaisons.
Use the context menu to navigate in the documentation pages