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

diff --git a/README.md b/README.md
index ad38c228b34da724f41089f5295b19ed1c114ace..3e0cbf18571d6425c6535c80077e798c3bed8e8b 100644 (file)
--- 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
index feebbd7e053bff426444c7b348c776c99c7490ee..dbb6995a01d10bf03a47a9c98ed48db396962b42 160000 (submodule)
--- a/src/sizzle
+++ b/src/sizzle
@@ -1 +1 @@
-Subproject commit feebbd7e053bff426444c7b348c776c99c7490ee
+Subproject commit dbb6995a01d10bf03a47a9c98ed48db396962b42

diff --git a/test/data/testinit.js b/test/data/testinit.js
index 9fc91ffb5506026c3583baa2e08aba1e8fa8f939..f2898e0ba2fac43263cd3da0dd72aecd0bb3b908 100644 (file)
--- 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 a39712f3445638d0712a4679eca2d8b4d23636f8..8f21303f373e9d507538cf6fcdcfb542f745b218 100644 (file)
--- 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 0b4eedcbfb7db94467602bf43e7eacf5dae32c4e..e2cf6c003f174cde706142fb6c51ac373bb05cf2 100644 (file)
--- 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 2b1cff3d34ca4d64b129ae50b132465b60679dee..e952ca8a9c5bf6a591818a369a3d3c16b6237d9a 100644 (file)
--- 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 672b204e1eb3cfbc8f63bc789c6268a10c7e7244..a6f418522c5711c013a9fe264f06c7cbdcecafe4 100644 (file)
--- 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 fac74f9063c1b8ea461285fe57134d477548427b..540a41b594ca64043cd85bc634493079664d5768 100644 (file)
--- 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 d605ab8df65bba1cb948d1d3204e4d4029bedeb2..079d130cc3596e9da63aadcc248dbcadc047a8e7 100644 (file)
--- 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 = [],