Advanced Test Options

This example begins by creating a namespace and a Y.Test.Case object:

Y.namespace("example.test");
Y.example.test.AdvancedOptionsTestCase = new Y.TestCase({
    name: "Advanced Options Tests"
});

This Y.Test.Case serves as the basis for this example.

Using _should

Immediately after the name 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.example.test.AdvancedOptionsTestCase = new Y.TestCase({

    //the name of the test case - if not provided, one is automatically generated
    name: "Advanced Options Tests",

    /*
     * Specifies tests that "should" be doing something other than the expected.
     */
    _should: {

        /*
         * Tests listed in here should fail, meaning that if they fail, the test
         * has passed. This is used mostly for YuiTest to test itself, but may
         * be helpful in other cases.
         */
        fail: {

            //the test named "testFail" should fail
            testFail: true

        },

        /*
         * Tests listed here should throw an error of some sort. If they throw an
         * error, then they are considered to have passed.
         */
        error: {

            /*
             * You can specify "true" for each test, in which case any error will
             * cause the test to pass.
             */
            testGenericError: true,

            /*
             * You can specify an error message, in which case the test passes only
             * if the error thrown matches the given message.
             */
            testStringError: "I'm a specific error message.",
            testStringError2: "I'm a specific error message.",

            /*
             * You can also specify an error object, in which case the test passes only
             * if the error thrown is on the same type and has the same message.
             */
            testObjectError: new TypeError("Number expected."),
            testObjectError2: new TypeError("Number expected."),
            testObjectError3: new TypeError("Number expected.")

        },

        /*
         * Tests listed here should be ignored when the test case is run. For these tests,
         * setUp() and tearDown() are not called.
         */
        ignore : {

            testIgnore: true

        }
    },

    ...
});

This Y.Test.Case specifies one test that should fail, six that should throw an error, and one that should be ignored.

In the 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.

Moving on to the 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.

The last section is 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

The next part of the example contains the actual test methods. Since each test method is specified as having a certain behavior in _should, they each do something to show their particular functionality.

The first method is testFail(), which does nothing but purposely fail. Since this method is specified as one that should fail, it means that this test will pass:

Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({

    //the name of the test case - if not provided, one is automatically generated
    name: "Advanced Options Tests",

    ...

    testFail : function() {

        //force a failure - but since this test "should" fail, it will pass
        Y.Assert.fail("Something bad happened.");

    },

    ...
});

This method uses 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.

Next, the test methods that should error are defined. The 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:

Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({

    //the name of the test case - if not provided, one is automatically generated
    name: "Advanced Options Tests",

    ...

    testGenericError : function() {
        throw new Error("Generic error");
    },

    ...
});

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, testStringError() and testStringError2() are specified as throwing an error with a specific message ("I'm a specific error message."):

Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({

    //the name of the test case - if not provided, one is automatically generated
    name: "Advanced Options Tests",

    ...

    testStringError : function() {

        //throw a specific error message - this will pass because it "should" happen
        throw new Error("I'm a specific error message.");
    },

    testStringError2 : function() {

        //throw a specific error message - this will fail because the message isn't expected
        throw new Error("I'm a specific error message, but a wrong one.");
    },

    ...
});

The 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.

To be more specific, testObjectError(), testObjectError2(), and testObjectError3(), specified an error type (TypeError) and an error messsage ("Number expected."):

Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({

    //the name of the test case - if not provided, one is automatically generated
    name: "Advanced Options Tests",

    ...

    testObjectError : function() {

        //throw a specific error and message - this will pass because it "should" happen
        throw new TypeError("Number expected.");
    },

    testObjectError2 : function() {

        //throw a specific error and message - this will fail because the type doesn't match
        throw new Error("Number expected.");
    },

    testObjectError3 : function() {

        //throw a specific error and message - this will fail because the message doesn't match
        throw new TypeError("String expected.");
    },

    ...
});

Of the these three methods, only 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.

The last method in the Y.Test.Case is testIgnore(), which is specified to be ignored. To be certain, this method pops up a message:

Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({

    //the name of the test case - if not provided, one is automatically generated
    name: "Advanced Options Tests",

    ...

    testIgnore : function () {
        alert("You'll never see this.");
    }
});

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 Y.Console when a test is ignored.

Running the tests

With all of the tests defined, the last step is to run them:

//create the console
(new Y.Test.Console({
    verbose : true,
    newestOnTop : false
})).render('#testLogger');

//add the test suite to the runner's queue
Y.Test.Runner.add(Y.example.test.AdvancedOptionsTestCase);

//run the tests
Y.Test.Runner.run();

Before running the tests, it's necessary to create a 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

<div id="testLogger"></div>

<script>
YUI().use('node', 'test-console', 'test', function (Y) {

    Y.namespace("example.test");

    Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({

        //the name of the test case - if not provided, one is automatically generated
        name: "Advanced Options Tests",

        /*
         * Specifies tests that "should" be doing something other than the expected.
         */
        _should: {

            /*
             * Tests listed in here should fail, meaning that if they fail, the test
             * has passed. This is used mostly for YuiTest to test itself, but may
             * be helpful in other cases.
             */
            fail: {

                //the test named "testFail" should fail
                testFail: true

            },

            /*
             * Tests listed here should throw an error of some sort. If they throw an
             * error, then they are considered to have passed.
             */
            error: {

                /*
                 * You can specify "true" for each test, in which case any error will
                 * cause the test to pass.
                 */
                testGenericError: true,

                /*
                 * You can specify an error message, in which case the test passes only
                 * if the error thrown matches the given message.
                 */
                testStringError: "I'm a specific error message.",
                testStringError2: "I'm a specific error message.",

                /*
                 * You can also specify an error object, in which case the test passes only
                 * if the error thrown is on the same type and has the same message.
                 */
                testObjectError: new TypeError("Number expected."),
                testObjectError2: new TypeError("Number expected."),
                testObjectError3: new TypeError("Number expected.")

            },

            /*
             * Tests listed here should be ignored when the test case is run. For these tests,
             * setUp() and tearDown() are not called.
             */
            ignore : {

                testIgnore: true

            }
        },

        //-------------------------------------------------------------------------
        // Basic tests - all method names must begin with "test"
        //-------------------------------------------------------------------------

        testFail : function() {

            //force a failure - but since this test "should" fail, it will pass
            Y.Assert.fail("Something bad happened.");

        },

        testGenericError : function() {
            throw new Error("Generic error");
        },

        testStringError : function() {

            //throw a specific error message - this will pass because it "should" happen
            throw new Error("I'm a specific error message.");
        },

        testStringError2 : function() {

            //throw a specific error message - this will fail because the message isn't expected
            throw new Error("I'm a specific error message, but a wrong one.");
        },

        testObjectError : function() {

            //throw a specific error and message - this will pass because it "should" happen
            throw new TypeError("Number expected.");
        },

        testObjectError2 : function() {

            //throw a specific error and message - this will fail because the type doesn't match
            throw new Error("Number expected.");
        },

        testObjectError3 : function() {

            //throw a specific error and message - this will fail because the message doesn't match
            throw new TypeError("String expected.");
        },

        testIgnore : function () {
            alert("You'll never see this.");
        }

    });


    //create the console
    (new Y.Test.Console({
        newestOnTop : false,
        style: 'block' // to anchor in the example content
    })).render('#testLogger');

    Y.Test.Runner.add(Y.example.test.AdvancedOptionsTestCase);

    //run the tests
    Y.Test.Runner.run();
});

</script>