ExampleGroup

A collection of sub-groups and specs describing some behaviour

Requiring

var ExampleGroup = require('nodespec/lib/example-group').ExampleGroup;

In general ExampleGroup should be not be instantiated directly, and instead created using either Nodespec.describe, ExampleGroup.describe or ExampleGroup.context.

Example

nodespec.describe("top level example group", function() {
    this.describe("sub-example group", function() {
        this.before(function() { this.variable = 1 });
        this.context("sub-sub-example group", function() {
            this.example("stuff", function() {
                // ... test
            });
        });
    });
})
Summary
ExampleGroupA collection of sub-groups and specs describing some behaviour
Constructors
ExampleGroup
Properties
childrenList of all subgroups and specs
descriptionThe description of this group
full_descriptionThe full description, parent’s description + this group’s
before_hooksList of all before hooks defined on this group and its parents
after_hooksList of all after hooks defined on this group and its parents
subjectsList of all subjects defined on this group and its parents
Functions
describeCreate a sub-ExampleGroup to describe some behaviour
contextAn alias for ExampleGroup.describe
beforeAdd a before hook to be run before all specs in the group
afterAdd an after hook to be run after all specs in the group
subjectDefine a “subject” that is lazily evaluated and made available to specs
exampleDefine an Example to be executed against this group
execExecute all of the children of this group in sequence.

Constructors

ExampleGroup

function ExampleGroup(description,
options,
definition_fn)

Arguments

description{string} The title of the behaviour being described
options{options} See below
definition_fn{function} The group definition, this will be evaluated with ‘this’ set to the new instance
options.nodespecthe root nodespec function
options.parentthe parent ExampleGroup or nodespec for a top level group
options.deps{options} Constructor function dependency injection
options.deps.ExampleGroupconstructor function for subgroups
options.deps.Exampleconstructor function for specs
options.deps.Resultconstructor function for result collection
options.deps.Contextconstructor function for context
options.deps.SingleResultconstructor function for one result
options.deps.Pendingconstructor function for pending exception

Properties

children

List of all subgroups and specs

Returns

Array(ExampleGroup | Example)

description

The description of this group

Returns

string

full_description

The full description, parent’s description + this group’s

Returns

string

before_hooks

List of all before hooks defined on this group and its parents

Returns

Array(function)

after_hooks

List of all after hooks defined on this group and its parents

Returns

Array(function)

subjects

List of all subjects defined on this group and its parents

Returns

Array(function)

Functions

describe

ExampleGroup.prototype.describe = function(description,
options,
dfn)

Create a sub-ExampleGroup to describe some behaviour

The subgroup will inherit all hooks and subjects of its parent class.

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 subgroup definition

Returns

{ExampleGroup} The newly created example group

context

ExampleGroup.prototype.context = ExampleGroup.prototype.describe

An alias for ExampleGroup.describe

before

ExampleGroup.prototype.before = function(options,
block)

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

Arguments

block{function} The hook definition

See also

Nodespec.before, Nodespec.after, ExampleGroup.after

after

ExampleGroup.prototype.after = function(options,
block)

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

Arguments

block{function} The hook definition

The block is processed in the same way as ExampleGroup.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, Nodespec.after, ExampleGroup.before

subject

ExampleGroup.prototype.subject = function(name,
block)

Define a “subject” that is lazily evaluated and made available to specs

Arguments

[name]{string} Optional variable name, defaults to “subject”
block{function} definition function, returns the subject’s value

Usage

group.describe("group with an instance", function() {
    this.subject(function() { return new MyClass(); });
    // ... tests
});
group.describe("group with fancy tricks", function() {
    this.subject(function() { return new MyClass(this.name); });
    this.subject('name', function() { return "outer name" });
    // ... tests in here have:
    //      context.subject = new MyClass("outer name");
    this.context("with a different name", function() {
        this.subject('name', function() { return "inner name" });
        // ... tests in here have:
        //      context.subject = new MyClass("inner name");
    })
});

Subjects functions are evaluated the first time they are accessed with ‘this’ set to the spec context, additional accesses will refer to the same object.  As seen above, this can be used to create instances that differ in inner contexts easily.

example

ExampleGroup.prototype.example = function(description,
options,
block)

Define an Example to be executed against this group

Arguments

description{string} Behaviour being described
[options]{options} Any additional options to be passed to the Example constructor.
block{function} The spec definition

The example can be defined in either procedural or asynchronous mode.

Procedural Usage

this within the function is bound to the test context

group.example("1 + 1 = 2", function() {
    this.assert.equal(1 + 1, 2);
})

Asynchronous Usage

If the function takes one argument, it is passed the test context and executed asynchronously, to signal completion you must call done().

group.example("1 + 1 = 2", function(test) {
    setTimeout(function() {
        test.assert.equal(1 + 1, 2);
        test.done();
    }, 1000);
});

See also

Example

exec

ExampleGroup.prototype.exec = function(emitter,
callback/*(err, result)*/)

Execute all of the children of this group in sequence.

Arguments

emitter{EventEmitter} events from the execution will be fired on this emitter
callback{function} Callback fired on completion of execution
callback.err{Error} undefined or an exception object
callback.result{<Result>} if err is undefined, this will contain a summary of the test run

Events

groupStart (ExampleGroup)Group is about to be executed
groupComplete (ExampleGroup)Group execution has completed
function ExampleGroup(description,
options,
definition_fn)
ExampleGroup.prototype.describe = function(description,
options,
dfn)
Create a sub-ExampleGroup to describe some behaviour
ExampleGroup.prototype.context = ExampleGroup.prototype.describe
An alias for ExampleGroup.describe
ExampleGroup.prototype.before = function(options,
block)
Add a before hook to be run before all specs in the group
ExampleGroup.prototype.after = function(options,
block)
Add an after hook to be run after all specs in the group
ExampleGroup.prototype.subject = function(name,
block)
Define a “subject” that is lazily evaluated and made available to specs
ExampleGroup.prototype.example = function(description,
options,
block)
Define an Example to be executed against this group
Describes a single piece of behaviour
ExampleGroup.prototype.exec = function(emitter,
callback/*(err, result)*/)
Execute all of the children of this group in sequence.
nodespec.describe = function describe(description,
options,
definition)
Create an ExampleGroup to describe some behaviour
function nodespec(name,
deps)
Create another top-level nodespec container, keyed by name
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
Close