UIZE JavaScript Framework

MODULES Uize.Class.Test

SEARCHEXAMPLESSOURCEDEPSTEST

1. Introduction

The Uize.Class.Test class provides a minimal base class for test classes of various types.

DEVELOPERS: Chris van Rensburg

1.1. Examples

There are no dedicated showcase example pages for the Uize.Class.Test module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Class.Test module...

SEARCH

1.2. Implementation Info

The Uize.Class.Test module defines the Uize.Class.Test class, which is a subclass of Uize.Class.

INHERITANCE CHAIN

Uize.Class −> Uize.Class.Test

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

INSTANCE METHODS

getDepth | getSynopsis | getTotalTests | log | run | stop

STATE PROPERTIES

duration | endTime | inProgress | isAsync | log | progress | reasonForFailure | result | startTime | test | title

STATIC METHODS

Uize.Class.Test.addTest | Uize.Class.Test.isAsync | Uize.Class.Test.resolve

1.2.2. Features Overridden in This Module

The features listed in this section have been overridden in this module.

The module that an overridden feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

valueOf

STATIC METHODS

Uize.Class.Test.set

STATIC PROPERTIES

Uize.Class.Test.moduleName | Uize.Class.Test.nonInheritableStatics

1.2.3. Features Inherited From Other Modules

The features listed in this section have been inherited from other modules.

The module that an inherited feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

fire | get | is | isMet | kill | met | onChange | once | set | toggle | unmet | unwire | whenever | wire

STATIC METHODS

Uize.Class.Test.alphastructor | Uize.Class.Test.declare | Uize.Class.Test.doMy | Uize.Class.Test.dualContextMethods | Uize.Class.Test.dualContextProperties | Uize.Class.Test.fire | Uize.Class.Test.get | Uize.Class.Test.instanceMethods | Uize.Class.Test.instanceProperties | Uize.Class.Test.mixins | Uize.Class.Test.omegastructor | Uize.Class.Test.singleton | Uize.Class.Test.stateProperties | Uize.Class.Test.staticMethods | Uize.Class.Test.staticProperties | Uize.Class.Test.subclass | Uize.Class.Test.toggle | Uize.Class.Test.unwire | Uize.Class.Test.wire

STATIC PROPERTIES

Uize.Class.Test.pathToResources

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Class.Test module.

2. Static Properties

2.1. Uize.Class.Test.isAsync

A read-only special value that is used to indicate that running of a test instance's test(s) is asynchronous.

When a test instance is known to be asynchronous, the instance's result state property will be set to the value Uize.Class.Test.isAsync. In this situation, the instance's isAsync state property will also be set to the value true. For a more in-depth discussion, see the section Asynchronous Tests in the JavaScript Testing Framework guide.

NOTES

see the related isAsync and result state properties

2.2. Uize.Class.Test.moduleName

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

2.3. Uize.Class.Test.nonInheritableStatics

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is not inherited by subclasses

2.4. Uize.Class.Test.pathToResources

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

3. Instance Methods

3.1. fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.2. get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.3. getDepth

Returns an integer, indicating how deep within the test instance tree the test instance is.

SYNTAX

depthINT = myTest.getDepth ();

The depth of a test instance is determined by traversing up the parent chain, all the way up to the root test. The depth of the root test is reported as 0, the depth of a child test of the root test is reported as 1, the depth of a child test of that child test is reported as 2, and so on.

NOTES

see the related parent instance property
see the related getTotalTests instance method

IMPLEMENTATION INFO

this feature was introduced in this module

3.4. getSynopsis

Returns a string, providing a synopsis of the test instance's run.

SYNTAX

synopsisSTR = myTest.getSynopsis ();

This method is useful when providing a report for a test, especially if the test fails. The synopsis provides an indication of whether the test passed or failed, breadcrumbs to indicate where the test is in a test tree, when the test started and ended and its duration, and the reason for failure if the test failed.

NOTES

see also the reasonForFailure and result state properties

