febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<div class="intro">
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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 <a href="http://www.nunit.org/">nUnit</a> and <a href="http://www.junit.org/">JUnit</a>.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>YUI Test features:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li>Rapid creation of <strong>test cases</strong> through simple syntax.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li>Advanced <strong>failure detection</strong> for methods that throw errors.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li>Grouping of related test cases using <strong>test suites</strong>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><strong>Mock objects</strong> for writing tests without external dependencies.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><strong>Asynchronous tests</strong> for testing events and Ajax communication.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><strong>DOM Event simulation</strong> in all A-grade browsers (through <a href="../event/index.html">Event</a>).</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync{{>getting-started}}
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="testcases">Using Test Cases</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The basis of Test is the <code>Y.Test.Case</code> object. A <code>TestCase</code> object is created by using the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>Y.Test.Case</code> constructor and passing in an object containing methods and other information with which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to initialize the test case. Typically, the argument is an object literal, for example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //traditional test names
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSomething : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSomethingElse : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this example, a simple test case is created named "TestCase Name". The <code>name</code> 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 ( <code>testSomething()</code> and <code>testSomethingElse())</code>, 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 <code>test</code> 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:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //friendly test names
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "Something should happen here" : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "Something else should happen here" : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Regardless of the naming convention used for test names, each should contain one or more <a href="#assertions">assertions</a> that test data for validity.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="setup-and-teardown">setUp() and tearDown()</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>As each test method is called, it may be necessary to setup information before it's run and then potentially clean up that information
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync after the test is run. The <code>setUp()</code> method is run before each and every test in the test case and likewise the <code>tearDown()</code> method is run
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync test is run. For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Setup and tear down
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync setUp : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this.data = { name : "Nicholas", age : 28 };
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync tearDown : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testName: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual("Nicholas", this.data.name, "Name should be 'Nicholas'");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testAge: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual(28, this.data.age, "Age should be 28");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this example, a <code>setUp()</code> method creates a data object with some basic information. Each property of the data object is checked with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync a different test, <code>testName()</code> tests the value of <code>data.name</code> while <code>testAge()</code> tests the value of <code>data.age</code>. Afterwards, the data object is deleted
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 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.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p><strong>Note: </strong>Both <code>setUp()</code> and <code>tearDown()</code> are optional methods and are only used when defined.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="ignoring">Ignoring Tests</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync use the <code>_should.ignore</code> property and name each test to skip as a property whose value is set to <code>true</code>:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Special instructions
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync testName: true //ignore this test
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync //---------------------------------------------
e7c4c205cb0af88b5ef0786be46da94847a9a37bvboxsync // Setup and tear down
e7c4c205cb0af88b5ef0786be46da94847a9a37bvboxsync //---------------------------------------------
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync setUp : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this.data = { name : "Nicholas", age : 28 };
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync tearDown : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testName: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual("Nicholas", this.data.name, "Name should be 'Nicholas'");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testAge: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual(28, this.data.age, "Age should be 28");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Here the <code>testName()</code> method will be ignored when the test case is run. This is accomplished by first defining the special <code>_should</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync property and within it, an <code>ignore</code> property. The ignore property is an object containing name-value pairs representing the names of the tests
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to ignore. By defining a property named "testName" and setting its value to <code>true</code>, it says that the method named "testName"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync should not be executed.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="intentional-errors">Intentional Errors</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is passed in. A thrown error in this case can signify that the test has passed. To indicate that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync a test should throw an error, use the <code>_should.error</code> property. For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncfunction sortArray(array) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (array instanceof Array){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync throw new TypeError("Expected an array");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Special instructions
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: true //this test should throw an error
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync sortArray(12); //this should throw an error
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this example, a test case is created to test the standalone <code>sortArray()</code> function, which simply accepts an array and calls its <code>sort()</code> method.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync But if the argument is not an array, an error is thrown. When <code>testSortArray()</code> is called, it throws an error because a number is passed into <code>sortArray()</code>.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Since the <code>_should.error</code> object has a property called "testSortArray" set to <code>true</code>, this indicates that <code>testSortArray()</code> should
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync pass only if an error is thrown.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>It is possible to be more specific about the error that should be thrown. By setting a property in <code>_should.error</code> to a string, you can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync specify that only a specific error message can be construed as a passed test. Here's an example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncfunction sortArray(array) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (array instanceof Array){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync throw new TypeError("Expected an array");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Special instructions
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: "Expected an array"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync sortArray(12); //this should throw an error
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this example, the <code>testSortArray()</code> test will only pass if the error that is thrown has a message of "Expected an array".
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync If a different error occurs within the course of executing <code>testSortArray()</code>, then the test will fail due to an unexpected error.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync you're expecting to occur:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncfunction sortArray(array) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (array instanceof Array){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync throw new TypeError("Expected an array");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Special instructions
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: TypeError
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync sortArray(12); //this should throw an error
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this example, the test will pass if a <code>TypeError</code> gets thrown; if any other type of error is thrown,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the test will fail. A word of caution: <code>TypeError</code> is the most frequently thrown error by browsers,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync so specifying a <code>TypeError</code> as expected may give false passes.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>To narrow the margin of error between checking for an error message and checking the error type, you can create a specific error
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync object and set that in the <code>_should.error</code> property, such as:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncfunction sortArray(array) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (array instanceof Array){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync throw new TypeError("Expected an array");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Special instructions
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: new TypeError("Expected an array")
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSortArray: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync sortArray(12); //this should throw an error
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Using this code, the <code>testSortArray()</code> method will only pass if a <code>TypeError</code> object is thrown with a message of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "Expected an array"; if any other type of error occurs, then the test fails due to an unexpected error.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p><strong>Note: </strong>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.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="assertions">Assertions</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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 <code>Y.assert()</code>, which takes two arguments: a condition to test and a message. If the condition is <em>not</em> true, then an assertion error is thrown with the specified message. For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testUsingAsserts : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.assert(value == 5, "The value should be five.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.assert(flag, "Flag should be true.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this example, <code>testUsingAsserts()</code> will fail if <code>value</code> is not equal to 5 of <code>flag</code> is not set to <code>true</code>. The <code>Y.assert()</code> method may be all that you need, but there are advanced options available. The <code>Y.Assert</code> object contains several assertion methods that can be used to validate data.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="equality">Equality Assertions</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The simplest assertions are <code>areEqual()</code> and <code>areNotEqual()</code>. Both methods accept three arguments: the expected value,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the actual value, and an optional failure message (a default one is generated if this argument is omitted). For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testEqualityAsserts : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual(5, 5); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual(5, "5"); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areNotEqual(5, 6); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual(5, 6, "Five was expected."); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>These methods use the double equals (<code>==</code>) operator to determine if two values are equal, so type coercion may occur. This means
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that the string <code>"5"</code> and the number <code>5</code> are considered equal because the double equals sign converts the number to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync a string before doing the comparison. If you don't want values to be converted for comparison purposes, use the sameness assertions instead.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="sameness">Sameness Assertions</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The sameness assertions are <code>areSame()</code> and <code>areNotSame()</code>, and these accept the same three arguments as the equality
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync assertions: the expected value, the actual value, and an optional failure message. Unlike the equality assertions, these methods use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the triple equals operator (<code>===</code>) for comparisions, assuring that no type coercion will occur. For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSamenessAsserts : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areSame(5, 5); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areSame(5, "5"); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areNotSame(5, 6); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areNotSame(5, "5"); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areSame(5, 6, "Five was expected."); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p><strong>Note: </strong>Even though this example shows multiple assertions failing, a test will stop as soon as one
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync assertion fails, causing all others to be skipped.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="datatypes">Data Type Assertions</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync of variables. Each of these methods acce<prepts two arguments: the data to test and an optional failure message. The data type assertions are as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync follows:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isArray()</code> - passes only if the value is an instance of <code>Array</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isBoolean()</code> - passes only if the value is a Boolean.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isFunction()</code> - passes only if the value is a function.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isNumber()</code> - passes only if the value is a number.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isObject()</code> - passes only if the value is an object or a function.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isString()</code> - passes only if the value is a string.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>These are used as in the following example: </p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testDataTypeAsserts : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isString("Hello world"); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isFunction(function(){}); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isBoolean(true); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isObject(function(){}); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isNumber("1", "Value should be a number."); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isString(1, "Value should be a string."); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In addition to these specific data type assertions, there are two generic data type assertions.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The <code>isTypeOf()</code> method tests the string returned when the <code>typeof</code> operator is applied to a value. This
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method accepts three arguments: the type that the value should be ("string", "number",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "boolean", "undefined", "object", or "function"), the value to test, and an optional failure message.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testTypeOf : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("string", "Hello world"); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("number", 1); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("boolean", true); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("number", 1.5); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("function", function(){}); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("object", {}); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("undefined", this.blah); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf("number", "Hello world", "Value should be a number."); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>If you need to test object types instead of simple data types, you can also use the <code>isInstanceOf()</code> assertion, which accepts three
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync arguments: the constructor function to test for, the value to test, and an optional failure message. This assertion uses the <code>instanceof</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync operator to determine if it should pass or fail. Example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testInstanceOf : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isInstanceOf(Object, {}); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isInstanceOf(Array, []); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isInstanceOf(Object, []); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isInstanceOf(Function, function(){}); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isInstanceOf(Object, function(){}); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTypeOf(Array, {}, "Value should be an array."); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="specialvalues">Special Value Assertions</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>There are numerous special values in JavaScript that may occur in code. These include <code>true</code>, <code>false</code>, <code>NaN</code>,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>null</code>, and <code>undefined</code>. There are a number of assertions designed to test for these values specifically:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isFalse()</code> - passes if the value is <code>false</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isTrue()</code> - passes if the value is <code>true</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isNaN()</code> - passes if the value is <code>NaN</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isNotNaN()</code> - passes if the value is not <code>NaN</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isNull()</code> - passes if the value is <code>null</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isNotNull()</code> - passes if the value is not <code>null</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isUndefined()</code> - passes if the value is <code>undefined</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>isNotUndefined()</code> - passes if the value is not <code>undefined</code>.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Each of these methods accepts two arguments: the value to test and an optional failure message. All of the assertions expect the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync exact value (no type coercion occurs), so for example calling <code>isFalse(0)</code> will fail.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSpecialValues : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isFalse(false); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isTrue(true); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isNaN(NaN); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isNaN(5 / "5"); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isNull(null); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isNotNull(undefined); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isUndefined(undefined); //passes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.isUndefined({}, "Value should be undefined."); //fails
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3 id="forcedfailures">Forced Failures</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>While most tests fail as a result of an assertion, there may be times when
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync you want to force a test to fail or create your own assertion method. To do this, use the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>fail()</code> method to force a test method to fail immediately:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
fd60bfdb327b9b1e7a6d084cf368fb7f07c566cfvboxsync testForceFail : function () {
fd60bfdb327b9b1e7a6d084cf368fb7f07c566cfvboxsync Y.Assert.fail(); //causes the test to fail
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this case, the <code>testForceFail()</code> method does nothing but force
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the method to fail. Optionally, you can pass in a message to <code>fail()</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync which will be displayed as the failure message:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testForceFail : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.fail("I decided this should fail.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>When the failure of this method is reported, the message "I decided this should fail." will be reported.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="mockobjects">Mock Objects</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Mock objects are used to eliminate test dependencies on other objects. In complex software systems, there's often multiple
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync object that have dependence on one another to do their job. Perhaps part of your code relies on the <code>XMLHttpRequest</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync object to get more information; if you're running the test without a network connection, you can't really be sure if the test
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is failing because of your error or because the network connection is down. In reality, you just want to be sure that the correct
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync data was passed to the <code>open()</code> and <code>send()</code> methods because you can assume that, after that point,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the <code>XMLHttpRequest</code> object works as expected. This is the perfect case for using a mock object.</p>
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync <p>To create a mock object, use the <code>Y.Mock()</code> method to create a new object and then use <code>Y.Mock.expect()</code>
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync to define expectations for that object. Expectations define which methods you're expecting to call, what the arguments should be,
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync and what the expected result is. When you believe all of the appropriate methods have been called, you call <code>Y.Mock.verify()</code>
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync on the mock object to check that everything happened as it should. For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//code being tested
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncfunction logToServer(message, xhr){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync xhr.open("get", "/log.php?msg=" + encodeURIComponent(message), true);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//test case for testing the above function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "logToServer Tests",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testPassingDataToXhr : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var mockXhr = Y.Mock();
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //I expect the open() method to be called with the given arguments
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method: "open",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync args: ["get", "/log.php?msg=hi", true]
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //I expect the send() method to be called with the given arguments
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method: "send",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync args: [null]
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //now call the function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync logToServer("hi", mockXhr);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //verify the expectations were met
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this code, a mock <code>XMLHttpRequest</code> object is created to aid in testing. The mock object defines two
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync expectations: that the <code>open()</code> method will be called with a given set of arguments and that the <code>send()</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method will be called with a given set of arguments. This is done by using <code>Y.Mock.expect()</code> and passing in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync mock object as well as some information about the expectation. The <code>method</code> property indicates the method name
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that will be called and the <code>args</code> property is an array of arguments that should be passed into the method. Each
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync argument is compared against the actual arguments using the identically equal (<code>===</code>) operator, and if any of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync arguments doesn't match, an assertion failure is thrown when the method is called (it "fails fast" to allow easier debugging).</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The call to <code>Y.Mock.verify()</code> is the final step in making sure that all expectations have been met. It's at this stage
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that the mock object checks to see that all methods have been called. If <code>open()</code> was called but <code>send()</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync was not, then an assertion failure is thrown and the test fails. It's very important to call <code>Y.Mock.verify()</code> to test
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync all expectations; failing to do so can lead to false passes when the test should actually fail.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In order to use mock objects, your code must be able to swap in and out objects that it uses. For example, a hardcoded
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync reference to <code>XMLHttpRequest</code> in your code would prevent you from using a mock object in its place. It's sometimes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync necessary to refactor code in such a way that referenced objects are passed in rather than hardcoded so that mock objects
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync can be used.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Note that you can use assertions and mock objects together; either will correctly indicate a test failure.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>Special Argument Values</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>There may be times when you don't necessarily care about a specific argument's value. Since you must always specify the correct
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync number of arguments being passed in, you still need to indicate that an argument is expected. There are several special values
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync you can use as placeholders for real values. These values do a minimum amount of data validation:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Mock.Value.Any</code> - any value is valid regardless of type.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Mock.Value.String</code> - any string value is valid.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Mock.Value.Number</code> - any number value is valid.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Mock.Value.Boolean</code> - any Boolean value is valid.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Mock.Value.Object</code> - any non-<code>null</code> object value is valid.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Mock.Value.Function</code> - any function value is valid.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Each of these special values can be used in the <code>args</code> property of an expectation, such as:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method: "open",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync args: [Y.Mock.Value.String, "/log.php?msg=hi", Y.Mock.Value.Boolean]
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The expecation here will allow any string value as the first argument and any Boolean value as the last argument.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync These special values should be used with care as they can let invalid values through if they are too general. The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>Y.Mock.Value.Any</code> special value should be used only if you're absolutely sure that the argument doesn't
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync matter.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>Property Expectations</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Since it's not possible to create property getters and setters in all browsers, creating a true cross-browser property
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync expectation isn't feasible. YUI Test mock objects allow you to specify a property name and it's expected value when
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>Y.Mock.verify()</code> is called. This isn't a true property expectation but rather an expectation that the property
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync will have a certain value at the end of the test. You can specify a property expectation like this:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//expect that the status property will be set to 404
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync property: "status",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>This example indicates that the <code>status</code> property of the mock object should be set to 404 before
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the test is completed. When <code>Y.Mock.verify()</code> is called on <code>mockXhr</code>, it will check
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the property and throw an assertion failure if it has not been set appropriately.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="asynctests">Asynchronous Tests</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>YUI Test allows you to pause a currently running test and resume either after a set amount of time or
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync at another designated time. The <code>TestCase</code> object has a method called <code>wait()</code>. When <code>wait()</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is called, the test immediately exits (meaning that any code after that point will be ignored) and waits for a signal to resume
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the test.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>A test may be resumed after a certain amount of time by passing in two arguments to <code>wait()</code>: a function to execute
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and the number of milliseconds to wait before executing the function (similar to using <code>setTimeout()</code>). The function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 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.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Setup and tear down
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync setUp : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this.data = { name : "Nicholas", age : 29 };
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync tearDown : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testAsync: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual("Nicholas", this.data.name, "Name should be 'Nicholas'");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //wait 1000 milliseconds and then run this function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual(29, this.data.age, "Age should be 29");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this code, the <code>testAsync()</code> function does one assertion, then waits 1000 milliseconds before performing
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync another assertion. The function passed into <code>wait()</code> is still in the scope of the original test, so it has
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync access to <code>this.data</code> just as the original part of the test does. Timed waits are helpful in situations when
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync there are no events to indicate when the test should resume.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>If you want a test to wait until a specific event occurs before resuming, the <code>wait()</code> method can be called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 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 <code>resume()</code> method is called. The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>resume()</code> method accepts a single argument, which is a function to run when the test resumes. This function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync should specify additional assertions. If <code>resume()</code> isn't called before the timeout expires, then the test fails. The following tests to see if the <code>Anim</code> object has performed its
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync animation completely:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar testCase = new Y.Test.Case({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "TestCase Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //---------------------------------------------
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testAnimation : function (){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //animate width to 400px
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var myAnim = new Y.Anim({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync node: '#testDiv',
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync duration: 3
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var test = this;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //assign oncomplete handler
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync myAnim.on("end", function(){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //tell the TestRunner to resume
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.Assert.areEqual(myAnim.get("node").get("offsetWidth"), 400, "Width of the DIV should be 400.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //start the animation
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //wait until something happens
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this example, an <code>Anim</code> object is used to animate the width of an element to 400 pixels. When the animation
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is complete, the <code>end</code> event is fired, so that is where the <code>resume()</code> method is called. The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync function passed into <code>resume()</code> simply tests that the final width of the element is indeed 400 pixels. Once the event handler is set up, the animation begins.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync In order to allow enough time for the animation to complete, the <code>wait()</code> method is called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 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 <code>resume()</code> is called or until 3100 milliseconds have passed.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="testsuites">Test Suites</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync by grouping them together into functional units that can be run together. To create new test suite, use the <code>Y.Test.Suite</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 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 <code>TestSuite</code> instance currently running. For example: </p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//create the test suite
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar suite = new Y.Test.Suite("TestSuite Name");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//add test cases
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Here, a test suite is created and three test cases are added to it using the <code>add()</code> method. The test suite now contains all of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync information to run a series of tests.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>It's also possible to add other multiple <code>TestSuite</code> instances together under a parent <code>TestSuite</code> using the same <code>add()</code> method:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//create a test suite
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar suite = new Y.Test.Suite("TestSuite Name");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//add a test case
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//create another suite
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar anotherSuite = new Y.Test.Suite("test_suite_name");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//add a test case
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//add the second suite to the first
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncsuite.add(anotherSuite);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>By grouping test suites together under a parent test suite you can more effectively manage testing of particular aspects of an application.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Test suites may also have <code>setUp()</code> and <code>tearDown()</code> methods. A test suite's <code>setUp()</code> method is called before
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the first test in the first test case is executed (prior to the test case's <code>setUp()</code> method); a test suite's <code>tearDown()</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method executes after all tests in all test cases/suites have been executed (after the last test case's <code>tearDown()</code> method). To specify
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync these methods, pass an object literal into the <code>Y.Test.Suite</code> constructor:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//create a test suite
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar suite = new Y.Test.Suite({
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name : "TestSuite Name",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync setUp : function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //test-suite-level setup
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync tearDown: function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //test-suite-level teardown
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Test suite <code>setUp()</code> and <code>tearDown()</code> may be helpful in setting up global objects that are necessary for a multitude of tests
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and test cases.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="running-tests">Running Tests</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In order to run test cases and test suites, use the <code>Y.Test.Runner</code> object. This object is a singleton that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync simply runs all of the tests in test cases and suites, reporting back on passes and failures. To determine which test cases/suites
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync will be run, add them to the <code>Y.Test.Runner</code> using the <code>add()</code> method. Then, to run the tests, call the <code>run()</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//add the test cases and suites
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync//run all tests
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>If at some point you decide not to run the tests that have already been added to the <code>TestRunner</code>, they can be removed by calling <code>clear()</code>:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Making this call removes all test cases and test suites that were added using the <code>add()</code> method.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>TestRunner Events</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The <code>Y.Test.Runner</code> provides results and information about the process by publishing several events. These events can occur at four
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync different points of interest: at the test level, at the test case level, at the test suite level, and at the <code>Y.Test.Runner</code> level.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The data available for each event depends completely on the type of event and the level at which the event occurs.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>Test-Level Events</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Test-level events occur during the execution of specific test methods. There are three test-level events:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.TEST_PASS_EVENT</code> - occurs when the test passes.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.TEST_FAIL_EVENT</code> - occurs when the test fails.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.TEST_IGNORE_EVENT</code> - occurs when a test is ignored.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>For each of these events, the event data object has three properties:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>type</code> - indicates the type of event that occurred.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>testCase</code> - the test case that is currently being run.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>testName</code> - the name of the test that was just executed or ignored.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>For <code>Y.Test.Runner.TEST_FAIL_EVENT</code>, an <code>error</code> property containing the error object
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that caused the test to fail.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>TestCase-Level Events</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>There are two events that occur at the test case level:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.TEST_CASE_BEGIN_EVENT</code> - occurs when the test case is next to be executed but before the first test is run.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.TEST_CASE_COMPLETE_EVENT</code> - occurs when all tests in the test case have been executed or ignored.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>For these two events, the event data object has three properties:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>type</code> - indicates the type of event that occurred.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>testCase</code> - the test case that is currently being run.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>For <code>TEST_CASE_COMPLETE_EVENT</code>, an additional property called <code>results</code> is included. The <code>results</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync property is an object containing the aggregated results for all tests in the test case (it does not include information about tests that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync were ignored). Each test that was run has an entry in the <code>result</code> object where the property name is the name of the test method
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and the value is an object with two properties: <code>result</code>, which is either "pass" or "fail", and <code>message</code>, which is a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync text description of the result (simply "Test passed" when a test passed or the error message when a test fails). Additionally, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>failed</code> property indicates the number of tests that failed in the test case, the <code>passed</code> property indicates the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync number of tests that passed, and the <code>total</code> property indicates the total number of tests executed. A typical <code>results</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync object looks like this:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testcase",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "Test Case 0",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Test passed",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test0"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "fail",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Assertion failed",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test1"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The <code>TEST_CASE_COMPLETE_EVENT</code> provides this information for transparency into the testing process.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>TestSuite-Level Events</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>There are two events that occur at the test suite level:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.TEST_SUITE_BEGIN_EVENT</code> - occurs when the test suite is next to be executed but before the first test is run.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.TEST_SUITE_COMPLETE_EVENT</code> - occurs when all tests in all test cases in the test suite have been executed or ignored.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>For these two events, the event data object has three properties:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>type</code> - indicates the type of event that occurred.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>testSuite</code> - the test suite that is currently being run.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The <code>TEST_SUITE_COMPLETE_EVENT</code> also has a <code>results</code> property, which contains aggregated results for all of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync test cases (and other test suites) it contains. Each test case and test suite contained within the main suite has an entry in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>results</code> object, forming a hierarchical structure of data. A typical <code>results</code> object may look like this:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testsuite",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "Test Suite 0",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testCase0: {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testcase",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "testCase0",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Test passed."
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test0"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "fail",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Assertion failed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test1"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testCase1: {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testcase",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "testCase1",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test0"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "fail",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Assertion failed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test1"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>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,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the hierarchy is built out accordingly, for example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testsuite",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "Test Suite 0",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testCase0: {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testcase",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "testCase0",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test0"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "fail",
b8908d384db2324f04a2f68a13e67ea32ebf609avboxsync message: "Assertion failed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test1"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testCase1: {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testcase",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "testCase1",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test0"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "fail",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Assertion failed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test1"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testSuite0:{
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testsuite",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "testSuite0",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync testCase2: {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync ignored: 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "testcase",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "testCase2",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test0"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync result: "fail",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync message: "Assertion failed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync type: "test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name: "test1"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this code, the test suite contained another test suite named "testSuite0", which is included in the results along
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with its test cases. At each level, the results are aggregated so that you can tell how many tests passed or failed within each
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync test case or test suite.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>TestRunner-Level Events</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>There are two events that occur at the <code>Y.Test.Runner</code> level:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.BEGIN_EVENT</code> - occurs when testing is about to begin but before any tests are run.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Runner.COMPLETE_EVENT</code> - occurs when all tests in all test cases and test suites have been executed or ignored.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The data object for these events contain a <code>type</code> property, indicating the type of event that occurred. <code>COMPLETE_EVENT</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync also includes a <code>results</code> property that is formatted the same as the data returned from <code>TEST_SUITE_COMPLETE_EVENT</code> and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync contains rollup information for all test cases and tests suites that were added to the <code>TestRunner</code>.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>Subscribing to Events</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>You can subscribe to particular events by calling the <code>subscribe()</code> method. Your event handler code
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync should expect a single object to be passed in as an argument. This object provides information about the event that just occured. Minimally,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the object has a <code>type</code> property that tells you which type of event occurred. Example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncfunction handleTestFail(data){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync alert("Test named '" + data.testName + "' failed with message: '" + data.error.message + "'.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar TestRunner = Y.Test.Runner;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncTestRunner.subscribe(TestRunner.TEST_FAIL_EVENT, handleTestFail);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>In this code, the <code>handleTestFail()</code> function is assigned as an event handler for <code>TEST_FAIL_EVENT</code>. You can also
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync use a single event handler to subscribe to any number of events, using the event data object's <code>type</code> property to determine
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync what to do:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncfunction handleTestResult(data){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var TestRunner = Y.Test.Runner;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync alert("Test named '" + data.testName + "' failed with message: '" + data.error.message + "'.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync alert("Test named '" + data.testName + "' passed.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync alert("Test named '" + data.testName + "' was ignored.");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncTestRunner.subscribe(TestRunner.TEST_FAIL_EVENT, handleTestResult);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncTestRunner.subscribe(TestRunner.TEST_IGNORE_EVENT, handleTestResult);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncTestRunner.subscribe(TestRunner.TEST_PASS_EVENT, handleTestResult);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="viewing-results">Viewing Results</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>There are two ways to view test results. The first is to output test results to the TestConsole
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync component. To do so, you need only create a new `Test.Console` instance; the result results will be posted
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to the logger automatically:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncYUI({ logInclude: { TestRunner: true } }).use('test-console', "test", function(Y){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //tests go here
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //initialize the console
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync newestOnTop: false
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync })).render('#log');
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //run the tests
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>If you are using a browser that supports the <code>console</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync object (Firefox with Firebug installed, Safari 3+, Internet Explorer 8+, Chrome), then you can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync direct the test results onto the console. To do so, make sure that you've specified your <code>YUI</code>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync instance to use the console when logging:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncYUI({ useBrowserConsole: true }).use("test", function(Y){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //tests go here
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>You can also extract the test result data using the <code>Y.Test.Runner.getResults()</code> method. By default, this method
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync returns an object representing the results of the tests that were just run (the method returns <code>null</code> if called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync while tests are still running). You can optionally specify a format in which the results should be returned. There are four
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync possible formats:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.XML</code> - YUI Test XML (default)</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.JSON</code> - JSON</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.JUnitXML</code> - JUnit XML</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.TAP</code> - <a href="http://testanything.org/">TAP</a></li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>You can pass any of these into <code>Y.Test.Runner.getResults()</code> to get a string with the test result information properly
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync formatted. For example:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncYUI({ useBrowserConsole: true }).use("test", function(Y){
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //tests go here
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //get object of results
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var resultsObject = Y.Test.Runner.getResults();
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync //get XML results
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var resultsXML = Y.Test.Runner.getResults(Y.Test.Format.XML);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The XML format outputs results in the following
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync format:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<?xml version="1.0" encoding="UTF-8" ?>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<report name="YUI Test Results" passed="5" failed="3" ignored="1" total="5">
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testsuite name="yuisuite" passed="5" failed="0" ignored="0" total="5">
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testcase name="Y.Anim" passed="5" failed="0" ignored="0" total="5">
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <test name="test_getEl" result="pass" message="Test passed" />
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <test name="test_isAnimated" result="pass" message="Test passed" />
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <test name="test_stop" result="pass" message="Test passed" />
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <test name="test_onStart" result="pass" message="Test passed" />
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <test name="test_endValue" result="pass" message="Test passed" />
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </testcase>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </testsuite>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The JSON format requires the <a href="../json/index.html">JSON utility</a> to be loaded on the page and outputs results in a format that follows the object/array hierarchy of the results object, such as:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "passed": 5,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "failed": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "ignored": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "total": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type": "report",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "name": "YUI Test Results",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "yuisuite":{
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "passed": 5,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "failed": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "ignored": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "total": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type": "testsuite",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "name": "yuisuite",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "passed": 5,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "failed": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "ignored": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "total": 0,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type":"testcase",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "test_getEl":{
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "result":"pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "message":"Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type":"test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "name":"test_getEl"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "test_isAnimated":{
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "result":"pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "message":"Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type":"test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "name":"test_isAnimated"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "test_stop":{
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "result":"pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "message":"Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type":"test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "name":"test_stop"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "test_onStart":{
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "result":"pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "message":"Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type":"test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "name":"test_onStart"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "test_endValue":{
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "result":"pass",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "message":"Test passed.",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "type":"test",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "name":"test_endValue"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<p>The JUnit XML format outputs results in the following format:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<?xml version="1.0" encoding="UTF-8" ?>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<testsuites>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testsuite name="Y.Anim" failures="0" total="5" time="0.0060">
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testcase name="test_getEl" time="0.0"></testcase>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testcase name="test_isAnimated" time="0.0010"></testcase>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testcase name="test_stop" time="0.0010"></testcase>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testcase name="test_onStart" time="0.0010"></testcase>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <testcase name="test_endValue" time="0.0010"></testcase>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </testsuite>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync</testsuites>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<p>Note that there isn't a direct mapping between YUI Test test suites and JUnit test suites, so some
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncof the hierarchical information is lost.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<p>The TAP format outputs results in the following format:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync```nohighlight
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync#Begin report YUI Test Results (0 failed of 5)
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync#Begin testcase Y.Anim (0 failed of 5)
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncok 1 - testGetServiceFromUntrustedModule
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncok 2 - testGetServiceFromTrustedModule
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncok 3 - testGetServiceFromService
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncok 4 - testGetServiceMultipleTimesFromService
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncok 5 - testGetServiceMultipleTimesFromUntrustedModule
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync#End testcase Y.Anim
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync#End report YUI Test Results
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The XML, JSON, and JUnit XML formats produce a string with no extra white space (white space and indentation shown here is for readability
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync purposes only).</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h2 id="test-reporting">Test Reporting</h2>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>When all tests have been completed and the results object has been returned, you can post those results to a server
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync using a <code>Y.Test.Reporter</code> object. A <code>Y.Test.Reporter</code> object creates a form that is POSTed
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to a specific URL with the following fields:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>results</code> - the serialized results object.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>useragent</code> - the user-agent string of the browser.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>timestamp</code> - the date and time that the report was sent.</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>You can create a new <code>Y.Test.Reporter</code> object by passing in the URL to report to. The results object can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync then be passed into the <code>report()</code> method to submit the results:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar reporter = new Y.Test.Reporter("http://www.yourserver.com/path/to/target");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The form submission happens behind-the-scenes and will not cause your page to navigate away. This operation is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync one direction; the reporter does not get any content back from the server.</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>There are four predefined serialization formats for results objects: </p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.XML</code> (default)</li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.JSON</code></li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.JUnitXML</code></li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <li><code>Y.Test.Format.TAP</code></li>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>The format in which to submit the results can be specified in the <code>Y.Test.Reporter</code> constructor by passing in the appropriate
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <code>Y.Test.Format</code> value (when no argument is specified, <code>Y.Test.Format.XML</code> is used:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncvar reporter = new Y.Test.Reporter("http://www.yourserver.com/path/to/target", Y.Test.Format.JSON);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <h3>Custom Fields</h3>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>You can optionally specify additional fields to be sent with the results report by using the <code>addField()</code> method.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync This method accepts two arguments: a name and a value. Any field added using <code>addField()</code> is POSTed along with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the default fields back to the server:</p>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncreporter.addField("color", "blue");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncreporter.addField("message", "Hello world!");
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <p>Note that if you specify a field name that is the same as a default field, the custom field is ignored in favor of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the default field.</p>