Every test class, except test classes that serve as parents of child tests, has a test function that is responsible for executing the actual test and then calculating and reporting the test result.

The Test Function for a Test Class is set on the test state property for the class. Consider the following example...

EXAMPLE

My2Plus2Equals4TestClass.set ({test:function () {return 2 + 2 == 4}});

In the case of synchronous tests, the Test Result is reported using a return statement. In the case of asynchronous tests, the Test Result is reported by calling a test result callback function. In the axample above, the test result is being calculated using a simple boolean expression, but it is more common to calculate the result using one or more of the available expectation methods. When a test instance is run by calling its run instance method, the test function is called as an instance method on the test instance. This allows the test function to call other instance methods on the instance, such as the expectation methods.

The test result for a test instance, calculated by the test function for a test, indicates whether or not the test has passed.

The test result is automatically set as the value of the result state property for the instance. The boolean value true indicates that a test has passed, while the boolean value false indicates that the test has failed. In the special case of asynchronous tests, the test result can be a special value indicating that the test is asynchronous and is still being executed (see Asynchronous Tests). The Test Result is determined by the test function for a test, and is calculated based upon every expectation of the test function being met.

Every test class can have a unique and descriptive title that can be used to distinguish it from other tests in the log messages of a test runner application, or to help locate the test's code inside a test module when troubleshooting a test's failure.

A title is set for a Test Class by setting the value of its title state property, as shown in the example below...

EXAMPLE

My2Plus2Equals4TestClass.set ({title:'Test that two plus two equals four'});

Now, when a test instance of My2Plus2Equals4TestClass is created, the value of its title state property will automatically be set to the class' value for that property. If the test is part of a test tree and it fails when it is run, then the test synopsis for the test will automatically contain the title for the test, along with the titles of all the tests up the test parent chain, in the test breadcrumbs info. Looking at the synopsis that may be logged by a test runner application, it will be evident which test failed, and where the failed test is in the test tree.

Expectations for a test are expressed using Expectation Methods.

An expectation method is an instance method that can be called on the test instance to test that a particular expectation is met. For example, to test that the result returned by some function is a number, the expectNumber instance method can be used. The Uize.Test module supports a wide variety of expectation methods for testing a wide variety of different types of expectations, such as type expectations, range expectations, and other kinds of expectations.

An expectation method is called as an instance method on the test and is provided with details to qualify the expectation in cases of parameterized expectations (such as a range expectation), along with the value that must meet the expectation. The method returns a boolean value, indicating whether or not the expectation is met. The result of the expectation method call can either be used as the test result, or it can be combined with the result of calling other expectation methods (see the section Compound Expectation). Ultimately, the test function must generate a boolean test result value, indicating whether or not the test passed.

EXAMPLE

My2Plus2Equals4TestClass.set ({test:function () {return this.expect (4,2 + 2)}});

5.1.1. Expectation First, Value Last

myTestInstance.expectInRange (0,100,value);  // expect that value is in range of 0 to 100
myTestInstance.expectType ('number',value);  // expect that value is of type 'number'
myTestInstance.expect ('foo',value);         // expect that value is 'foo'

5.1.2. Different Types of Expectations

A test may have more than one expectation, and these expectations can be built into a single boolean condition.

If multiple calls to expectation methods are chained together into a single boolean expression using the && operator, then the short circuiting behavior of boolean expressions will result in the first expectation that is not met terminating evaluation of the expression. Consider the following example...

EXAMPLE

RandomInRangeTestClass.set ({
  test:function () {
    var result = randomInRange (15,20);
    return this.expectNumber (result) && this.expectInRange (15,20,result);
  }
});

In the above example, a test function is being set for a test class that has been created to test a randomInRange function. The test function calls the randomInRange function, captures the result, and then returns the result of a compound expectation boolean expression. The first expectation is that the result is a number, while the second expectation is that the result is in the range of 15 to 20. If the result is not a number, then the call to the expectNumber instance method will return the value false, causing the boolean expression to terminate evaluation and the expectInRange method would not be called.

Besides simply testing whether or not an expectation is met, the expectation methods also record the reason for a test's failure.

