Add quick-start documentation for testing with QUnit and using jQuery's helper methods.

9 files changed, 104 insertions, 15 deletions

diff --git a/README.md b/README.md
index ad38c228b..3e0cbf185 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,60 @@ Following are some commands that can be used there:
 * `Ctrl + S` - save
 * `Ctrl + Q` - quit
 
+[QUnit](http://docs.jquery.com/QUnit) Reference
+-----------------
+
+Test methods:
+	expect( numAssertions )
+	stop()
+	start()
+		note: QUnit's eventual addition of an argument to stop/start is ignored in this test suite
+		so that start and stop can be passed as callbacks without worrying about
+			their parameters
+
+Test assertions:
+	ok( value, [message] )
+	equal( actual, expected, [message] )
+	notEqual( actual, expected, [message] )
+	deepEqual( actual, expected, [message] )
+	notDeepEqual( actual, expected, [message] )
+	strictEqual( actual, expected, [message] )
+	notStrictEqual( actual, expected, [message] )
+	raises( block, [expected], [message] )
+
+Test Suite Convenience Methods Reference (See [test/data/testinit.js](https://github.com/jquery/jquery/blob/master/test/data/testinit.js))
+------------------------------
+
+q( ... );
+	Returns an array of elements with the given IDs
+	@example q("main", "foo", "bar") => [<div id="main">, <span id="foo">, <input id="bar">]
+
+t( testName, selector, [ "#array", "#of", "#ids" ] );
+	Asserts that a select matches the given IDs
+	@example t("Check for something", "//[a]", ["foo", "baar"]);
+
+fireNative( node, eventType );
+	Fires a native DOM event without going through jQuery
+	@example fireNative( jQuery("#elem")[0], "click" );
+
+url( "some/url.php" );
+	Add random number to url to stop caching
+	@example url("data/test.html") => "data/test.html?10538358428943"
+	@example url("data/test.php?foo=bar") => "data/test.php?foo=bar&10538358345554"
+
+testIframe( fileName, testName, callback );
+	Loads a given page constructing a url with fileName: "./data/" + fileName + ".html"
+	and fires the given callback on jQuery ready (using the jQuery loading from that page)
+	and passes the iFrame's jQuery to the callback.
+	Callback arguments:
+		callback( jQueryFromIFrame, iFrameWindow, iFrameDocument )
+
+testIframeWithCallback( testName, fileName, callback )
+	Loads a given page constructing a url with fileName: "./data/" + fileName + ".html"
+	The given callback is fired when window.iframeCallback is called by the page
+	The arguments passed to the callback are the same as the
+	arguments passed to window.iframeCallback, whatever that may be
+
 Questions?
 ----------
 
diff --git a/src/sizzle b/src/sizzle
-Subproject feebbd7e053bff426444c7b348c776c99c7490e
+Subproject dbb6995a01d10bf03a47a9c98ed48db396962b4
diff --git a/test/data/testinit.js b/test/data/testinit.js
index 9fc91ffb5..f2898e0ba 100644
--- a/test/data/testinit.js
+++ b/test/data/testinit.js
@@ -10,7 +10,7 @@ var jQuery = this.jQuery || "jQuery", // For testing .noConflict()
 /**
  * Set up a mock AMD define function for testing AMD registration.
  */
-function define(name, dependencies, callback) {
+function define( name, dependencies, callback ) {
 	amdDefined = callback();
 }
 
@@ -19,7 +19,7 @@ define.amd = {
 };
 
 /**
- * Returns an array of elements with the given IDs, eg.
+ * Returns an array of elements with the given IDs
  * @example q("main", "foo", "bar")
  * @result [<div id="main">, <span id="foo">, <input id="bar">]
  */
@@ -34,10 +34,11 @@ function q() {
 }
 
 /**
- * Asserts that a select matches the given IDs * @example t("Check for something", "//[a]", ["foo", "baar"]);
+ * Asserts that a select matches the given IDs
  * @param {String} a - Assertion name
  * @param {String} b - Sizzle selector
  * @param {String} c - Array of ids to construct what is expected
+ * @example t("Check for something", "//[a]", ["foo", "baar"]);
  * @result returns true if "//[a]" return two elements with the IDs 'foo' and 'baar'
  */
 function t( a, b, c ) {
@@ -113,7 +114,7 @@ if ( document.createEvent ) {
 }
 
 /**
- * Add random number to url to stop IE from caching
+ * Add random number to url to stop caching
  *
  * @example url("data/test.html")
  * @result "data/test.html?10538358428943"
@@ -121,7 +122,7 @@ if ( document.createEvent ) {
  * @example url("data/test.php?foo=bar")
  * @result "data/test.php?foo=bar&10538358345554"
  */
-function url(value) {
+function url( value ) {
 	return value + (/\?/.test(value) ? "&" : "?") + new Date().getTime() + "" + parseInt(Math.random()*100000);
 }
 
diff --git a/test/unit/attributes.js b/test/unit/attributes.js
index a39712f34..8f21303f3 100644
--- a/test/unit/attributes.js
+++ b/test/unit/attributes.js
@@ -1,8 +1,19 @@
 module("attributes", { teardown: moduleTeardown });
 
-var bareObj = function(value) { return value; };
-var functionReturningObj = function(value) { return (function() { return value; }); };
+var bareObj = function( value ) { return value; };
+var functionReturningObj = function( value ) { return (function() { return value; }); };
 
+/*
+	======== local reference =======
+	bareObj and functionReturningObj can be used to test passing functions to setters
+	See testVal below for an example
+
+	bareObj( value );
+		This function returns whatever value is passed in
+
+	functionReturningObj( value );
+		Returns a function that returns the value
+*/
 
 test("jQuery.propFix integrity test", function() {
 	expect(1);
diff --git a/test/unit/dimensions.js b/test/unit/dimensions.js
index 0b4eedcbf..e2cf6c003 100644
--- a/test/unit/dimensions.js
+++ b/test/unit/dimensions.js
@@ -8,6 +8,18 @@ function fn( val ) {
 	return function(){ return val; };
 }
 
+/*
+	======== local reference =======
+	pass and fn can be used to test passing functions to setters
+	See testWidth below for an example
+
+	pass( value );
+		This function returns whatever value is passed in
+
+	fn( value );
+		Returns a function that returns the value
+*/
+
 function testWidth( val ) {
 	expect(9);
 
diff --git a/test/unit/effects.js b/test/unit/effects.js
index 2b1cff3d3..e952ca8a9 100644
--- a/test/unit/effects.js
+++ b/test/unit/effects.js
@@ -1628,4 +1628,4 @@ asyncTest( "multiple unqueued and promise", 4, function() {
 	});
 });
 
-} // if ( jQuery.fx )
\ No newline at end of file
+} // if ( jQuery.fx )
diff --git a/test/unit/manipulation.js b/test/unit/manipulation.js
index 672b204e1..a6f418522 100644
--- a/test/unit/manipulation.js
+++ b/test/unit/manipulation.js
@@ -6,6 +6,18 @@ Array.prototype.arrayProtoFn = function(arg) { throw("arrayProtoFn should not be
 var bareObj = function(value) { return value; };
 var functionReturningObj = function(value) { return (function() { return value; }); };
 
+/*
+	======== local reference =======
+	bareObj and functionReturningObj can be used to test passing functions to setters
+	See testVal below for an example
+
+	bareObj( value );
+		This function returns whatever value is passed in
+
+	functionReturningObj( value );
+		Returns a function that returns the value
+*/
+
 test("text()", function() {
 	expect(5);
 	var expected = "This link has class=\"blog\": Simon Willison's Weblog";
diff --git a/test/unit/queue.js b/test/unit/queue.js
index fac74f906..540a41b59 100644
--- a/test/unit/queue.js
+++ b/test/unit/queue.js
@@ -1,6 +1,4 @@
-module( "queue", {
-	teardown: moduleTeardown
-});
+module( "queue", { teardown: moduleTeardown });
 
 test( "queue() with other types", 12, function() {
 	var counter = 0;
@@ -288,4 +286,4 @@ if ( jQuery.fn.stop ) {
 		foo.stop( false, true );
 	});
 
-} // if ( jQuery.fn.stop ) 
\ No newline at end of file
+} // if ( jQuery.fn.stop ) 
diff --git a/test/unit/selector.js b/test/unit/selector.js
index d605ab8df..079d130cc 100644
--- a/test/unit/selector.js
+++ b/test/unit/selector.js
@@ -1,9 +1,9 @@
+module("selector - jQuery only", { teardown: moduleTeardown });
+
 /**
  * This test page is for selector tests that require jQuery in order to do the selection
  */
 
-module("selector - jQuery only", { teardown: moduleTeardown });
-
 test("element - jQuery only", function() {
 	expect( 7 );
 
@@ -65,7 +65,8 @@ testIframe("selector/html5_selector", "attributes - jQuery.attr", function( jQue
 	expect(35);
 
 	/**
-	 * Returns an array of elements with the given IDs, eg.
+	 * Returns an array of elements with the given IDs
+	 * q & t are added here for the iFrame's context
 	 */
 	function q() {
 		var r = [],