YUI Test user guide and examples.

src/test/docs/component.json

@@ -0,0 +1,46 @@
+{
+    "name"       : "test",
+    "displayName": "Test",
+    "description": "A JavaScript testing framework with a comprehensive assertion syntax. Suitable for testing YUI-based code, but designed to support test-driven development across any JavaScript project, regardless of whether YUI is involved.",
+    "author"     : ["nzakas"],
+
+    "tags": ["utility", "test", "testing", "unit", "tdd"],
+    "use" : ["test"],
+
+    "examples": [
+        {
+            "name"       : "test-simple-example",
+            "displayName": "Simple Testing Example",
+            "description": "Demonstrates basic usage of YUI Test for setting up and running tests.",
+            "modules"    : ["test"]
+        },
+
+        {
+            "name": "test-advanced-test-options",
+            "displayName": "Advanced Test Options",
+            "description": "Demonstrates how to use advanced testing features such as defining tests that should fail, tests that should be ignored, and tests that should throw an error.",
+            "modules": ["test"]
+        },
+
+        {
+            "name": "test-array-tests",
+            "displayName": "Array Processing",
+            "description": "Demonstrates how to use the ArrayAssert object to test array data.",
+            "modules": ["test"]
+        },
+
+        {
+            "name": "test-async-test",
+            "displayName": "Asynchronous Testing",
+            "description": "Demonstrates basic asynchronous tests.",
+            "modules": ["test"]
+        },
+
+        {
+            "name": "test-async-event-tests",
+            "displayName": "Asynchronous Event Testing",
+            "description": "Demonstrates using events with asynchronous tests.",
+            "modules": ["test"]
+        }
+    ]
+}

src/test/docs/partials/test-advanced-test-options-source.mustache

@@ -0,0 +1,136 @@
+<div id="testLogger"></div>
+
+<script>
+YUI().use('node', 'console', 'test', function (Y) {
+
+    Y.namespace("example.test");
+
+    Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
+
+        //the name of the test case - if not provided, one is automatically generated
+        name: "Advanced Options Tests",
+
+        /*
+         * Specifies tests that "should" be doing something other than the expected.
+         */
+        _should: {
+
+            /*
+             * Tests listed in here should fail, meaning that if they fail, the test
+             * has passed. This is used mostly for YuiTest to test itself, but may
+             * be helpful in other cases.
+             */
+            fail: {
+
+                //the test named "testFail" should fail
+                testFail: true
+
+            },
+
+            /*
+             * Tests listed here should throw an error of some sort. If they throw an
+             * error, then they are considered to have passed.
+             */
+            error: {
+
+                /*
+                 * You can specify "true" for each test, in which case any error will
+                 * cause the test to pass.
+                 */
+                testGenericError: true,
+
+                /*
+                 * You can specify an error message, in which case the test passes only
+                 * if the error thrown matches the given message.
+                 */
+                testStringError: "I'm a specific error message.",
+                testStringError2: "I'm a specific error message.",
+
+                /*
+                 * You can also specify an error object, in which case the test passes only
+                 * if the error thrown is on the same type and has the same message.
+                 */
+                testObjectError: new TypeError("Number expected."),
+                testObjectError2: new TypeError("Number expected."),
+                testObjectError3: new TypeError("Number expected.")
+
+            },
+
+            /*
+             * Tests listed here should be ignored when the test case is run. For these tests,
+             * setUp() and tearDown() are not called.
+             */
+            ignore : {
+
+                testIgnore: true
+
+            }
+        },
+
+        //-------------------------------------------------------------------------
+        // Basic tests - all method names must begin with "test"
+        //-------------------------------------------------------------------------
+
+        testFail : function() {
+
+            //force a failure - but since this test "should" fail, it will pass
+            Y.Assert.fail("Something bad happened.");
+
+        },
+
+        testGenericError : function() {
+            throw new Error("Generic error");
+        },
+
+        testStringError : function() {
+
+            //throw a specific error message - this will pass because it "should" happen
+            throw new Error("I'm a specific error message.");
+        },
+
+        testStringError2 : function() {
+
+            //throw a specific error message - this will fail because the message isn't expected
+            throw new Error("I'm a specific error message, but a wrong one.");
+        },
+
+        testObjectError : function() {
+
+            //throw a specific error and message - this will pass because it "should" happen
+            throw new TypeError("Number expected.");
+        },
+
+        testObjectError2 : function() {
+
+            //throw a specific error and message - this will fail because the type doesn't match
+            throw new Error("Number expected.");
+        },
+
+        testObjectError3 : function() {
+
+            //throw a specific error and message - this will fail because the message doesn't match
+            throw new TypeError("String expected.");
+        },
+
+        testIgnore : function () {
+            alert("You'll never see this.");
+        }
+
+    });
+
+
+    //create the console
+    var r = new Y.Console({
+        newestOnTop : false,
+        style: 'block' // to anchor in the example content
+    });
+
+    r.render('#testLogger');
+
+    Y.Test.Runner.add(Y.example.test.AdvancedOptionsTestCase);
+
+    //run the tests
+    Y.Test.Runner.run();
+});
+
+</script>

src/test/docs/partials/test-array-tests-source.mustache