The reason for a test's failure is recorded in the reasonForFailure state property of a test instance. While the value for this property can be set explicitly inside a test function, the value is automatically set when using the expectation methods and when an expectation is not met.

5.3.1. An Example

function add (a,b) {
  return a - b; // <--- OUR FUNCTION HAS A BUG!!!
}

AddFunctionTestClass.set ({test:function () {return add (2,2) == 4}});

AddFunctionTestClass.set ({test:function () {return this.expect (4,add (2,2))});

EXPECTED:

4

ACTUAL:

0

5.3.2. When You'll See the Reason For Failure

When a test is asynchronous, it cannot return the test result in a return statement inside the test function.

Instead, the test function must report the test result using a callback function that is provided to it when it is called. Consider the following example...

EXAMPLE

MyTimeoutTestClass.set ({
  test:function (testResultCallback) {
    var whenTimeoutSet = new Date;
    setTimeout (
      function () {
        testResultCallback (this.expectInRange (1000,Infinity,new Date - whenTimeoutSet));
      },
      1000
    );
  }
});

In the above example, a test function is being set for the test class MyTimeoutTestClass. This test is testing JavaScript's built-in setTimeout function to make sure that the code to be executed at the end of the timeout isn't executed before the timeout duration has elapsed. The test function is, therefore, guaranteed here to be asynchronous.

Now, the time is captured right before the timeout is set and assigned to the whenTimeoutSet variable. The timeout is then set with a duration of 1000 milliseconds. The code executed by the timeout tests that at least a second has elapsed since the timeout was set. It does this by subtracting the value of the whenTimeoutSet variable from the current time, and then using the expectInRange expectation method to test that the elapsed time is in the range of 1000 to Infinity. The test result that is calculated in this way is then "reported" by calling the test result callback function (named testResultCallback here) and passing the result as the single parameter.

Looking at the code in this example, you should notice a few things. First, the test result callback function is passed to the test function as a parameter. If your test function is not asynchronous, then you don't need to declare this parameter. If you do choose to declare the parameter for use in an asynchronous test, you can name it however you like - just refer to it by that name when you use it inside your test function's code. Another thing you'll notice is that the test function has no return statement. Without a return statement, the function will return the value undefined by default. The Uize.Test class interprets this to mean that the test is asynchronous, so there's no need to return a special value or otherwise indicate that the test is asynchronous. Finally, you'll notice that you can still use expectation methods in asynchronous tests - the only difference is that the test result is being calculated at the end of some asynchronous code execution.

6.1.1. isAsync State Property

6.1.2. Uize.Test.isAsync Special Value

A Test Tree is a hierarchical set of tests that allows a multitude tests to be organized in a meaningful way.

7.1.1. Test Parenting

var
  MyTestClass1 = Uize.Test.subclass (),  // this will be used as a child test
  MyTestClass2 = Uize.Test.subclass (),  // this will also be used as a child test
  MyTestClass3 = Uize.Test.subclass ()   // this will be used as a wrapper test
;
MyTestClass3.set ({test:[MyTestClass1,MyTestClass2]});
var myTestClass3Instance = new MyTestClass3;

7.1.2. Root Test

7.1.3. Multiple Occurrences of a Test Class

7.1.4. Test Instance Depth

7.1.5. Total Tests

When a synopsis is generated for a test instance using the getSynopsis method, Test Breadcrumbs are generated to indicate where the test is in a test tree.

The breadcrumbs are generated for an instance by concatenating the titles of all instances up the parent chain to the root test. This can be seen in the test synopsis example.

The code in the example below creates a test tree that is three levels deep, using the basic test declaration factory method (which makes it a bit more concise).

The root test has a single child test, and its child test in turn has a child test (so, it's a grandchild test). The test function for the grandchild test is designed to deliberately fail so that we can see what kind of synopsis is generated in this case. The test fails because we are calling the expect instance method and expecting the string value 'foo', but the actual value being tested against this expectation is 'bar'.

EXAMPLE

var
  MyTestClass = Uize.Test.resolve ({
    title:'This is the root test',
    test:[
      {
        title:'This is a child test',
        test:[
          {
            title:'This is a grandchild test',
            test:function () {return this.expect ('foo','bar')}
          }
        ]
      }
    ]
  }),
  myTestClassInstance = new MyTestClass
;
myTestClassInstance.wire (
  'Done',
  function (e) {if (e.source.get ('reasonForFailure')) alert (e.source.getSynopsis ())}
);
myTestClassInstance.run ();

When the above code is executed, a synopsis as shown below will be displayed in an alert dialog...

SYNOPSIS

FAILED

----------------------------------------------------------

BREADCRUMBS...

This is the root test
  This is a child test
    This is a grandchild test

----------------------------------------------------------

TIME STARTED: Fri Sep 24 2010 16:49:48 GMT-0700 (Pacific Daylight Time)
TIME ENDED: Fri Sep 24 2010 16:49:48 GMT-0700 (Pacific Daylight Time)
DURATION: 10ms

----------------------------------------------------------

REASON FOR FAILURE...

EXPECTED:

'foo'

ACTUAL:

'bar'

Every message logged for a test instance is represented by a log message object, which contains the text of the message along with a timestamp for when the message was logged.

LOG MESSAGE OBJECT

{
  message   : messageSTR,  // the text of the log message
  timestamp : dataOBJ      // the time at which the message was added to the log
}

10.1.1. Log Message Timestamp

function timeBetweenLogEntries (testInstance,entryA,entryB) {
  if (entryA == entryB) return 0;
  var
    log = testInstance.get ('log') || [],
    lastEntryNo = log.length - 1,
    startTime = testInstance.get ('startTime'),
    endTime = testInstance.get ('endTime')
  ;
  return (
    (entryB > lastEntryNo ? endTime : entryB < 0 ? startTime : log [entryB].timestamp) -
    (entryA > lastEntryNo ? endTime : entryA < 0 ? startTime : log [entryA].timestamp)
  );
}

function timeFromPreviousLogEntry (testInstance,entry) {
  return timeBetweenLogEntries (testInstance,entry - 1,entry);
}

function timeTillNextLogEntry (testInstance,entry) {
  return timeBetweenLogEntries (testInstance,entry,entry + 1);
}

It is important to note that the Start and Done test events bubble.

This means that if you wire a handler for either of these events on an instance, and that instance happens to have child tests and is somewhere within a test tree, then the handler you registered will be executed for some instances other than the one on which you wired the handler. In such cases, if you only want to execute the handler code for the instance on which the handler is wired, then you should test the source property of the event object, as follows...

EXAMPLE

var myTestTreeInstance = new MyTestTreeClass;
myTestTreeInstance.wire (
  'Done',
  function (e) {
    if (e.source == myTestTreeInstance) {
      alert ('Executing the test tree is complete');
    }
  }
);
myTestTreeInstance.run ();

In the above example, the alert statement will only be executed one the test instance myTestTreeInstance has completed running - not when any instance within the test tree has completed running.

While a basic test class can be created by subclassing the Uize.Test class and then setting values for the class' state properties, a more convenient approach is to use the Uize.Test.resolve static method.

The Uize.Test.resolve method is the most basic of the available test class factory methods. It accepts a single parameter, being an object that contains values for the state properties of the Uize.Test class.

INSTEAD OF...

var My2Plus2Equals4TestClass = Uize.Test.subclass ();
My2Plus2Equals4TestClass.set ({
  title:'Test that 2 + 2 equals 4',
  test:function () {return this.expect (4,2 + 2)}
});

USE...

Uize.Test.resolve ({
  title:'Test that 2 + 2 equals 4',
  test:function () {return this.expect (4,2 + 2)}
});

The Uize.Test.resolve method returns a Uize.Test subclass, so it can be used for declaring a child test in an array of child tests, as with all the other test class factory methods. For a more in-depth discussion of the Uize.Test.resolve method, consult the reference documentation for the Uize.Test module.

Beyond the basic test declaration factory method, factory methods also exist for creating test classes in a declarative fashion for some fancier types of tests.

Following is an overview of some of the more exotic test class factory methods. For comprehensive documentation on the methods, you should consult the reference for the Uize.Test class.

12.2.1. Required Modules Test

var RequireUizeDataTestClass = Uize.Test.requiredModulesTest ('Uize.Data');

12.2.2. Static Property Test

var
  MathMinTestClass = Uize.Test.staticPropertyTest ('Math.min','function'),
  NumberMaxValueTestClass = Uize.Test.staticPropertyTest ('Number.MAX_VALUE','number')
;

12.2.3. Static Method Test

Uize.Test.staticMethodTest (
  'Uize.capFirstChar',
  [
    ['Many letters, first letter is lowercase','hello','Hello'],
    ['Many letters, first letter is uppercase','Hello','Hello'],
    ['Single letter, lowercase','h','H'],
    ['Single letter, uppercase','H','H'],
    ['Empty string','','']
  ]
);

12.2.4. Test Module Test

uizeDataTestModuleRunner = Uize.Test.testModuleTest ('Uize.Test.Uize.Data');

12.2.5. Test Suite Test

var uizeTestSuite = Uize.Test.testSuite (
  'UIZE JavaScript Framework Unit Tests',
  [
    'Uize.Test.Uize.Data',
    'Uize.Test.Uize',
    'Uize.Test.Uize.Array',
    'Uize.Test.Uize.Array.Order',
    'Uize.Test.Uize.Array.Sort',
    'Uize.Test.Uize.Data.Csv',
    'Uize.Test.Uize.Date',
    // ... ... ... ... ... ...
    // more test modules here
    // ... ... ... ... ... ...
  ]
);

A good convention to follow when naming a test module is to take the name of the module that it tests and prepend a test namespace under which all of your test modules will reside.

For the modules that make up the UIZE JavaScript Framework, test modules are located under the Uize.Test namespace. So, for example, the test module for testing the Uize.Data module lives under the Uize.Test namespace as Uize.Test.Uize.Data. Essentially, the namespace hierarchy of the UIZE JavaScript Framework is replicated under the Uize.Test namespace - excepting, of course, the Uize.Test namespace hierarchy (or you would have video feedback style infinite recursion).

13.1.1. An Example

To examine what the typical contents of a test module looks like, consider the following example...

EXAMPLE

Uize.module ({
  name:'MyCompanySite.Test.MyCompanySite.CommonUtils',
  builder:function () {
    'use strict';

    return Uize.Test.resolve ({
      title:'MyCompanySite.CommonUtils Test',
      test:[
        Uize.Test.requiredModulesTest ('MyCompanySite.CommonUtils'),
        Uize.Test.staticMethodsTest ([
          // ... ... ... ... ... ... ... ...
          // static methods tests go here
          // ... ... ... ... ... ... ... ...
        ])
      ]
    });
  }
});

In the above example, the test module MyCompanySite.Test.MyCompanySite.CommonUtils defines a test class that tests the MyCompanySite.CommonUtils module. The builder function uses the Uize.Test.resolve method to define the test class in a declarative fashion and then returns a reference to the class. The test class has two Child Tests, the first of which tests requiring of the module being tested, and the second of which tests all the module's static methods (you'll have to just imagine the code that replaces those comments).

One thing you'll notice by looking at the code is that the test module is not requiring the module that it is testing - there isn't even a required property in the module declaration (the call to the Uize.module method) in this case. This is because the module being tested will be required dynamically when an instance of the test class is run, as soon as the required modules test is encountered, which happens to be the first test (defined by calling the Uize.Test.requiredModulesTest method). This has the benefit that loading the MyCompanySite.Test.MyCompanySite.CommonUtils test module does not incur loading of the module that it tests - only when the test is run will the module being tested be loaded, as necessary.

The unit tests test suite for the UIZE JavaScript Framework is implemented in the Uize.Test.UnitTests module.

The Uize.Test.UnitTests module is a test module that defines an uber test suite comprised of all the test modules that test individual modules of the framework, and is used by build scripts that automate testing of the framework. If you are looking to create a test suite of unit tests for your own site / application, you can use this module as a reference. You can create your unit tests module under your own test namespace (as MyCompanySite.Test.UnitTests, for example) and model its contents on the contents of the Uize.Test.UnitTests module. Then, whenever you create a new JavaScript module for your site / application, you can create a companion test module and add an entry for it in your unit tests test suite module - a simple matter of adding a line to the file in order to add the test to the sequence of tests performed by the module.