(info) This AI is still in early stages of development.

Unit Tests

Owned by Aubergine
Last updated: Nov 30, 2012Version comment
2 min read
The unit test function, responsible for performing one or more Test Assertions...

 

Syntax

The scope of unit test functions is manipulated before a test runs, so you cannot reference variables defined in the function's scope chain (closures will not work either).

If you want to reference variables external to the Unit Test function, pass them in via a settings object defined in the associated Test() invocation (see Example section below).

function([dataRef]) {
	// code and assertions
}

Parameters

ParameterTypeMandatoryNotesAPI Version
dataRefVariant(error)

You can use the first formal parameter of the function to get a custom-named reference to the testData associated with the unit test.

Note: The test settings will always be available via the testData variable (see Notes section below for details).

1.0

Return value

The return value is not processed.

Notes

Within the unit test, the following variables and properties are available:

Property / VariableTypeNotesAPI Version
_globalObject

A reference to the global object (not scope).

The _global var was added to allow Test API to run independently of Util API. If you don't have Util API installed, you can use _global to get the same effect as global.

1.0
modulePathStringThe modulePath that the test is running in – see Test.module() for more information.1.1
moduleData

Object

Undefined

The data associated with the modulePath, if specified in the Module Lifecycle Object.

If the module doesn't have any data, moduleData will have a value of undefined.

1.1
this.dataVariant

For tests of mode Test.APPEND( ) this will be the testData for the Test.ASYNCH( ) that initiated the current asynchronous test session.

For all other test modes, it will be the testData for the current test – same value as testData variable below...

1.0
testDataVariant

The data associated with the current unit test, if applicable.

Will have a value of undefined if no testData was defined when the unit test was created.

1.0
testNameStringThe name of the current unit test.1.0
testModeObject

An object describing the mode in which the test is being run – for more information see Test API - Dev Notes.

1.0
currentTestObjectA reference to the context of the current test, useful for .call and .apply, etc.1.0

Example

// Define some test data for our unit test
var data = {bar: "fish"};
 
// The test data is passed in as 3rd parameter of the Test() function
// and is accessible via the testData variable
Test("Foo", Test.ANY( ), function() {
	comment( "My first unit test!" );
	// In here, 'data' is undefined as the function is re-scoped
	// to the unit test instance it's running within
	equal( "fish", data.bar, "data.bar == 'fish'?" ); // error: data not defined
	equal( "fish", testData.bar, "testData.bar == 'fish'?" ); // pass
}, data); // <-- test data passed in here
 
// If you wanted to access the testData via a custom named variable,
// specify it's name as the first parameter to the unit test function...
Test("Foo2", Test.ANY( ), function(data) { // <-- custom reference to testData
	comment( "My second unit test!" );
	// Now you can access testData via 'data' parameter
	equal( "fish", data.bar, "data.bar == 'fish'" ); // pass
	// Note that testData variable will still be defined...
    equal( "fish", testData.bar, "testData.bar == 'fish'" ); // pass
}, data);
Availability STABLE

Requires:

Contents

Jump to:

Test API

Topics:

  • Test() — Define a unit test and it's configuration...
  • Test Modules — A test module groups one or more unit tests and provides additional lifecycle settings for those tests...
  • Test Modes — Defines the mode in which a unit test is run...
    • Test.ANY( ) — The most basic unit test mode...
    • Test.EXPECT( ) — Causes the test to fail if it does not generate the specified number of results...
    • Test.ASYNCH( ) — Causes a test to keep running until it either passes, fails or times-out...
    • Test.APPEND( ) — Appends results to a specific asynchronous test session...
  • Unit Tests — The unit test function, responsible for performing one or more Test Assertions...
  • Test Assertions — Assertions are used to perform various tests and annotations within a unit test...
    • comment( ) — Adds a comment to the test results...
    • ok( ) — A simple state checking assertion...
    • hasNative( ) — Assert presence of a native property on the global object...
    • hasFunction( ) — Check if a context has a function property, optionally with specified number of formal parameters...
    • equal( ) — A basic equality checking assertion...
    • notEqual( ) — A basic inequality checking assertion...
    • strictEqual( ) — A strict equality checking assertion...
    • notStrictEqual( ) — A strict inequality checking assertion...
    • deepEqual( ) — A deep equality checking assertion...
    • notDeepEqual( ) — A deep inequality checking assertion...
    • similarTo( ) — A deep similarity checking assertion...
    • notSimilarTo( ) — A deep dissimilarity spotting assertion...
  • Test Signals — Signals are used to prematurely terminate Unit Tests...
    • REQUIRE( ) — Check whether a test or group of tests have passed. If the requirement fails, a RequireSignal will be sent which terminates the current test and marks it as failed.
    • ABORT( ) — Aborts the current test, marking it as failed in the process...
    • FINISH( ) — Terminates the test as if it had finished normally...
  • Test Events — Events defined by Test API...
  • Test Results — After testing is finished, output results...
  • Test API - Dev Notes — Developer notes for this API...