IMPLEMENTATION INFO

this feature was introduced in this module

3.5. getTotalTests

Returns an integer, indicating the total number of tests inside the test instance's test tree.

SYNTAX

totalTestsINT = myTest.getTotalTests ();

This method recurses through the entire tree, essentially flattening the tree in order to count the total number of actual tests that would be performed. The method includes parent tests in the tally, along with all child tests. For example, if the test contained two child tests, and each one of those child tests contained two child tests, then the total number of tests in the tree would be 7 - one root test, two child tests, and four grandchild tests.

NOTES

see the related getDepth instance method

IMPLEMENTATION INFO

this feature was introduced in this module

3.6. is

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.7. isMet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.8. kill

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.9. log

IMPLEMENTATION INFO

this feature was introduced in this module

3.10. log Instance Method

Adds the specified message, along with a generated timestamp, to the log array for the instance and returns a reference to the instance.

SYNTAX

myTest = myTest.log (messageSTR);

NOTES

see the related log state property

3.11. met

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.12. onChange

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.13. once

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.14. run

Runs the instance's test(s) and returns the result.

SYNTAX

resultBOOL = myTest.run ();

In the event that running of the instance's test(s) is asynchronous, the run method will return the value Uize.Class.Test.isAsync, and the instance's isAsync state property will be set to the value true. For a more in-depth discussion, see the section Asynchronous Tests in the JavaScript Testing Framework guide.

3.14.1. Callback Function For Asynchronous Tests

When the optional callbackFUNC parameter is specified, a callback function can be specified that will be called once running of the instance's test(s) is complete, in the event that running of the instance's test(s) is asynchronous.

VARIATION

resultBOOL = myTest.run (callbackFUNC);

The callback function should expect to receive one parameter, being the result value for the test.

NOTES

see the companion stop instance method

IMPLEMENTATION INFO

this feature was introduced in this module

3.15. set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.16. stop

Stops running of the test instance's test(s).

SYNTAX

myTest.stop ();

Upon calling the stop method, the stop method will first be called on any child tests belonging to the test, after which the inProgress state property for the instance will be set to false. If the instance is not running its test(s) at the time that this method is called, then calling it will have no effect.

NOTES

see the companion run instance method
see the related inProgress state property

IMPLEMENTATION INFO

this feature was introduced in this module

3.17. toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.18. unmet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.19. unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.20. valueOf

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)

IMPLEMENTATION INFO

3.21. whenever

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.22. wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4. Instance Events

4.1. Done

An bubbling instance event that is fired whenever the instance's test completes running.

NOTES

this event bubbles
see the companion Start instance event

4.2. Start

An bubbling instance event that is fired whenever the instance's test is run by calling its run instance method.

NOTES

this event bubbles
see the companion Done instance event

5. Static Methods

5.1. Uize.Class.Test.addTest

Adds the specified child test to the test class and returns a reference to the test class.

SYNTAX

Uize.Class.Test.addTest (testOBJ);

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

5.2. Uize.Class.Test.alphastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.3. Uize.Class.Test.declare

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.4. Uize.Class.Test.doMy

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.5. Uize.Class.Test.dualContextMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.6. Uize.Class.Test.dualContextProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.7. Uize.Class.Test.fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.8. Uize.Class.Test.get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.9. Uize.Class.Test.instanceMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.10. Uize.Class.Test.instanceProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.11. Uize.Class.Test.isAsync

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

5.12. Uize.Class.Test.mixins

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.13. Uize.Class.Test.omegastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.14. Uize.Class.Test.resolve

Returns a Uize.Class.Test subclass, being the specified test object resolved to a test class.

SYNTAX

testCLASS = Uize.Class.Test.resolve (testOBJ);

5.14.1. testOBJ

An object, being either a set of property values for the state properties of the Uize.Class.Test class, or a reference to a Uize.Class.Test subclass.

