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

   1 What is it?
   2 ===========
   3
   4 JSUnit is intended to aid in testing the structure of the HTML
   5 document generated by ASP.Net, as well as to test behavior of scripted
   6 elements on webpages (like the client side scripting aspects of
   7 ASP.Net validators.)
   8
   9 It's syntax is meant to resemble that of NUnit as much as possible, so
  10 moving from one to the other shouldn't require too much effort to
  11 understand.  There is some boilerplate, but the syntax for writing
  12 tests is largely the same.  Here is an example test script:
  13
  14 <script Language="JavaScript">
  15     var TestFixture = {
  16         Example_Test1 : function () {
  17                 Assert.IsTrue (true, "true test");
  18         },
  19
  20         Example_Test2 : function () {
  21                 Assert.AreEqual ("hi there", "hi" + " there", "JS string concat");
  22         }
  23     };
  24 </script>
  25
  26 Your tests must be written in the above manner, as properties of
  27 variable called "TestFixture".  JSUnit will call each of your tests
  28 automatically.  As you can see, as in NUnit "Assert." is used as a
  29 prefix for all of your test assertions.
  30
  31
  32 Assert syntax
  33 =============
  34
  35 JSUnit's Assert object has many of the same methods as NUnit's, with a
  36 few differences.  One very important thing to note is when you see an
  37 argument called "expr", it is evaluated as javascript, so you can
  38 include code to query attributes, set attributes, do just about
  39 anything you want.  This gets evaluated as part of your assertion, and
  40 any errors are treated as test failures.
  41
  42 Here is a complete list of Assert's methods:
  43
  44 IsTrue(expr, msg)
  45         if @expr evaluates to false, the test fails.
  46
  47 IsFalse(expr, msg)
  48         if @expr does not evaluate to false, the test fails.
  49
  50 IsNull(expr, msg)
  51         if @expr is not null, the test fails.
  52
  53 NotNull(expr, msg)
  54         if @expr is null, the test fails.
  55
  56 AreEqual(expected, expr, msg)
  57         if @expected and @expr (after evaluation) do not equal, the
  58         test fails.
  59
  60 AreEqualCase(expected, expr, msg);
  61         Same as AreEqual, only case insensitive.
  62
  63 NotEqual(expected, expr, msg);
  64         if @expected and @expr (after evaluation) are equal, the test
  65         fails.
  66
  67 IsFunction(expr, msg);
  68         if @expr evaluates such that the javascript type is not
  69         'function', the test fails.
  70
  71 AttributeHasValue(expected, attr, msg)
  72         if the value of the attribute @attr of the bound element does
  73         not equal @expected, the test fails.  More on "the bound
  74         element below."
  75
  76
  77 Utility Functions
  78 =================
  79
  80 JSUnit has a number of functions that are available from within your
  81 test scripts to help make writing test assertions less painful.
  82
  83 JSUnit_BindElement(elementid);
  84         sets the bound element for the currently running test to
  85         document.getElementById(@elementid).
  86
  87 JSUnit_GetElement([elementid]);
  88         if @elementid is present, looks up the element using
  89         document.getElementById.  otherwise it returns the bound
  90         element.
  91
  92 JSUnit_GetAttribute(attrname[, elementid]);
  93         if @elementid is present, looks up the attribute named
  94         @attrname on that element.  otherwise does the lookup on the
  95         bound element.
  96
  97 JSUnit_Click(element);
  98         Causes the browser to react as if the user had clicked on
  99         element.  @element can be any html element with a click()
 100         method, an onClick handler, or an href attribute.
 101
 102 JSUnit_TestCausesPageLoad();
 103         a special function to let JSUnit know that at some point
 104         during the running of the current test, a page load will
 105         happen, be it from a form submit, calling .load, setting
 106         document.src, whatever.  Special care is needed when writing
 107         tests that cause page loads.  See below.
 108
 109
 110
 111 Tests that cause page loads
 112 ===========================
 113
 114 While testing asp.net validators, we needed to be able to cause page
 115 loads to happen and write tests based on the resulting html.  This is
 116 usually done by creating an asp:button in the form on the test page
 117 and calling "JSUnit_Click()" as part of the test.
 118
 119 Once this method has been called, no further assertions can be made
 120 about the state of the page.  the JSUnit_Click() call (or whatever
 121 mechanism you use to load a new page) should be the last thing in that
 122 test.  The JSUnit machinery will wait for the page to fully load and
 123 then continue on through the list of tests in the current TextFixture.
 124 This means you need to write page load tests split into two parts,
 125 like so:
 126
 127 ------
 128
 129    .
 130    .
 131    .
 132   TestBeforeLoad: function () {
 133         var button = JSUnit_GetElement ("formsubmitbutton");
 134
 135         /* this function causes a page load.  Let JSUnit know. */
 136         JSUnit_TestCausesPageLoad ();
 137
 138         /* assertions about current state of page here */
 139
 140         /* a submit button click  nothing else after this call */
 141         JSUnit_Click (button);
 142   },
 143
 144   TestAfterLoad: function () {
 145         /* assertions about the state of the page after the load has
 146            completed */
 147   }
 148   .
 149   .
 150   .
 151
 152 ------
 153
 154 Telling jsunit about your tests
 155 ===============================
 156
 157 The following is how you build up your test page:
 158
 159 ------
 160     <head>
 161       <script language="JavaScript" src="../jsunit/jsunit.js"></script>
 162
 163       <script language="JavaScript">
 164
 165       var JSUnit_TestPages = [
 166             { url:"http://www.mywebsite.com/", script:"test-script.html" },
 167             { url:"combined-test.html" },
 168       ];
 169
 170       </script>
 171
 172     </head>
 173
 174     <frameset onload="JSUnit_OnLoad()" rows="*,1,1" border=0>
 175     <frame id="test-results" src="../jsunit/jsunit-results.html"/>
 176     <frame id="test-run" src="about:blank"/>
 177     <frame id="test-scripts" src="about:blank"/>
 178     </frameset>
 179 ------
 180
 181 Pretty much the only thing you should change is the list of test
 182 pages, the variable JSUnit_TestPages.  Note the two tests listed in
 183 the example.  One specifies both a test url and script file, and the
 184 other just a url.  The first instance is useful for testing remote
 185 servers, or where you're testing html that you don't want to mark up
 186 with tests.  The second instance is useful when writing small unit
 187 tests, where you want to keep the html and javascript together.
 188
 189 Including tests inside the html
 190 ===============================
 191
 192 For tests such as the second one in the example above, you embed your
 193 tests directly in the html along with the content you're testing, like
 194 so:
 195
 196 <html>
 197 <body>
 198   Hi, this is a combined JSUnit test.
 199
 200   ...
 201
 202   <script Language="JavaScript">
 203       var TestFixture = {
 204         ...
 205       };
 206   </script>
 207 </body>
 208 </html>