Documentation
QUnit
From jQuery JavaScript Library
Contents |
About
QUnit is the unit testrunner for the jQuery project. It got promoted to a top-level project in May 2008 to make it easier to use in other projects, with focus on jQuery UI. Every plugin developer can leverage the testsuite to unit test their code.
It's especially useful for regression testing: Whenever a bug is reported, write a test that asserts the existence of that particular bug. Then fix it and commit both. Every time you work on the code again, run the tests. If the bug comes up again - a regression - you'll spot it immediately and know how to fix it, because you know what code you just changed.
Having good unit test coverage makes safe refactoring easy and cheap. You can run the tests after each small refactoring step and always know what change broke something.
Status
The core QUnit features are extremely stable. The overall API is still a work-in-progress, with some legacy assertions slowly being replaced by more generic methods. There is no stable release, just files in a subversion repository.
Contact
QUnit is maintained by Jörn Zaefferer.
Please post to the jQuery development list (see Discussion) for anything related to QUnit (put QUnit into the subject of your mail).
Using QUnit
To use QUnit, you have to include its js and css files and provide a basic HTML structure for displaying the test results:
test("a basic test example", function() {
ok( true, "this test is fine" );
var value = "hello";
equals( "hello", value, "We expect value to be hello" );
});
module("Module A");
test("first test within module", function() {
ok( true, "all pass" );
});
test("second test within module", function() {
ok( true, "all pass" );
});
module("Module B");
test("some other test", function() {
expect(2);
equals( true, false, "failing test" );
equals( true, true, "passing test" );
});
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<script src="http://code.jquery.com/jquery-latest.js"></script>
<link rel="stylesheet" href="http://dev.jquery.com/view/trunk/qunit/testsuite.css" type="text/css" media="screen" />
<script>
$(document).ready(function(){
test("a basic test example", function() {
ok( true, "this test is fine" );
var value = "hello";
equals( "hello", value, "We expect value to be hello" );
});
module("Module A");
test("first test within module", function() {
ok( true, "all pass" );
});
test("second test within module", function() {
ok( true, "all pass" );
});
module("Module B");
test("some other test", function() {
expect(2);
equals( true, false, "failing test" );
equals( true, true, "passing test" );
});
});
</script>
</head>
<body>
<script type="text/javascript" src="http://jqueryjs.googlecode.com/svn/trunk/qunit/testrunner.js"></script>
<h1>QUnit example</h1>
<h2 id="banner"></h2>
<h2 id="userAgent"></h2>
<ol id="tests"></ol>
<div id="main"></div>
</body>
</html>
API documentation
more coming soon
URL Parameters
You can customize individual testruns via URL paramters. To start, double click on a test to have QUnit only run that single test.
Or add the name of a module to the URL to run only tests within that module, eg jquery.com/test?fx runs only tests for effects. You can combine various filters, eg. ?fx&ajax to run effects and ajax tests.
Another feature is global-variables pollution detection. Add ?noglobals to the URL, and QUnit will detect if a test introduced a new global variable (aka new properties on the window object), making that test fail.
Integration into Browser Automation Tools
To integrate QUnit into browser automation tools, those doing the work of launching various browsers and gathering the results, QUnit provides a simple microformat for its test result.
<p class="result" id="testresult"> Tests completed in 16797 milliseconds.<br/> <span class="bad">0</span> tests of <span class="all">565</span> failed. </p>
Using jQuery, you can read the result:
var r = jQuery("#testresult")
var bad = r.find(".bad").text();
var all = r.find(".all").text();
console.log(bad + " of " + all + " failed.")
Suggestions for better integration are welcome!
Reference testsuites
jQuery itself has the biggest set of tests using QUnit:
The validation plugin got a decent test coverage, too:
Examples from the jQuery UI project: