YUI Test is a testing framework for browser-based JavaScript solutions. Using YUI Test, you can easily add unit testing to your JavaScript solutions. While not a direct port from any specific xUnit framework, YUI Test does derive some characteristics from nUnit and JUnit.
+YUI Test features:
+The basis of Test is the Y.Test.Case object. A TestCase object is created by using the
+ Y.Test.Case constructor and passing in an object containing methods and other information with which
+ to initialize the test case. Typically, the argument is an object literal, for example:
In this example, a simple test case is created named "TestCase Name". The name property is automatically applied to the test case so that it can be distinguished from other test cases that may be run during the same cycle. The two methods in this example are tests methods ( testSomething() and testSomethingElse()), which means that they are methods designed to test a specific piece of functional code. Test methods are indicatd by their name, either using the traditional manner of prepending the word test to the method name, or using a "friendly name," which is a sentence containing the word "should" that describes the test's purpose. For example:
Regardless of the naming convention used for test names, each should contain one or more assertions that test data for validity.
+ +As each test method is called, it may be necessary to setup information before it's run and then potentially clean up that information
+ after the test is run. The setUp() method is run before each and every test in the test case and likewise the tearDown() method is run
+ after each test is run. These methods should be used in conjunction to create objects before a test is run and free up memory after the
+ test is run. For example:
In this example, a setUp() method creates a data object with some basic information. Each property of the data object is checked with
+ a different test, testName() tests the value of data.name while testAge() tests the value of data.age. Afterwards, the data object is deleted
+ to free up the memory. Real-world implementations will have more complex tests, of course, but they should follow the basic pattern you see in the above code.
Note: Both setUp() and tearDown() are optional methods and are only used when defined.
There may be times when you want to ignore a test (perhaps the test is invalid for your purposes or the functionality is being re-engineered and so it shouldn't be tested at this time). To specify tests to ignore,
+ use the _should.ignore property and name each test to skip as a property whose value is set to true:
Here the testName() method will be ignored when the test case is run. This is accomplished by first defining the special _should
+ property and within it, an ignore property. The ignore property is an object containing name-value pairs representing the names of the tests
+ to ignore. By defining a property named "testName" and setting its value to true, it says that the method named "testName"
+ should not be executed.
There may be a time that a test throws an error that was expected. For instance, perhaps you're testing a function that should throw an error if invalid data
+ is passed in. A thrown error in this case can signify that the test has passed. To indicate that
+ a test should throw an error, use the _should.error property. For example:
In this example, a test case is created to test the standalone sortArray() function, which simply accepts an array and calls its sort() method.
+ But if the argument is not an array, an error is thrown. When testSortArray() is called, it throws an error because a number is passed into sortArray().
+ Since the _should.error object has a property called "testSortArray" set to true, this indicates that testSortArray() should
+ pass only if an error is thrown.
It is possible to be more specific about the error that should be thrown. By setting a property in _should.error to a string, you can
+ specify that only a specific error message can be construed as a passed test. Here's an example:
In this example, the testSortArray() test will only pass if the error that is thrown has a message of "Expected an array".
+ If a different error occurs within the course of executing testSortArray(), then the test will fail due to an unexpected error.
If you're unsure of the message but know the type of error that will be thrown, you can specify the error constructor for the error + you're expecting to occur:
+``` +function sortArray(array) { + if (array instanceof Array){ + array.sort(); + } else { + throw new TypeError("Expected an array"); + } +} + +var testCase = new Y.Test.Case({ + + name: "TestCase Name", + + //--------------------------------------------- + // Special instructions + //--------------------------------------------- + + _should: { + error: { + testSortArray: TypeError + } + }, + + //--------------------------------------------- + // Tests + //--------------------------------------------- + + testSortArray: function () { + sortArray(12); //this should throw an error + } + +}); +``` + +In this example, the test will pass if a TypeError gets thrown; if any other type of error is thrown,
+ the test will fail. A word of caution: TypeError is the most frequently thrown error by browsers,
+ so specifying a TypeError as expected may give false passes.
To narrow the margin of error between checking for an error message and checking the error type, you can create a specific error
+ object and set that in the _should.error property, such as:
Using this code, the testSortArray() method will only pass if a TypeError object is thrown with a message of
+ "Expected an array"; if any other type of error occurs, then the test fails due to an unexpected error.
Note: If a test is marked as expecting an error, the test will fail unless that specific error is thrown. If the test completes without an error being thrown, then it fails.
+ +Test methods use assertions to check the validity of a particular action or function. An assertion method tests (asserts) that a condition is valid; if not, it throws an error that causes the test to fail. If all assertions pass within a test method, it is said that the test has passed. The simplest assertion is Y.assert(), which takes two arguments: a condition to test and a message. If the condition is not true, then an assertion error is thrown with the specified message. For example:
In this example, testUsingAsserts() will fail if value is not equal to 5 of flag is not set to true. The Y.assert() method may be all that you need, but there are advanced options available. The Y.Assert object contains several assertion methods that can be used to validate data.
The simplest assertions are areEqual() and areNotEqual(). Both methods accept three arguments: the expected value,
+ the actual value, and an optional failure message (a default one is generated if this argument is omitted). For example:
These methods use the double equals (==) operator to determine if two values are equal, so type coercion may occur. This means
+ that the string "5" and the number 5 are considered equal because the double equals sign converts the number to
+ a string before doing the comparison. If you don't want values to be converted for comparison purposes, use the sameness assertions instead.
The sameness assertions are areSame() and areNotSame(), and these accept the same three arguments as the equality
+ assertions: the expected value, the actual value, and an optional failure message. Unlike the equality assertions, these methods use
+ the triple equals operator (===) for comparisions, assuring that no type coercion will occur. For example:
Note: Even though this example shows multiple assertions failing, a test will stop as soon as one + assertion fails, causing all others to be skipped.
+ +There may be times when some data should be of a particular type. To aid in this case, there are several methods that test the data type
+ of variables. Each of these methods acce These are used as in the following example: In addition to these specific data type assertions, there are two generic data type assertions. The If you need to test object types instead of simple data types, you can also use the There are numerous special values in JavaScript that may occur in code. These include Each of these methods accepts two arguments: the value to test and an optional failure message. All of the assertions expect the
+ exact value (no type coercion occurs), so for example calling While most tests fail as a result of an assertion, there may be times when
+ you want to force a test to fail or create your own assertion method. To do this, use the
+ In this case, the When the failure of this method is reported, the message "I decided this should fail." will be reported. Mock objects are used to eliminate test dependencies on other objects. In complex software systems, there's often multiple
+ object that have dependence on one another to do their job. Perhaps part of your code relies on the To create a mock object, use the In this code, a mock The call to In order to use mock objects, your code must be able to swap in and out objects that it uses. For example, a hardcoded
+ reference to Note that you can use assertions and mock objects together; either will correctly indicate a test failure. There may be times when you don't necessarily care about a specific argument's value. Since you must always specify the correct
+ number of arguments being passed in, you still need to indicate that an argument is expected. There are several special values
+ you can use as placeholders for real values. These values do a minimum amount of data validation: Each of these special values can be used in the The expecation here will allow any string value as the first argument and any Boolean value as the last argument.
+ These special values should be used with care as they can let invalid values through if they are too general. The
+ Since it's not possible to create property getters and setters in all browsers, creating a true cross-browser property
+ expectation isn't feasible. YUI Test mock objects allow you to specify a property name and it's expected value when
+ This example indicates that the YUI Test allows you to pause a currently running test and resume either after a set amount of time or
+ at another designated time. The A test may be resumed after a certain amount of time by passing in two arguments to In this code, the If you want a test to wait until a specific event occurs before resuming, the In this example, an For large web applications, you'll probably have many test cases that should be run during a testing phase. A test suite helps to handle multiple test cases
+ by grouping them together into functional units that can be run together. To create new test suite, use the Here, a test suite is created and three test cases are added to it using the It's also possible to add other multiple By grouping test suites together under a parent test suite you can more effectively manage testing of particular aspects of an application. Test suites may also have Test suite In order to run test cases and test suites, use the If at some point you decide not to run the tests that have already been added to the Making this call removes all test cases and test suites that were added using the The Test-level events occur during the execution of specific test methods. There are three test-level events: For each of these events, the event data object has three properties: For There are two events that occur at the test case level: For these two events, the event data object has three properties: For The There are two events that occur at the test suite level: For these two events, the event data object has three properties: The This example shows the results for a test suite with two test cases, but there may be test suites contained within test suites. In that case,
+ the hierarchy is built out accordingly, for example: In this code, the test suite contained another test suite named "testSuite0", which is included in the results along
+ with its test cases. At each level, the results are aggregated so that you can tell how many tests passed or failed within each
+ test case or test suite. There are two events that occur at the The data object for these events contain a You can subscribe to particular events by calling the In this code, the There are two ways to view test results. The first is to output test results to the Console
+ component. To do so, you need only create a new Console instance; the result results will be posted
+ to the logger automatically: If you are using a browser that supports the You can also extract the test result data using the You can pass any of these into The XML format outputs results in the following
+ format: The JSON format requires the JSON utility to be loaded on the page and outputs results in a format that follows the object/array hierarchy of the results object, such as: The JUnit XML format outputs results in the following format: Note that there isn't a direct mapping between YUI Test test suites and JUnit test suites, so some
+of the hierarchical information is lost. The TAP format outputs results in the following format: The XML, JSON, and JUnit XML formats produce a string with no extra white space (white space and indentation shown here is for readability
+ purposes only). When all tests have been completed and the results object has been returned, you can post those results to a server
+ using a You can create a new The form submission happens behind-the-scenes and will not cause your page to navigate away. This operation is
+ one direction; the reporter does not get any content back from the server. There are four predefined serialization formats for results objects: The format in which to submit the results can be specified in the You can optionally specify additional fields to be sent with the results report by using the Note that if you specify a field name that is the same as a default field, the custom field is ignored in favor of
+ the default field. This example shows how to use advanced test options, which allow you to specify additional information about how a test should be run.
+ Each This example begins by creating a namespace and a This Immediately after the This In the Moving on to the The last section is The next part of the example contains the actual test methods. Since each test method is specified as having a certain behavior in
+ The first method is This method uses Next, the test methods that should error are defined. The The fact that this method throws an error is enough to cause it to pass (the type of error and error message don't matter). The next
+ two methods, The To be more specific, Of the these three methods, only The last method in the If this test weren't ignored, then the alert should be displayed. Since it is ignored, though, you will never see the alert. Additionally,
+ there is a special message displayed in the With all of the tests defined, the last step is to run them: Before running the tests, it's necessary to create a This example shows how to use the This example uses the The example begins by creating an example namespace and This The first test is The test begins by setting up a shortcut variables for The next test is This test also starts out by creating some shortcut variables, for The next test is The The next test is The The next test is The The first test is to determine that the length of the array is still 6 (since the previous step removed two items and then inserted two, the
+ length should still be 6). After that, The next test is Working similar to With all of the tests defined, the last step is to run them: Before running the tests, it's necessary to create a This example shows how to create an asynchronous test with the YUI Test framework for testing browser-based JavaScript code.
+ A This example begins by creating a namespace: This namespace serves as the core object upon which others will be added (to prevent creating global objects). The first step is to create a new The only test in the With all of the tests defined, the last step is to run them: Before running the tests, it's necessary to create a This example shows how to create an asynchronous test with the YUI Test framework for testing browser-based JavaScript code.
+ A This example begins by creating a namespace: This namespace serves as the core object upon which others will be added (to prevent creating global objects). The first step is to create a new The object literal passed into the constructor contains two different sections. The first section contains the Next, the The second section contains the actual tests to be run. The only test is With all of the tests defined, the last step is to run them: Before running the tests, it's necessary to create a This example shows basic usage of the YUI Test framework for testing browser-based JavaScript code.
+ Two different This example begins by creating a namespace: This namespace serves as the core object upon which others will be added (to prevent creating global objects). The first step is to create a new The object literal passed into the constructor contains a number of different sections. The first section contains the Next, the The last section contains the actual tests to be run. Test method names must always begin with the word "test" (all lowercase) in order
+ to differentiate them from other methods that may be added to the object. The first test in this object is The second and third tests follow the same pattern as the first with the exception that they work with different data types. The Although it's possible that you'll have only one As with the first To better organize the two The first line creates a new Any number of With all of the tests defined, the last step is to run them. This initialization is assigned to take place when all of the YUI
+ components have been loaded: Before running the tests, it's necessary to create a
+
+ isArray() - passes only if the value is an instance of Array.isBoolean() - passes only if the value is a Boolean.isFunction() - passes only if the value is a function.isNumber() - passes only if the value is a number.isObject() - passes only if the value is an object or a function.isString() - passes only if the value is a string.isTypeOf() method tests the string returned when the typeof operator is applied to a value. This
+ method accepts three arguments: the type that the value should be ("string", "number",
+ "boolean", "undefined", "object", or "function"), the value to test, and an optional failure message.
+ For example:isInstanceOf() assertion, which accepts three
+ arguments: the constructor function to test for, the value to test, and an optional failure message. This assertion uses the instanceof
+ operator to determine if it should pass or fail. Example:Special Value Assertions
+ true, false, NaN,
+ null, and undefined. There are a number of assertions designed to test for these values specifically:
+
+ isFalse() - passes if the value is false.isTrue() - passes if the value is true.isNaN() - passes if the value is NaN.isNotNaN() - passes if the value is not NaN.isNull() - passes if the value is null.isNotNull() - passes if the value is not null.isUndefined() - passes if the value is undefined.isNotUndefined() - passes if the value is not undefined.isFalse(0) will fail.Forced Failures
+ fail() method to force a test method to fail immediately:testForceFail() method does nothing but force
+ the method to fail. Optionally, you can pass in a message to fail()
+ which will be displayed as the failure message:Mock Objects
+ XMLHttpRequest
+ object to get more information; if you're running the test without a network connection, you can't really be sure if the test
+ is failing because of your error or because the network connection is down. In reality, you just want to be sure that the correct
+ data was passed to the open() and send() methods because you can assume that, after that point,
+ the XMLHttpRequest object works as expected. This is the perfect case for using a mock object.Y.Mock() method to create a new object and then use Y.Mock.expect()
+ to define expectations for that object. Expectations define which methods you're expecting to call, what the arguments should be,
+ and what the expected result is. When you believe all of the appropriate methods have been called, you call Y.Mock.verify()
+ on the mock object to check that everything happened as it should. For example:XMLHttpRequest object is created to aid in testing. The mock object defines two
+ expectations: that the open() method will be called with a given set of arguments and that the send()
+ method will be called with a given set of arguments. This is done by using Y.Mock.expect() and passing in the
+ mock object as well as some information about the expectation. The method property indicates the method name
+ that will be called and the args property is an array of arguments that should be passed into the method. Each
+ argument is compared against the actual arguments using the identically equal (===) operator, and if any of the
+ arguments doesn't match, an assertion failure is thrown when the method is called (it "fails fast" to allow easier debugging).Y.Mock.verify() is the final step in making sure that all expectations have been met. It's at this stage
+ that the mock object checks to see that all methods have been called. If open() was called but send()
+ was not, then an assertion failure is thrown and the test fails. It's very important to call Y.Mock.verify() to test
+ all expectations; failing to do so can lead to false passes when the test should actually fail.XMLHttpRequest in your code would prevent you from using a mock object in its place. It's sometimes
+ necessary to refactor code in such a way that referenced objects are passed in rather than hardcoded so that mock objects
+ can be used.Special Argument Values
+
+
+ Y.Mock.Value.Any - any value is valid regardless of type.Y.Mock.Value.String - any string value is valid.Y.Mock.Value.Number - any number value is valid.Y.Mock.Value.Boolean - any Boolean value is valid.Y.Mock.Value.Object - any non-null object value is valid.Y.Mock.Value.Function - any function value is valid.args property of an expectation, such as:Y.Mock.Value.Any special value should be used only if you're absolutely sure that the argument doesn't
+ matter.Property Expectations
+ Y.Mock.verify() is called. This isn't a true property expectation but rather an expectation that the property
+ will have a certain value at the end of the test. You can specify a property expectation like this:status property of the mock object should be set to 404 before
+ the test is completed. When Y.Mock.verify() is called on mockXhr, it will check
+ the property and throw an assertion failure if it has not been set appropriately.Asynchronous Tests
+ TestCase object has a method called wait(). When wait()
+ is called, the test immediately exits (meaning that any code after that point will be ignored) and waits for a signal to resume
+ the test.wait(): a function to execute
+ and the number of milliseconds to wait before executing the function (similar to using setTimeout()). The function
+ passed in as the first argument will be executed as part of the current test (in the same scope) after the specified amount of time.
+ For example:testAsync() function does one assertion, then waits 1000 milliseconds before performing
+ another assertion. The function passed into wait() is still in the scope of the original test, so it has
+ access to this.data just as the original part of the test does. Timed waits are helpful in situations when
+ there are no events to indicate when the test should resume.wait() method can be called
+ with a timeout argument (the number of milliseconds to wait before considering the test a failure). At that point, testing will resume only when the resume() method is called. The
+ resume() method accepts a single argument, which is a function to run when the test resumes. This function
+ should specify additional assertions. If resume() isn't called before the timeout expires, then the test fails. The following tests to see if the Anim object has performed its
+ animation completely:Anim object is used to animate the width of an element to 400 pixels. When the animation
+ is complete, the end event is fired, so that is where the resume() method is called. The
+ function passed into resume() simply tests that the final width of the element is indeed 400 pixels. Once the event handler is set up, the animation begins.
+ In order to allow enough time for the animation to complete, the wait() method is called
+ with a timeout of 3.1 seconds (just longer than the 3 seconds needed to complete the animation). At that point, testing stops until the animation completes and resume() is called or until 3100 milliseconds have passed.Test Suites
+ Y.Test.Suite
+ constructor and pass in the name of the test suite. The name you pass in is for logging purposes and allows you to discern which TestSuite instance currently running. For example: add() method. The test suite now contains all of the
+ information to run a series of tests.TestSuite instances together under a parent TestSuite using the same add() method:setUp() and tearDown() methods. A test suite's setUp() method is called before
+ the first test in the first test case is executed (prior to the test case's setUp() method); a test suite's tearDown()
+ method executes after all tests in all test cases/suites have been executed (after the last test case's tearDown() method). To specify
+ these methods, pass an object literal into the Y.Test.Suite constructor:setUp() and tearDown() may be helpful in setting up global objects that are necessary for a multitude of tests
+ and test cases.Running Tests
+ Y.Test.Runner object. This object is a singleton that
+ simply runs all of the tests in test cases and suites, reporting back on passes and failures. To determine which test cases/suites
+ will be run, add them to the Y.Test.Runner using the add() method. Then, to run the tests, call the run()
+ method:TestRunner, they can be removed by calling clear():add() method.TestRunner Events
+ Y.Test.Runner provides results and information about the process by publishing several events. These events can occur at four
+ different points of interest: at the test level, at the test case level, at the test suite level, and at the Y.Test.Runner level.
+ The data available for each event depends completely on the type of event and the level at which the event occurs.Test-Level Events
+
+
+ Y.Test.Runner.TEST_PASS_EVENT - occurs when the test passes.Y.Test.Runner.TEST_FAIL_EVENT - occurs when the test fails.Y.Test.Runner.TEST_IGNORE_EVENT - occurs when a test is ignored.
+
+ type - indicates the type of event that occurred.testCase - the test case that is currently being run.testName - the name of the test that was just executed or ignored.Y.Test.Runner.TEST_FAIL_EVENT, an error property containing the error object
+ that caused the test to fail.TestCase-Level Events
+
+
+ Y.Test.Runner.TEST_CASE_BEGIN_EVENT - occurs when the test case is next to be executed but before the first test is run.Y.Test.Runner.TEST_CASE_COMPLETE_EVENT - occurs when all tests in the test case have been executed or ignored.
+
+ type - indicates the type of event that occurred.testCase - the test case that is currently being run.TEST_CASE_COMPLETE_EVENT, an additional property called results is included. The results
+ property is an object containing the aggregated results for all tests in the test case (it does not include information about tests that
+ were ignored). Each test that was run has an entry in the result object where the property name is the name of the test method
+ and the value is an object with two properties: result, which is either "pass" or "fail", and message, which is a
+ text description of the result (simply "Test passed" when a test passed or the error message when a test fails). Additionally, the
+ failed property indicates the number of tests that failed in the test case, the passed property indicates the
+ number of tests that passed, and the total property indicates the total number of tests executed. A typical results
+ object looks like this:TEST_CASE_COMPLETE_EVENT provides this information for transparency into the testing process.TestSuite-Level Events
+
+
+ Y.Test.Runner.TEST_SUITE_BEGIN_EVENT - occurs when the test suite is next to be executed but before the first test is run.Y.Test.Runner.TEST_SUITE_COMPLETE_EVENT - occurs when all tests in all test cases in the test suite have been executed or ignored.
+
+ type - indicates the type of event that occurred.testSuite - the test suite that is currently being run.TEST_SUITE_COMPLETE_EVENT also has a results property, which contains aggregated results for all of the
+ test cases (and other test suites) it contains. Each test case and test suite contained within the main suite has an entry in the
+ results object, forming a hierarchical structure of data. A typical results object may look like this:TestRunner-Level Events
+ Y.Test.Runner level:
+
+ Y.Test.Runner.BEGIN_EVENT - occurs when testing is about to begin but before any tests are run.Y.Test.Runner.COMPLETE_EVENT - occurs when all tests in all test cases and test suites have been executed or ignored.type property, indicating the type of event that occurred. COMPLETE_EVENT
+ also includes a results property that is formatted the same as the data returned from TEST_SUITE_COMPLETE_EVENT and
+ contains rollup information for all test cases and tests suites that were added to the TestRunner.Subscribing to Events
+ subscribe() method. Your event handler code
+ should expect a single object to be passed in as an argument. This object provides information about the event that just occured. Minimally,
+ the object has a type property that tells you which type of event occurred. Example:handleTestFail() function is assigned as an event handler for TEST_FAIL_EVENT. You can also
+ use a single event handler to subscribe to any number of events, using the event data object's type property to determine
+ what to do:Viewing Results
+ console
+ object (Firefox with Firebug installed, Safari 3+, Internet Explorer 8+, Chrome), then you can
+ direct the test results onto the console. To do so, make sure that you've specified your YUI
+ instance to use the console when logging:Y.Test.Runner.getResults() method. By default, this method
+ returns an object representing the results of the tests that were just run (the method returns null if called
+ while tests are still running). You can optionally specify a format in which the results should be returned. There are four
+ possible formats:
+
+ Y.Test.Format.XML - YUI Test XML (default)Y.Test.Format.JSON - JSONY.Test.Format.JUnitXML - JUnit XMLY.Test.Format.TAP - TAPY.Test.Runner.getResults() to get a string with the test result information properly
+ formatted. For example:Test Reporting
+ Y.Test.Reporter object. A Y.Test.Reporter object creates a form that is POSTed
+ to a specific URL with the following fields:
+
+ results - the serialized results object.useragent - the user-agent string of the browser.timestamp - the date and time that the report was sent.Y.Test.Reporter object by passing in the URL to report to. The results object can
+ then be passed into the report() method to submit the results:
+
+
+ Y.Test.Format.XML (default)Y.Test.Format.JSONY.Test.Format.JUnitXMLY.Test.Format.TAPY.Test.Reporter constructor by passing in the appropriate
+ Y.Test.Format value (when no argument is specified, Y.Test.Format.XML is used:Custom Fields
+ addField() method.
+ This method accepts two arguments: a name and a value. Any field added using addField() is POSTed along with
+ the default fields back to the server:TestCase can specify up to three different options for tests,
+ including tests that should be ignored, tests that should throw an error, and tests that should fail.Advanced Test Options
+
+Y.Test.Case object:Y.Test.Case serves as the basis for this example.Using
+
+_shouldname of the Y.Test.Case is defined, there is a _should property.
+ This property specifies information about how tests should behave and is defined as an object literal with one
+ or more of the following properties: fail, error, and ignore.Each of these three
+ is also defined as an object literal whose property names map directly to the names of test methods in the Y.Test.Case.
+ This example uses all three properties:Y.Test.Case specifies one test that should fail, six that should throw an error, and one that should be ignored.fail section, the test method testFail() is specified as one that should fail. By adding the
+ property testFail and settings its value to true, the Y.Test.Runner knows that this test is expected to fail.
+ If the test were to be run without failing, it would be considered a failure of the test. This feature is useful when testing
+ YUI Test itself or addon components to YUI Test.error section, there are six tests specified that should throw an error. There are three different ways
+ to indicate that a test is expected to throw an error. The first is simply to add a property with the same name as the test method
+ and set its value equal to true (similar to specifying tests that should fail). In this example, the testGenericError()
+ method is specified this way. When specified like this, the test passes regardless of the type of error that occurs. This can be
+ dangerous since unexpected errors will also cause the test to pass. To be more specific, set the property value for the test method
+ to an error message string. When a string is used instead of the Boolean true, the test passes only when an error is thrown and that
+ error message matches the string. In this example, testStringError() and testStringError2() expect an error
+ to be thrown with an error message of "I'm a specific error message." If any other error occurs inside of the these methods,
+ the test will fail because the error message doesn't match. The last way to specify an error should occur is to create an actual error
+ object, which is the case with testObjectError(), testObjectError2(), and testObjectError3().
+ When specified in this way, a test will pass only when an error is thrown whose constructor and error message match that of the
+ error object.ignore, which determines tests that should be ignored. In this example, the method testIgnore()
+ is set to be ignored when the Y.Test.Case is executed. Test in the ignore section are specified the same way
+ as those in the fail section, by adding the name as a property and setting its value to true.Creating the test methods
+
+_should, they each do something to show their particular functionality.testFail(), which does nothing but purposely fail. Since this method is specified as one that should
+ fail, it means that this test will pass:Assert.fail() to force the test to fail. This type of method is helpful if you are creating your own
+ type of assert methods that should fail when certain data is passed in.testGenericError() method is specified as needing to throw
+ an error to pass. In the error section, testGenericError is set to true, meaning that any error causes
+ this method to pass. To illustrate this, the method simply throws an error:testStringError() and testStringError2() are specified as throwing an error with a specific
+ message ("I'm a specific error message."):testStringError() method will pass when executed because the error message matches up exactly with the one
+ specified in the error section. The testStringError2() method, however, will fail because its
+ error message is different from the one specified.testObjectError(), testObjectError2(), and testObjectError3(),
+ specified an error type (TypeError) and an error messsage ("Number expected."):testObjectError() will pass because it's the only one that throws a TypeError
+ object with the message, "Number expected." The testObjectError2() method will fail because the type of error
+ being thrown (Error) is different from the expected type (TypeError), as specified in the error
+ section. The last method, testObjectError3(), also fails. Though it throws the right type of error, the error message
+ doesn't match the one that was specified.Y.Test.Case is testIgnore(), which is specified to be ignored. To be certain, this
+ method pops up a message:Y.Console when a test is ignored.Running the tests
+
+Y.Console object to display the results (otherwise the tests would run
+ but you wouldn't see the results). After that, the Y.Test.Runner is loaded with the Y.Test.Suite object by calling
+ add() (any number of Y.Test.Case and Y.Test.Suite objects can be added to a Y.Test.Runner,
+ this example only adds one for simplicity). The very last step is to call run(), which begins executing the tests in its
+ queue and displays the results in the Y.Console.Complete Example Source
+
+```
+{{>test-advanced-test-options-source}}
+```
diff --git a/src/test/docs/test-array-tests.mustache b/src/test/docs/test-array-tests.mustache
new file mode 100644
index 00000000000..33675f86509
--- /dev/null
+++ b/src/test/docs/test-array-tests.mustache
@@ -0,0 +1,331 @@
+ArrayAssert object, which
+ contains assertions designed to be used specifically with JavaScript Arrays and array-like objects.Array Assertions
+
+Y.ArrayAssert object to test methods on JavaScript's
+ built-in Array object. The intent of this example is to introduce Y.ArrayAssert and its methods
+ as an alternative to the generic methods available on Y.Assert.Y.Test.Case:TestCase has a setUp() method that creates an array for all the tests to use, as well as
+ a tearDown() method that deletes the array after each test has been executed. This array is used throughout
+ the tests as a base for array manipulations.Testing
+push()testPush(), which tests the functionality of the Array object's push() method
+ (other methods hidden for simpicity):Y.ArrayAssert, then pushes the value 6 onto
+ the data array (which was created by setUp()). Next, Y.ArrayAssert.isNotEmpty() determines if the
+ array has at least one item; this should definitely pass because the push() operation only adds values to the array. To determine
+ that the new value, 6, is in the array, Y.ArrayAssert.contains() is used. The first argument is the value to look for and the second
+ is the array to look in. To find out if the new value ended up where it should have (the last position, index 6), Y.ArrayAssert.indexOf()
+ is used, passing in the value to search for as the first argument, the array to search in as the second, and the index at which the value should
+ occur as the final argument. Since 6 was pushed onto the end of an array that already had 6 items, it should end up at index 6 (the length of the
+ array minus one). As a final test, Y.ArrayAssert.itemsAreEqual() is used to determine that all of the items in the array are in the
+ correct place. The first argument of this method is an array that has all of the values that should be in the array you're testing. This assertion
+ passes only when the values in both arrays match up (the values are equal and the positions are the same).Testing
+pop()testPop(), which tests the functionality of the Array object's pop() method:Y.Assert and Y.ArrayAssert. Next, the pop()
+ method is called, storing the returned item in value. Since pop() should only remove a single item, Y.ArrayAssert.isNotEmpty()
+ is called to ensure that only one item has been removed. After that, Y.Assert.areEqual() is called twice: once to check the
+ length of the array and once to confirm the value of the item that was removed from the array (which should be 5). The last assertion uses
+ Y.ArrayAssert.itemsAreSame(), which is similar to Y.ArrayAssert.itemsAreEqual() in that it compares values between two
+ arrays. The difference is that Y.ArrayAssert.itemsAreSame() uses strict equality (===) to compare values, ensuring that
+ no behind-the-scenes type conversions will occur (this makes Y.ArrayAssert.itemsAreSame() more useful for working with arrays of
+ objects).Testing
+reverse()testReverse(), which tests the functionality of the Array object's reverse() method:testRemove() method is very simple, calling reverse() on the array and then testing the result. Since
+ every item in the array has changed, the changes can be tested by calling Y.ArrayAssert.itemsAreEqual() once (instead of
+ calling Y.ArrayAssert.indexOf() multiple times). The first argument is an array with all the values in the reverse order
+ of the array that was created in setUp(). When compared with the second argument, the newly reversed array, the values in
+ each position should be equal.Testing
+shift()testShift(), which tests the functionality of the Array object's shift() method:shift() method removes the first item in the array and returns it (similar to pop(), which removes the item
+ from the end). In the testShift() method, shift() is called and the item is stored in value. To ensure
+ that the rest of the array is still there, Y.ArrayAssert.isNotEmpty() is called. After that, Array.areEqual() is
+ called twice, once to test the length of the array and once to test the value that was returned from shift() (which should be
+ 0). As a last test, the entire array is tested using Y.ArrayAssert.itemsAreEqual() to ensure that all of the items have shifted
+ into the appropriate positions in the array.Testing
+splice()testSplice(), which tests the functionality of the Array object's splice() method:splice() method is one of the most powerful Array manipulations. It can both remove and add any number of items
+ from an array at the same time. This test begins by splicing some values into the array. When calling splice(), the first argument
+ is 1, indicating that values should be inserted at index 1 of the array; the second argument is 2, indicating that two values should be
+ removed from the array (the value in index 1 and the value in index 2); the third and fourth arguments are values that should be inserted
+ into the array at the position given by the first argument. Essentially, values 1 and 2 should end up being replaced by values 99 and 100 in
+ the array.Y.Assert.indexOf() is called to determine that the values of 99 and 100 are in positions
+ 1 and 2, respectively. To ensure the integrity of the entire array, Y.ArrayAssert.itemsAreEqual() is called on the array, comparing
+ it to an array with the same values. The very last step is to test the value returned from splice(), which is an array containing
+ the removed values, 1 and 2. Y.ArrayAssert.itemsAreEqual() is appropriate for this task as well.Testing
+unshift()testUnshift(), which tests the functionality of the Array object's unshift() method:push(), unshift() adds a value to the array, but the item is added to the front (index 0) instead of
+ the back. This test begins by adding the value -1 to the array. The first assertion determines if the length of the array has been incremented
+ to 7 to account for the new value. After that, Y.ArrayAssert.indexOf() is used to determine if the value has been placed in the
+ correct location. The final assertions tests that the entire array is expected by using Y.ArrayAssert.itemsAreEqual().Running the tests
+
+Y.Console object to display the results (otherwise the tests would run
+ but you wouldn't see the results). After that, the Y.Test.Runner is loaded with the Y.Test.Case object by calling
+ add() (any number of Y.Test.Case and TestSuite objects can be added to a Y.Test.Runner,
+ this example only adds one for simplicity). The very last step is to call run(), which begins executing the tests in its
+ queue and displays the results in the Y.Console.Complete Example Source
+
+```
+{{>test-array-tests-source}}
+```
diff --git a/src/test/docs/test-async-event-tests.mustache b/src/test/docs/test-async-event-tests.mustache
new file mode 100644
index 00000000000..97c8b4bdf10
--- /dev/null
+++ b/src/test/docs/test-async-event-tests.mustache
@@ -0,0 +1,128 @@
+Y.Test.Case object is created to test the
+ Y.Anim object. The test waits until the animation is complete
+ before checking the settings of the animated element.Asynchronous Events Test Example
+
+Creating the TestCase
+
+Y.Test.Caseobject called AsyncTestCase.
+ To do so, using the Y.Test.Caseconstructor and pass in an object literal containing information about the tests to be run:Y.Test.Caseis called testAnimation. It begins by creating a new
+Anim object that will animate the width of a div to 400 pixels over three seconds. An
+event handler is assigned to the Anim object's end event, within which the
+resume() method is called. A function is passed into the resume() method to indicate
+the code to run when the test resumes, which is a test to make sure the width is 400 pixels. After that, the
+run() method is called to begin the animation and the wait() method is called to
+tell the Y.Test.Runner to wait until it is told to resume testing again. When the animation completes,
+the end event is fired and the test resumes, assuring that the width is correct.Running the tests
+
+Y.Console object to display the results (otherwise the tests would run
+ but you wouldn't see the results). After that, the Y.Test.Runner is loaded with the Y.Test.Caseobject by calling
+ add() (any number of Y.Test.Caseand TestSuite objects can be added to a Y.Test.Runner,
+ this example only adds one for simplicity). The very last step is to call run(), which begins executing the tests in its
+ queue and displays the results in the Y.Console.Complete Example Source
+
+```
+{{>test-async-event-tests-source}}
+```
diff --git a/src/test/docs/test-async-test.mustache b/src/test/docs/test-async-test.mustache
new file mode 100644
index 00000000000..b2333d60f46
--- /dev/null
+++ b/src/test/docs/test-async-test.mustache
@@ -0,0 +1,141 @@
+Y.Test.Case object is created with a test that waits for a
+ few seconds before continuing. The Y.Test.Runner
+ is then used to run the tests once the page has loaded.Asynchronous Test Example
+
+Creating the TestCase
+
+Y.Test.Case object called AsyncTestCase.
+ To do so, using the Y.Test.Case constructor and pass in an object literal containing information about the tests to be run:name property,
+ which is used to determine which Y.Test.Case is being executed. A name is necessary, so one is generated if it isn't specified.setUp() and tearDown() methods are included. The setUp() method is used in a Y.Test.Case
+ to set up data that may be needed for tests to be completed. This method is called immediately before each test is executed. For this example,
+ setUp() creates a data object. The tearDown() is responsible for undoing what was done in setUp(). It is
+ run immediately after each test is run and, in this case, deletes the data object that was created by setUp. These methods are optional.testWait(), which demonstrates using
+ the wait() method to delay test execution. There are two arguments passed in: a function to run once the test resumes
+ and the number of milliseconds to wait before running this function (same basic format as setTimeout()). When
+ the test resumes, the function is executed in the context of the Y.Test.Case object, meaning that it still has
+ access to all of the same data as the test that called wait(), including properties and methods on the Y.Test.Case
+ itself. This example shows the anonymous function using both the Y.Assert object and the data property
+ of the Y.Test.Case.Running the tests
+
+Y.Console object to display the results (otherwise the tests would run
+ but you wouldn't see the results). After that, the Y.Test.Runner is loaded with the Y.Test.Case object by calling
+ add() (any number of Y.Test.Case and TestSuite objects can be added to a TestRunner,
+ this example only adds one for simplicity). The very last step is to call run(), which begins executing the tests in its
+ queue and displays the results in the Y.Console.Complete Example Source
+
+```
+{{>test-async-test-source}}
+```
diff --git a/src/test/docs/test-simple-example.mustache b/src/test/docs/test-simple-example.mustache
new file mode 100644
index 00000000000..3e75414c456
--- /dev/null
+++ b/src/test/docs/test-simple-example.mustache
@@ -0,0 +1,241 @@
+TestCase objects are created and added to a
+ TestSuite object. The TestRunner
+ is then used to run the tests once the page has loaded.Simple Test Example
+
+Creating the first TestCase
+
+Y.Test.Case object called DataTestCase.
+ To do so, using the Y.Test.Case constructor and pass in an object literal containing information about the tests to be run:name property,
+ which is used to determine which Y.Test.Case is being executed. A name is necessary, so one is generated if it isn't specified.setUp() and tearDown() methods are included. The setUp() method is used in a Y.Test.Case
+ to set up data that may be needed for tests to be completed. This method is called immediately before each test is executed. For this example,
+ setUp() creates a data object. The tearDown() is responsible for undoing what was done in setUp(). It is
+ run immediately after each test is run and, in this case, deletes the data object that was created by setUp. These methods are optional.testName(), which runs
+ various assertions on data.name. Inside of this method, a shortcut to Y.Assert is set up and used to run three
+ assertions: isObject() on data, isString() on data.name and areEqual() to compare
+ data.name to the expected value, "test". These assertions are arranged in order from least-specific to most-specific,
+ which is the recommended way to arrange your assertions. Basically, the third assertion is useless to run unless the second has passes and the second
+ can't possibly pass unless the first passed. Both isObject() and isString() accept a single argument, which is the value
+ to test (you could optionally include a failure message as a second argument, though this is not required). The areEqual() method
+ expects two arguments, the first being the expected value ("test") and the second being the actual value (data.name).testYear()
+ method works with data.year, which is a number and so runs tests specifically for numbers (areEqual() can be used with
+ all data types). The testBeta() method works with data.beta, which is a Boolean, and so it uses the isTrue()
+ assertion instead of areEqual() (though it could also use areEqual(true, this.data.beta)).Creating the second TestCase
+
+ Y.Test.Case object, typically there is more than one, and so this example includes
+ a second Y.Test.Case. This one tests some of the built-in functions of the Array object:Y.Test.Case, this one is split up into three sections: the name, the setUp() and tearDown()
+ methods, and the test methods. The setUp() method in this Y.Test.Case creates an array of data to be used by the various
+ tests while the tearDown() method destroys the array. The test methods are very simple, testing the pop(), push(),
+ and splice() methods. Each test method uses areEqual() exclusively, to show the different ways that it can be used.
+ The testPop() method calls pop() on the array of values, then verifies that the length of the array has changed and
+ that the value popped off is 4; the testPush() pushes a new value (5) onto the array and then verifies that the length of the array has
+ changed and that the value is included in the correct location; the testSplice() method tests splice() by removing one
+ value that's already in the array and inserting two in its place.Creating the TestSuite
+Y.Test.Case objects, a Y.Test.Suite is created and those two Y.Test.Case objects are
+ added to it:Y.Test.Suite object using its constructor, which accepts a single argument - the name of the suite. As with
+ the name of a Y.Test.Case, the Y.Test.Suite name is used to determine where execution is when tests are being executed. Although
+ not required (one is generated if it's not provided), it is recommended that you select a meaningful name to aid in debugging.Y.Test.Case and Y.Test.Suite objects can be added to a Y.Test.Suite by using the add()
+ method. In this example, the two Y.Test.Case objects created earlier are added to the Y.Test.Suite.Running the tests
+
+Y.Console object to display the results (otherwise the tests would run
+ but you wouldn't see the results). After that, the Y.Test.Runner is loaded with the Y.Test.Suite object by calling
+ add() (any number of Y.Test.Case and Y.Test.Suite objects can be added to a Y.Test.Runner,
+ this example only adds one for simplicity). The very last step is to call run(), which begins executing the tests in its
+ queue and displays the results in the Y.Console.Complete Example Source
+
+```
+{{>test-simple-example-source}}
+```