I'm in the mood for JavaScript

So you want to use jsAsserUnit 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?
Very easy, only three lines of script to be in the mood :

<script language="JavaScript" src="assert.js"></script>

That's the usual tag to include the core script file of jsAsserUnit (of course, we suppose that file located in the same directory as jsAsserUnit, otherwise, adapt the path).
Then go on with:

<script language="JavaScript">
var myFirstAssertion = 'jsAsserUnit is a nice little tool for the cute developers';
Assert.isTrue(myFirstAssertion);
</script>

and include these lines in your favorite HTML page (either directly or thru a script link tag) and open it in your browser (please don't be silly, use one of those generation 5 browsers like Mozilla 0.9, Explorer 5/6 or Netscape 6, otherwise, jsAssertUnit won't work). OK? It's done.
That's all, you've just used successfully jsAsserUnit for the first time.
What? You even didn't notice the smallest flickering of your screen? What kind of tool is this? I don't see it work.
You're right. And we hope you'll (almost) never see the jsAsserUnit reporter screen. Because, if you see it, things are going wrong.

Want to verify?
Let's modify our wonderfull script and append it a few more lines:

<script language="JavaScript">
var mySecondAssertion = 'jsAsserUnit is __NOT__ a nice little tool for the cute developers';
Assert.isFalse(mySecondAssertion);
</script>

Load the script again in your browser.
Eh, you! You're not right, my Dear, I don't agree with your assertion!
You see why now? That damned tool has just reported that you're wrong when you assert that 'jsAsserUnit is __NOT__ a nice little tool for the cute developers'. Why? Because you wanted to verify that the string variable mySecondAssertion was FALSE. But it isn't. A non empty string is never false in JavaScript, it's quite TRUE.

Once more, with more informative arguments

<script language="JavaScript">
var TEST_THIS_ASSERTION = true;
Assert.isFalse(mySecondAssertion,
	TEST_THIS_ASSERTION,
	'mySecond_jsAsserUnit_Test:mySecondAssertion seems to be true');
Assert.isFalse(mySecondAssertion);
</script>

Fine, we have now refined the report to indicate in what function the assertion was made and added a boolean variable (TEST_THIS_ASSERTION) 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, a singleton instance of the class ASSERT_Tester.

Sorry for those without any Java background: if JavaScript is not Java, we do like the Java formalism and apply it as much as we can to write our scripts. That's why jsAssertUnit has classes ala Java (a singleton is class with only a single instance object).

isFalse is a method of that class whose role is to test whether its first argument (here, mySecondAssertion variable) is a boolean false value.
The first argument is what has to be tested: 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 wether the assertion has to be actually checked. So you can locally 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 script 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 have to be separated by a colon.
OO experts will recognize that we gave some overloading behaviour to our assertion tests methods.

It's so good

You understand now the basic principle of unit testing and the way jsAsserUnit apply it: when you want to be sure that a variable in your script contains really the value it is supposed to contain at that very runtime instant, assert that value. If it's correct, 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 2GHz 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 jsAsserUnit 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 mistake.

Convinced? Not yet! It looks like a little sofware gadget to say "yes, it's true, no it's wrong". What can I do with that?
So, 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. The principles are quite limpid and astonishing.
Then practice one or two days to write a few scripts and functions using assertions checked by jsAsserUnit. I'm sure you'll quickly come back here.

We must however admit that just TRUE or FALSE would make a very restricted tool to deploy a true assertion testing method.
So jsAsserUnit provides more testing logic: is this variable null or not null, defined or undefined (that's the question!), is it truly a number or not, does it equal another variable or not...
With these small panoply of tests you can quickly build some pretty usefull evaluation or your script behaviour.
And, if it's not enough, try the warn function to send directly in the reporter window 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: jsAssertUnit has a very different behaviour, because it's used to test JavaScript code which, most of the time is embedded in web pages 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, jsAssertUnit has been design to catch these dynamic situations, so it runs in a browser window, 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 (as we did in the coretest.js sample file). 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 jsAssertUnit running in a browser window is that you can save the content of that window every time you want, to have a snapshot of your tests.
This is really very usefull, 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.
And jsAssertUnit is an open source tool, so if you are an experienced programmer, its code is yours: you can extend any class in the package which could help you to enhance your testing framework.
We only hope you'll give us a few words of feedback or, a very nice decision, to let the community use your smarter tricks.

To have a more formal insight of jsAssertUnit, go to the jsAssertUnit Design page.