@@ -0,0 +1,180 @@
+<div id="testLogger"></div>
+
+<script>
+YUI().use('node', 'console', 'test', function (Y) {
+
+    Y.namespace("example.test");
+
+    Y.example.test.ArrayTestCase = new Y.Test.Case({
+
+        //the name of the test case - if not provided, one is automatically generated
+        name: "Array Tests",
+
+        //-------------------------------------------------------------------------
+        // Setup and teardown
+        //-------------------------------------------------------------------------
+
+        /*
+         * The setUp() method is used to setup data that necessary for a test to
+         * run. This method is called immediately before each test method is run,
+         * so it is run as many times as there are test methods.
+         */
+        setUp : function () {
+            this.data = new Array (0,1,2,3,4,5);
+        },
+
+        /*
+         * The tearDown() method is used to clean up the initialization that was done
+         * in the setUp() method. Ideally, it should free up all memory allocated in
+         * setUp(), anticipating any possible changes to the data. This method is called
+         * immediately after each test method is run.
+         */
+        tearDown : function () {
+            delete this.data;
+        },
+
+        //-------------------------------------------------------------------------
+        // Basic tests - all method names must begin with "test"
+        //-------------------------------------------------------------------------
+
+        /*
+         * Test the push() method.
+         */
+        testPush : function() {
+
+            //shortcut variables
+            var ArrayAssert = Y.ArrayAssert;
+
+            //do whatever data manipulation is necessary
+            this.data.push(6);
+
+            //array-specific assertions
+            ArrayAssert.isNotEmpty(this.data, "Array should not be empty.");
+            ArrayAssert.contains(6, this.data, "Array should contain 6.");
+            ArrayAssert.indexOf(6, this.data, 6, "The value in position 6 should be 6.");
+
+            //check that all the values are there
+            ArrayAssert.itemsAreEqual([0,1,2,3,4,5,6], this.data, "Arrays should be equal.");
+
+        },
+
+        /*
+         * Test the pop() method.
+         */
+        testPop : function() {
+
+            //shortcut variables
+            var Assert = Y.Assert;
+            var ArrayAssert = Y.ArrayAssert;
+
+            //do whatever data manipulation is necessary
+            var value = this.data.pop();
+
+            //array shouldn't be empty
+            ArrayAssert.isNotEmpty(this.data, "Array should not be empty.");
+
+            //basic equality assertion - expected value, actual value, optional error message
+            Assert.areEqual(5, this.data.length, "Array should have 5 items.");
+            Assert.areEqual(5, value, "Value should be 5.");
+
+            ArrayAssert.itemsAreSame([0,1,2,3,4], this.data, "Arrays should be equal.");
+        },
+
+        /*
+         * Test the reverse() method.
+         */
+        testReverse : function() {
+
+            //shortcut variables
+            var ArrayAssert = Y.ArrayAssert;
+
+            //do whatever data manipulation is necessary
+            this.data = this.data.reverse();
+
+            ArrayAssert.itemsAreEqual([5,4,3,2,1,0], this.data, "Arrays should be equal.");
+        },
+
+        /*
+         * Test the shift() method.
+         */
+        testShift : function() {
+
+            //shortcut variables
+            var Assert = Y.Assert;
+            var ArrayAssert = Y.ArrayAssert;
+
+            //do whatever data manipulation is necessary
+            var value = this.data.shift();
+
+            //array shouldn't be empty
+            ArrayAssert.isNotEmpty(this.data, "Array should not be empty.");
+
+            //basic equality assertion - expected value, actual value, optional error message
+            Assert.areEqual(5, this.data.length, "Array should have 6 items.");
+            Assert.areEqual(0, value, "Value should be 0.");
+
+            ArrayAssert.itemsAreEqual([1,2,3,4,5], this.data, "Arrays should be equal.");
+        },
+
+        /*
+         * Test the splice() method.
+         */
+        testSplice : function() {
+
+            //shortcut variables
+            var Assert = Y.Assert;
+            var ArrayAssert = Y.ArrayAssert;
+
+            //do whatever data manipulation is necessary
+            var removed = this.data.splice(1, 2, 99, 100);
+
+            //basic equality assertion - expected value, actual value, optional error message
+            Assert.areEqual(6, this.data.length, "Array should have 6 items.");
+
+            //the new items should be there
+            ArrayAssert.indexOf(99, this.data, 1, "Value at index 1 should be 99.");
+            ArrayAssert.indexOf(100, this.data, 2, "Value at index 2 should be 100.");
+
+            ArrayAssert.itemsAreEqual([0,99,100,3,4,5], this.data, "Arrays should be equal.");
+            ArrayAssert.itemsAreEqual([1,2], removed, "Removed values should be an array containing 1 and 2.");
+
+        },
+
+        /*
+         * Test the unshift() method.
+         */
+        testUnshift : function() {
+
+            //shortcut variables
+            var Assert = Y.Assert;
+            var ArrayAssert = Y.ArrayAssert;
+
+            //do whatever data manipulation is necessary
+            this.data.unshift(-1);
+
+            //basic equality assertion - expected value, actual value, optional error message
+            Assert.areEqual(7, this.data.length, "Array should have 7 items.");
+
+            //the new item should be there
+            ArrayAssert.indexOf(-1, this.data, 0, "First item should be -1.");
+
+            ArrayAssert.itemsAreEqual([-1,0,1,2,3,4,5], this.data, "Arrays should be equal.");
+        }
+
+    });
+
+    //create the console
+    var r = new Y.Console({
+        newestOnTop : false,
+        style: 'block' // to anchor in the example content
+    });
+
+    r.render('#testLogger');
+
+    Y.Test.Runner.add(Y.example.test.ArrayTestCase);
+
+    //run the tests
+    Y.Test.Runner.run();
+});
+
+</script>