In the event that the testOBJ parameter's value is a set of property value, a new subclass of the Uize.Class.Test class is created, and its state properties are initialized with the values contained in the testOBJ object. The value of the test property receives special handling (see Resolving Subtests).

5.14.2. More Concise and Declarative

The Uize.Class.Test.resolve method allows for a more concise, declarative syntax for defining tests.

INSTEAD OF...

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

USE...

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

5.14.3. Returns a Test Class

Because the Uize.Class.Test.resolve method returns a Uize.Class.Test subclass, it can be used for declaring a child test in an array of child tests, as with all the other test class factory methods (see Example 2: A Set of Tests for an illustration of this).

5.14.4. Resolving Subtests

If a test properties object is specified for the testOBJ parameter (rather than a Uize.Class.Test subclass), then the value of that object's test property is further resolved.

If the value of the test property is an array of child tests, then the elements of the child tests array are resolved to test classes by calling the Uize.Class.Test.resolve method for each of them, where each element value becomes the value of the Uize.Class.Test.resolve method's testOBJ parameter. For an example of this type of usage, see the Example 2: A Set of Tests.

5.14.5. Example 1: A Single Test

In this example, a simple test class is being created using the Uize.Class.Test.resolve method.

EXAMPLE

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

The value of the test state property in this case is a function, which will be executed when an instance of the test class is run using the run instance method.

5.14.6. Example 2: A Set of Tests

In this example, a test class is being created that serves as a wrapper for a set of child tests.

EXAMPLE

Uize.Class.Test.resolve ({
  title:'Test a whole bunch of things',
  test:[
    {
      title:'2 + 2 equals 4',
      test:function () {return 2 + 2 == 4}
    },
    Uize.Class.Test.resolve ({
      title:'The value true is equal to 1 in a simple equality test',
      test:function () {return 1 == true}
    })
  ]
});

The value of the test state property in this case is an array, which contains a sequence of child tests. The elements of the child tests array are resolved to test classes (see Resolving Subtests). In this example, the child tests array contains a mix of child tests declared in different ways: the first child test is declared using the simple object syntax, while the second is declared by calling the Uize.Class.Test.resolve method explicitly.

NOTES

this method is one of the many available test class factory methods

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

5.15. Uize.Class.Test.set

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.16. Uize.Class.Test.singleton

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.17. Uize.Class.Test.stateProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.18. Uize.Class.Test.staticMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.19. Uize.Class.Test.staticProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.20. Uize.Class.Test.subclass

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.21. Uize.Class.Test.toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.22. Uize.Class.Test.unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.23. Uize.Class.Test.wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6. State Properties

6.1. duration

A number, representing how long it took for the test instance to run, measured in milliseconds.

Before a test instance has been run for the first time, the value of this property will be undefined. The value will also be reset to undefined each time the test is started, and will remain undefined while the test is in progress.

NOTES

the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

6.2. endTime

An instance of JavaScript's Date object, that is set to the time at which running of the test instance ended.

Before a test instance has been run for the first time, the value of this property will be undefined. The value will also be reset to undefined each time the test is started, and will remain undefined while the test is in progress. The value will be reset to the current time each time the test ends running.

NOTES

see also the companion startTime and duration state properties
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

6.3. inProgress

A boolean, indicating whether or not the test instance is busy running its test(s).

The value of this property is set to true each time the test is started, and is set back to false each time the test ends running.

NOTES

see also the related progress state property
the initial value is false

IMPLEMENTATION INFO

this feature was introduced in this module

6.4. isAsync

A boolean, indicating whether or not running the test instance's test(s) is asynchronous.

The value undefined is equivalent to the boolean value false. When a test is run in the browser context, the value of this property is coerced to true. For a more in-depth discussion, see the section Asynchronous Tests in the JavaScript Testing Framework guide.

NOTES

see the related Uize.Class.Test.isAsync static property
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

6.5. log

An array, containing all of the messages logged using the log Instance Method.

Before a test instance has been run for the first time, the value of this property will be undefined. The value will also be reset to [] (an empty array) each time the test is started. Each element of the log array is an object with the following structure...

