nodespec module

The top-level container object for the nodespec test suite.

Requiring

var nodespec = require('nodespec');

The nodespec module when included functions as the collection for all example groups and behaviours you wish to describe in your system, each module that wants to describe tests should require nodespec and use the describe method to describe groups of examples.

Normal usage

var nodespec = require('nodespec');
nodespec.describe("test behaviour", function() {
    // ... test definitions here
});
nodespec.exec();

Advanced usage

As well as acting like a singleton for the test suite, it is also callable as a factory-style method if more than one top-level container per script execution is needed for some reason (see nodespec).

var nodespec1 = require('nodespec')("top-level 1");
var nodespec2 = require('nodespec')("top-level 2");
Summary
nodespec moduleThe top-level container object for the nodespec test suite.
Functions
nodespecCreate another top-level nodespec container, keyed by name
NodespecMethods attached to the module
Functions
abandonForget this nodespec function
requireRequire nodespec test definition files without executing them
describeCreate an ExampleGroup to describe some behaviour
beforeAdd a before hook to be run before all specs in the suite
afterAdd an after hook to be run after all specs in the suite
mockWithLoad a pre-defined mocking library
registerFormatterAdd an additional formatter
execRun all specs currently defined for this suite

Functions

nodespec

function nodespec(name,
deps)

Create another top-level nodespec container, keyed by name

Note that this function is not a method of the nodespec module, it is the callable module itself.

Arguments

name{string} Name for the separate context, subsequent calls with the same name will return the same object
deps{options} Allows for dependency injection of constructor functions, omitted keys will fall back to defaults
deps.ExampleGroupdefaults to ExampleGroup
deps.Exampledefaults to Example
deps.Contextdefaults to <Context>
deps.Resultdefaults to <Result>
deps.SingleResultdefaults to <SingleResult>
deps.Pendingdefaults to <Pending>
deps.ExpectationErrordefaults to assert.AssertionError

Returns

{function} A new Nodespec function, which is still callable as nodespec

Usage

var nodespec = require("nodespec");
var separate_nodespec = nodespec("separate stack",
                                 {Context: AugmentedContext})

See Also

Nodespec.abandon

Nodespec

Methods attached to the module

Summary
Functions
abandonForget this nodespec function
requireRequire nodespec test definition files without executing them
describeCreate an ExampleGroup to describe some behaviour
beforeAdd a before hook to be run before all specs in the suite
afterAdd an after hook to be run after all specs in the suite
mockWithLoad a pre-defined mocking library
registerFormatterAdd an additional formatter
execRun all specs currently defined for this suite

Functions

abandon

nodespec.abandon = function abandon()

Forget this nodespec function

Subsequent calls to nodespec() with the same name as this instance will return a fresh instance instead of the usual behaviour.

Example

var nodespec = require('nodespec');
var another = nodespec('another');
another.abandon();
var again = nodespec('another');
another !== again;

require

nodespec.require = function require(target)

Require nodespec test definition files without executing them

This function is currently the recommended way to load a test suite that spans multiple files and then executing it all at once.  See the example below.

Arguments

target{string} The path to load, as with the usual nodejs require function

Example

// Note that glob isn't an actual built-in NodeJS function
var files = glob('spec/*_spec.js');
for (var i in files) {
   nodespec.require(files[i]);
}

describe

nodespec.describe = function describe(description,
options,
definition)

Create an ExampleGroup to describe some behaviour

Arguments

description{string} The title of the behaviour being described
[options]{options} Any additional options to be passed to the ExampleGroup constructor.
definition{function} The group definition

Returns

{ExampleGroup} The newly created example group

before

nodespec.before = function before(block)

Add a before hook to be run before all specs in the suite

Arguments

block{function} The hook definition

The block will be executed before each spec on a fresh context, any exceptions or failed assertions will be treated as belonging to the spec being executed.  The function can be defined in either procedural or asynchronous mode.

Procedural Usage

this within the function is bound to the test context, the following example makes ’value’ available in every test as this.variable.

nodespec.before(function() {
    this.variable = 'value';
})

Asynchronous Usage

If the function takes one argument, it is passed the test context and executed asynchronously, to signal completion you must call done().  The following example makes the value returned by the async function available to every test as this.variable.

    nodespec.before(function(hook) {
        async_function(function(err, value) {
            hook.variable = value;
            hook.done();
        });
    });

See also

    <Nodespec.after>, <ExampleGroup.before>, <ExampleGroup.after>

after

nodespec.after = function after(block)

Add an after hook to be run after all specs in the suite

Arguments

block{function} The hook definition

The block is processed in the same way as <nodespec.before>, with one difference: if an assertion fails or an error is thrown in an after block, all other after blocks will still be run.

See also

Nodespec.before

mockWith

nodespec.mockWith = function mockWith(lib)

Load a pre-defined mocking library

Arguments

lib{string} The name of a supported mocking library

Supported libraries

sinonProvides a sinon sandbox to each test as context.sinon (http://sinonjs.org).

registerFormatter

nodespec.registerFormatter = function registerFormatter(name,
file,
set_default)

Add an additional formatter

Arguments

name{string} Name of formatter
file{string} Module path to require, expected to export `Formatter`
set_default{boolean} Make this the default formatter

exec

nodespec.exec = function exec()

Run all specs currently defined for this suite

Note that this function will conclude with a call to process.exit

function nodespec(name,
deps)
Create another top-level nodespec container, keyed by name
nodespec.abandon = function abandon()
Forget this nodespec function
nodespec.require = function require(target)
Require nodespec test definition files without executing them
nodespec.describe = function describe(description,
options,
definition)
Create an ExampleGroup to describe some behaviour
A collection of sub-groups and specs describing some behaviour
nodespec.before = function before(block)
Add a before hook to be run before all specs in the suite
nodespec.after = function after(block)
Add an after hook to be run after all specs in the suite
nodespec.mockWith = function mockWith(lib)
Load a pre-defined mocking library
nodespec.registerFormatter = function registerFormatter(name,
file,
set_default)
Add an additional formatter
nodespec.exec = function exec()
Run all specs currently defined for this suite
Describes a single piece of behaviour
Methods attached to the module
Close