File:  [mozdev] / xulunit / www / cookbook.html
Revision 1.2: download - view: text, annotated - select for diffs - revision graph
Thu Jan 27 15:29:45 2005 UTC (15 years ago) by mjaque
Branches: MAIN
CVS tags: v0_1, HEAD
Cookbook uploaded

<!-- MAIN CONTENT -->
<h5 class="page-header">Cookbook</h5>

<h1>The Metaphor</h1>
<p>Remember this:</p>
<ul>
<li><b>Tests</b> are assertions made on objects (I.e. variables, functions,
values... or even proper objects). Assertions could be things like <i>"check this variable is not null"</i> or 
<i>"check this value equals this one"</i>.</li>
<li><b>Test Cases</b> are functions (starting with "test_") that, among any
other commands, include some tests (assertions).</li>
<li><b>Test Suites</b> are collection of Test Cases.</li>
<li><b>Test Runner</b> is the Graphical User Interface which can execute some
Test Suites and show their results.</li>
</ul>
<p><u>Easy! Is'nt it?</u></p>

<h1>Some Examples</h1>
<p>This is a test: <pre>assertEquals("A simple test", 36, myAge);</pre></p>
<p>Tests should be included in Test Cases to be run. This is a Test Case:</p>
<pre>
  function test_MyTest(){
    var myAge = 35;
    myAge++;
    assertEquals("A simple test", 36, myAge);
    assertNotNull("Another stupid test", "notNullValue");
  }
</pre>
<p>But, as Test Cases need some more things that just a function (with assertions) we need to instatiate
a TestCase object. This will add result attributes and other jingles to our test function:</p>
<pre>
  myTestCase = new TestCase("This is my Test Case", test_MyTest);
</pre>
<p>Test Cases should be added to Test Suites in order to be run. This is done by:</p>
<pre>
  var myTestSuite =  new TestSuite("TestSuite Name");
  myTestSuite.add(myTestCase);
</pre>
<p>And, in order to run the Suites (and therefore the tests), we need to create
a TestRunner object and add our Test Suites:</p>
<pre>
  var testRunner = new TestRunner();
  testRunner.add(myTestSuite);
</pre>

<p>A complete example of test construction can be found in myTests.js
file (included in the <a href=".../download/xulunit.tar.gz">XulUnit Package</a>).</p>

<h1>How to Run Test Runner</h1>
<p>After creating your tests, test cases, test suites and a test runner object,
you simply need to create a xul page, load any js file with your tests and
classes to be tested, and call TestRunner launch method (with no arguments).</p>
<p>This will open a new window, run the tests and show the results. Thats all.</p>

<h2>For example</h2>
<p>Example at <a href=".../download/xulunit.tar.gz">XulUnit Package</a> myTest.xul includes the following code:</p>
<pre>
  &lt;script src="xulunit.js" /&gt;
  &lt;script src="myTests.js" /&gt;
  &lt;!-- Any other js files with classes --&gt;
</pre>
<p>This loads XulUnit classes and the user defined tests.</p>
<p>To run then, you can use a simple button...</p>
<pre>
      &lt;button label="Run My Tests" onclick="testRunner.launch()"/&gt;
</pre>
<p>You can also call launch method on the onload attribute of your window.</p>

<h1>Assert Functions</h1>
<p>These are the assert functions included in XulUnit:</p>

<p><b>function assert(name, toEval)</b> Asserts toEval expression equals true</b>
<p><b>function assertTrue(name, toEval)</b> Asserts toEval expression equals true.</p>
<p><b>function assertFalse(name, toEval)</b> Asserts toEval expression equals false.</p>
<p><b>function assertEquals(name, value, toEval)</b> Asserts toEval expression equals value.</p>
<p><b>function assertNotEquals(name, value, toEval)</b> Asserts toEval expression does not equals value.</p>
<p><b>function assertNull(name, toEval)</b> Asserts toEval expression is null.</p>
<p><b>function assertNotNull(name, toEval)</b> Asserts toEval expression is not null.</p>
<p><b>function assertUndefined(name, toEval)</b> Asserts toEval expression is undefined.</p>
<p><b>function assertNotUndefined(name, toEval)</b> Asserts toEval expression is not undefined.</p>
<p><b>function assertNaN(name, toEval)</b> Asserts toEval expression is Nan (Not a Number).</p>
<p><b>function assertNotNaN(name, toEval)</b> Asserts toEval expression is not
Nan (Not a Number). I.e. it is a number.</p>
<p><b>function assertRegExp(name, regExp, toEval)</b> To be done.</p>
<p><b>function assertTypeOf(name, type, toEval)</b> To be done.</p>

<h1>Understanding Test Results</h1>
<p>Tests can evaluate to any of four results:</p>
<ul>
<li><b>PASS</b> The assertion is correct.</li>
<li><b>FAIL</b> The assertion is false.</li>
<li><b>BREAK</b> The test did not complete.</li>
<li><b>UNKNOWN</b> The assertion was done in the test.</li>
</ul>
<p>Results follow up to cases and suites with the rule: <i>If all passes, I
pass</i>. This means that a case PASSES only if all its tests passes. And same
aplies to Suites.</p> 
<p>If any of the tests in a case fails, the case will
throw a FAIL result (eventhough you can see the results for each individual
test).</p>
<p>If any of the tests breaks... the case and the suite will break.</p>

<h1>Todo</h1>
<p>I know you can't believe it. But there are still features to be added to
XulUnit (on which I am working hard). The main left are:</p>
<ul>
  <li><b>Fixtures:</b> So you can do some preparation before Suite execution and some cleanning afterwards.</li>
  <li><b>Anidated Suites:</b> For the moment, Suites can only include
  TestCases. In a future release, you will be able to add Suites to other
  Suites making your test organization more flexible.</li>
</ul>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>