mono/mcs/class/System.Web/Test/jsunit/README

What is it?
===========

JSUnit is intended to aid in testing the structure of the HTML
document generated by ASP.Net, as well as to test behavior of scripted
elements on webpages (like the client side scripting aspects of
ASP.Net validators.)

It's syntax is meant to resemble that of NUnit as much as possible, so
moving from one to the other shouldn't require too much effort to
understand.  There is some boilerplate, but the syntax for writing
tests is largely the same.  Here is an example test script:

<script Language="JavaScript">
    var TestFixture = {
	Example_Test1 : function () {
		Assert.IsTrue (true, "true test");
	},

	Example_Test2 : function () {
		Assert.AreEqual ("hi there", "hi" + " there", "JS string concat");
	}
    };
</script>

Your tests must be written in the above manner, as properties of
variable called "TestFixture".  JSUnit will call each of your tests
automatically.  As you can see, as in NUnit "Assert." is used as a
prefix for all of your test assertions.


Assert syntax
=============

JSUnit's Assert object has many of the same methods as NUnit's, with a
few differences.  One very important thing to note is when you see an
argument called "expr", it is evaluated as javascript, so you can
include code to query attributes, set attributes, do just about
anything you want.  This gets evaluated as part of your assertion, and
any errors are treated as test failures.

Here is a complete list of Assert's methods:

IsTrue(expr, msg)
	if @expr evaluates to false, the test fails.

IsFalse(expr, msg)
	if @expr does not evaluate to false, the test fails.

IsNull(expr, msg)
	if @expr is not null, the test fails.

NotNull(expr, msg)
	if @expr is null, the test fails.

AreEqual(expected, expr, msg)
	if @expected and @expr (after evaluation) do not equal, the
	test fails.

AreEqualCase(expected, expr, msg);
	Same as AreEqual, only case insensitive.

NotEqual(expected, expr, msg);
	if @expected and @expr (after evaluation) are equal, the test
	fails.

IsFunction(expr, msg);
	if @expr evaluates such that the javascript type is not
	'function', the test fails.

AttributeHasValue(expected, attr, msg)
	if the value of the attribute @attr of the bound element does
	not equal @expected, the test fails.  More on "the bound
	element below."


Utility Functions
=================

JSUnit has a number of functions that are available from within your
test scripts to help make writing test assertions less painful.

JSUnit_BindElement(elementid);
	sets the bound element for the currently running test to
	document.getElementById(@elementid).

JSUnit_GetElement([elementid]);
	if @elementid is present, looks up the element using
	document.getElementById.  otherwise it returns the bound
	element.

JSUnit_GetAttribute(attrname[, elementid]);
	if @elementid is present, looks up the attribute named
	@attrname on that element.  otherwise does the lookup on the
	bound element.

JSUnit_Click(element);
	Causes the browser to react as if the user had clicked on
        element.  @element can be any html element with a click()
	method, an onClick handler, or an href attribute.

JSUnit_TestCausesPageLoad();
	a special function to let JSUnit know that at some point
	during the running of the current test, a page load will
	happen, be it from a form submit, calling .load, setting
	document.src, whatever.  Special care is needed when writing
	tests that cause page loads.  See below.



Tests that cause page loads
===========================

While testing asp.net validators, we needed to be able to cause page
loads to happen and write tests based on the resulting html.  This is
usually done by creating an asp:button in the form on the test page
and calling "JSUnit_Click()" as part of the test.

Once this method has been called, no further assertions can be made
about the state of the page.  the JSUnit_Click() call (or whatever
mechanism you use to load a new page) should be the last thing in that
test.  The JSUnit machinery will wait for the page to fully load and
then continue on through the list of tests in the current TextFixture.
This means you need to write page load tests split into two parts,
like so:

------

   .
   .
   .
  TestBeforeLoad: function () {
	var button = JSUnit_GetElement ("formsubmitbutton");

	/* this function causes a page load.  Let JSUnit know. */
	JSUnit_TestCausesPageLoad ();

	/* assertions about current state of page here */

	/* a submit button click  nothing else after this call */
	JSUnit_Click (button);
  },

  TestAfterLoad: function () {
	/* assertions about the state of the page after the load has
	   completed */
  }
  .
  .
  .

------

Telling jsunit about your tests
===============================

The following is how you build up your test page:

------
    <head>
      <script language="JavaScript" src="../jsunit/jsunit.js"></script>

      <script language="JavaScript">

      var JSUnit_TestPages = [
            { url:"http://www.mywebsite.com/", script:"test-script.html" },
            { url:"combined-test.html" },
      ];

      </script>

    </head>

    <frameset onload="JSUnit_OnLoad()" rows="*,1,1" border=0>
    <frame id="test-results" src="../jsunit/jsunit-results.html"/>
    <frame id="test-run" src="about:blank"/>
    <frame id="test-scripts" src="about:blank"/>
    </frameset>
------

Pretty much the only thing you should change is the list of test
pages, the variable JSUnit_TestPages.  Note the two tests listed in
the example.  One specifies both a test url and script file, and the
other just a url.  The first instance is useful for testing remote
servers, or where you're testing html that you don't want to mark up
with tests.  The second instance is useful when writing small unit
tests, where you want to keep the html and javascript together.

Including tests inside the html
===============================

For tests such as the second one in the example above, you embed your
tests directly in the html along with the content you're testing, like
so:

<html>
<body>
  Hi, this is a combined JSUnit test.

  ...

  <script Language="JavaScript">
      var TestFixture = {
	...
      };
  </script>
</body>
</html>