h1. Dr Nic's JavaScript Test Helpers
 
h2. What
 
This JavaScript project provides help for unit testing other JavaScript projects:
 
* <code>Event.simulate('element', 'eventName')</code>
* <code>Ajax.Request</code> mocking (for "Prototypejs":http://www.prototypejs.org/ based projects)
* Extra test case assertions (assertDifference, assertNoDifference)
 
h2. Downloading
 
Latest version: <a href="dist/drnic_js_test_helpers.js">drnic_js_test_helpers.js</a>
 
Alternately, to get the complete project source go to the "downloads":http://rubyforge.org/frs/?group_id=2351&release_id=19240
page on rubyforge.org, or by clicking on "Get Version" badge above and clicking
through to "drnic_js_test_helpers".
 
Save the file within your JavaScript project, say in <code>test/assets</code>,
and link to it from your HTML test files.
 
h2. Setup/installation
 
This library is for use within unittest.js related HTML test files. If your test HTML
files are in <code>test/</code> and the library is saved at
<code>test/assets/drnic_js_test_helpers.js</code>, then within the &lt;head&gt;
of each HTML test file add:
 
<pre syntax="html">
<script src="assets/drnic_js_test_helpers.js" type="text/javascript"></script>  
</pre>
 
h2. Demonstration of usage
 
This library currently offers some helpers:
 
* Event simulation - simulating mouse events (click, mouseover, etc), or HTML events (change, etc)
* Ajax request mocking - no Ajax requests available during unit testing, so mock them out
* Extra test assertions - bonus assertXXX methods for unittest.js
 
h3. Event simulation
 
<pre syntax="javascript">Event.simulate('element', 'eventName')</pre>
 
 
h3. Ajax request mocking
 
<code>Ajax.Request</code> mocking (for "Prototypejs":http://www.prototypejs.org/ based projects)
 
Within your test or setup method:
 
<pre syntax="javascript">Ajax.Request.setupMock('/some/url', function(request, response) {
  response.responseJSON = "{data: 123}";
  request.options.onComplete(response);
});</pre>
 
Now, during your test if <code>new Ajax.Request('/some/url', {onComplete: function() {...}})</code> 
is called, then the <code>onComplete</code> callback will be invoked, 
and <code>responseJSON</code> will have a mocked out value.
 
Within your teardown method it is advisable to clear the mocks, thus each test needs to setup the mock it requires:
 
<pre>teardown: function() {
  Ajax.Request.clearMocks();
},
</pre>
 
The <code>clearMocks</code> call is to restore the Ajax mechanism; which is used
when you run tests via <code>rake test</code> to communicate the test results back
to the command-line test server. If <code>rake test</code> is hanging, it is 
likely you are not calling <code>clearMocks</code> in your teardown method.
 
h3. Extra assertions
 
Your test cases can use the following additional assertions:
  
* <code>assertDifference(evalStr, block, count)</code>
* <code>assertNoDifference(evalStr, block)</code> - same as <code>assertDifference(evalStr, block, 0)</code>
* <code>assertTagDifference(tag, block, count)</code>
 
For example, if you wanted to test that some code created an additional &gt;div&lt; element
in the DOM, then your test might be:
 
<pre syntax="javascript">
testExtraDiv: function() { with(this) {
  assertDifference("$$('div').length", function() {
    // do something that creates new <div> element
  }, 1, "should not be different");
}},
</pre>
 
There is a primitive selector assertion <code>assertTagDifference</code>:
  
<pre syntax="javascript">assertTagDifference('span', function() {
  var span = document.createElement("span");
  Test.$('sample').appendChild(span);
}, 1);</pre>
 
h2. Other test helpers
 
The protolicious source has some helper files, see "source":http://code.google.com/p/protolicious/source/browse/trunk/
 
h2. Forum
 
"http://groups.google.com/group/drnicutilities":http://groups.google.com/group/drnicutilities
 
 
h2. How to submit patches
 
Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
 
The source project is a "Git":http://git.or.cz/ repository. See Dr Nic's "master branch":http://github.com/drnic/drnic_js_test_helpers/tree/master for clone/checkout details.
 
h2. License
 
This code is free to use under the terms of the MIT license. 
 
h2. Contact
 
Comments are welcome. Send an email to "Dr Nic Williams":mailto:drnicwilliams@gmail.com via the "forum":http://groups.google.com/group/drnicutilities