Reference

Functions

Properties

Test Suite Formats

Objects

Functions

The following functions are defined under the jsUnity namespace.

attachAssertions ( scope )

Copies all assertion functions that are sub-properties of the assertions property to the given scope. If the scope is omitted, the current (usually global) scope will be used. This can be used to shorten the amount of code that needs to be written when using assertion functions:

jsUnity.attachAssertions();
jsUnity.run(function () {
    function testCondition() {
        assertTrue(condition);
    }
});

compile ( suite )

Compiles the passed in test suite. The test suite can be in several different formats. If the test suite is valid, a TestSuite object is returned. Otherwise, an exception is thrown. This function is idempotent; passing it a TestSuite object returns the same TestSuite object. The returned object can be passed to the run function to run the test suite.

error ( message )

Logs an error. It’s used by jsUnity to report an error (not to be confused with test failures) in running a test suite. It can also be used by the test fixture or the test cases for the logging of debug information. By default, this function is wired to call the log function after prepending "[ERROR] " to the passed in string. You should override this function to provide logging capabilities that’s suitable for the context in which you’re running jsUnity. For example, when running inside HTML, you can output to the document:

jsUnity.error = function (s) {
    document.write("<div class=\"error\">ERROR: "
        + s + "</div>");
};

log ( message )

This function is used by jsUnity to report progress of a test suite run. It can also be used by the test fixture or the tests for the logging of debug information. By default, it doesn’t do anything. You should override this function to provide logging capabilities that’s suitable for the context in which you’re running jsUnity. For example, when running inside HTML, you can output to the document:

jsUnity.log = function (s) {
    document.write("<div>" + s + "</div>");
};

run ( suite, suite, … )

Runs in the passed in test suites. The run function is basically the bare minimum that you need to be able to run a test suite and inspect the results.

Each argument can be a pre-compiled (see compile) TestSuite object or a test suite in one of several different formats. If a test suite is invalid, false is returned. If all test suites can be run successfully, a TestResults object is returned. If multiple test suites are passed, the return will be the cumulative result of all test suites.

Properties

The following properties are defined under the jsUnity namespace.

assertions

The collection of assertion functions that can be used in test cases and also used by the attachAssertions function. This property is set to defaultAssertions by default and can be overridden to use a custom set of assertion functions.

function testCondition() {
    jsUnity.assertions.assertTrue(condition);
}

defaultAssertions

The collection of default assertions functions that come with jsUnity. jsUnity currently comes with the following assertion functions that are inspired by JsUnit and JsUnitTest:

  • assertException
  • assertTrue
  • assertFalse
  • assertIdentical
  • assertNotIdentical
  • assertEqual
  • assertNotEqual
  • assertMatch
  • assertNotMatch
  • assertTypeOf
  • assertNotTypeOf
  • assertInstanceOf
  • assertNotInstanceOf
  • assertNull
  • assertNotNull
  • assertUndefined
  • assertNotUndefined
  • assertNaN
  • assertNotNaN
  • fail

Test Suite Formats

As a convenience, the run function accepts test suites in several different formats. A test suite is a collection of test functions (cases) whose names start with “test”.

Function

A function with inner functions as test cases. When an anonymous outer function is used, the test suite will have no name. When a named outer function is used, the name of the function becomes the test suite name. Inner functions whose names start with “test” are regarded as test cases. Functions setUp and tearDown, when defined, will be called prior and after the call to each test case function.

function myTestSuite() {
    function setUp() {
    }

    function tearDown() {
    }

    function testThis() {
    }
}

var results = jsUnity.run(myTestSuite);

Object

An object with properties as test cases.

var myTestSuite = {
    suiteName: "myTestSuite",

    setUp: function () {
    },

    tearDown: function () {
    },

    testThis: function () {
    }
};

jsUnity.run(myTestSuite);

Array

An array of functions or function names.

function setUp() {
}

function tearDown() {
}

function testThis() {
}

var myTestSuite = [ setUp, tearDown, testThis ];

jsUnity.run(myTestSuite);

Whenever it’s more convenient, an array of function names can be used as well:

var myTestSuite = [ "setUp", "tearDown", "testThis" ];

String

Source code in Function test suite format. This can be useful for loading test suites through AJAX or an iframe.

var myTestSuite = "function () {\
    function testThis() {\
    }\
}";

jsUnity.run(myTestSuite);

Objects

TestSuite ( suiteName, scope )

Object returned by a successful call to the compile function. You can pass custom TestSuite instances to the run function for special needs (for example, programmatically generated tests). The constructor arguments correspond to the suiteName and scope properties below. The properties of the TestSuite object are:

suiteName

The name of this test suite. Can be undefined.

scope

The scope with which the test functions will be called. This is an object that can be referenced as this within test functions.

tests

Array of tests. Each item is an object with the following properties:

name

The name of the test.

fn

The test function.

setUp

The fixture set up function. Can be undefined.

tearDown

The fixture tear down function. Can be undefined.

TestResults

Object returned by a successful call to the run function. The constructor doesn’t take in any arguments. The properties are:

suiteName

The name of the test suite or undefined if an unnamed test suite is used. If multiple test suites are simultaneously passed to run, this will be a comma-delimited list of all test suites.

total

The number of test cases that were run.

passed

The number of test cases that passed.

failed

The number of test cases that failed.

duration

The number of milliseconds it took to run all test cases.