LOG MESSAGE OBJECT

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

NOTES

see the related log Instance Method
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

6.6. progress

A floating point number in the range of 0 to 1, indicating how far the test instance is in running its test(s).

Before a test instance has been run for the first time, the value of this property will be 0. The value will also be reset to 0 each time the test is started. The value will be set to the 1 when the test ends running. During running of the test, the value will be updated periodically to reflect the progress that has been made. The progress is calculated by dividing the number of subtests that have completed running by the total number of subtests defined in the test state property. Importantly, the value of this property does not reflect updates in the progress of individual subtests.

NOTES

see also the related inProgress state property

IMPLEMENTATION INFO

this feature was introduced in this module

6.7. reasonForFailure

A string, providing an explanation for why the test failed, or the value undefined if the test has not failed.

Before a test instance has been run for the first time, the value of this property will be undefined. The value will also be reset to undefined each time the test is started, and will remain undefined while the test is in progress. If the test fails, the value of this property can be set to a string that provides an explanation for why the test failed.

NOTES

see also the related result state property
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

6.8. result

A boolean, indicating whether or not the test passed, or the value undefined or Uize.Class.Test.isAsync.

A value of true indicates that the test was completed and passed, while a value of false indicates that the test was completed and failed or was aborted with a catastrophic failure. A value of undefined indicates that the test result has not yet been determined, while a value of Uize.Class.Test.isAsync indicates that determination of the result is waiting upon the completion of asynchronous code.

Before a test instance has been run for the first time, the value of this property will be undefined. The value will also be reset to undefined each time the test is started, and will remain undefined until the result is determined, or will be set to the constant value Uize.Class.Test.isAsync if the test is known to be asynchronous.

NOTES

see also the related reasonForFailure state property
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

6.9. startTime

An instance of JavaScript's Date object, that is set to the time at which running of the test instance started.

Before a test instance has been run for the first time, the value of this property will be undefined. The value will be reset to the current time each time the test is started.

NOTES

see also the companion endTime and duration state properties
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

6.10. test

A test function, or an array of child tests where each element is an instance of a Uize.Class.Test subclass.

6.10.1. The Simple Test Case

In the case of a simple test that has no child tests, the value of the test property should be a reference to the function that performs the test action.

This function will be executed when the test is run by calling the run instance method. When the function is called, it will be called as an instance method of the test instance, so it will have access to the instance for the purpose of calling any of the instance methods of the test class, or for accessing state of the instance through its various state properties.

The function should expect to receive a single parameter, being a continuation function that can be called in case the test is asynchronous (see the section on Asynchronous Tests in the JavaScript Testing Framework guide for more details). In the case of synchronous tests, the test function should return a boolean value, indicating whether the test passed or failed.

6.10.2. The Child Tests Case

In the case of a test that is serving as a parent for a set of child tests, the value of the test property will be an array of child test instances.

In such cases, when the test is run all of its child tests contained in the test array will be executed in sequence. If any of the child tests fail, execution of the remaining child tests will be terminated.

IMPLEMENTATION INFO

this feature was introduced in this module

6.11. title

A string, representing the title of the test instance.

The title of a test is used when generating a synopsis for a test using the getSynopsis instance method. The title can also be used by a test runner application whose interface provides logging for tests as they are being run.

IMPLEMENTATION INFO

this feature was introduced in this module

7. Instance Properties

7.1. children

An array of child tests where each element is an instance of a Uize.Class.Test subclass.

A test instance contains children when its test state property is an array. When its test state property is not an array, children will be undefined.

NOTES

the children array is read-only - its contents should not be directly modified
the initial value is undefined
see also related test state property
see also the related parent instance property

7.2. parent

A reference to the test class instance that serves as the parent for the test instance.

A test instance is parented when it is instantiated by its parent test. The root test in a test tree is never parented, and so the value of the parent property for the root test remains undefined.

NOTES

the initial value is undefined
see also the related children instance property