A collection of sub-groups and specs describing some behaviour
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.
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 }); }); }); })
ExampleGroup | A collection of sub-groups and specs describing some behaviour |
Constructors | |
ExampleGroup | |
Properties | |
children | List of all subgroups and specs |
description | The description of this group |
full_description | The full description, parent’s description + this group’s |
before_hooks | List of all before hooks defined on this group and its parents |
after_hooks | List of all after hooks defined on this group and its parents |
subjects | List of all subjects defined on this group and its parents |
Functions | |
describe | Create a sub-ExampleGroup to describe some behaviour |
context | An alias for ExampleGroup.describe |
before | Add a before hook to be run before all specs in the group |
after | Add an after hook to be run after all specs in the group |
subject | Define a “subject” that is lazily evaluated and made available to specs |
example | Define an Example to be executed against this group |
exec | Execute all of the children of this group in sequence. |
function ExampleGroup( description, options, definition_fn )
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.nodespec | the root nodespec function |
options.parent | the parent ExampleGroup or nodespec for a top level group |
options.deps | {options} Constructor function dependency injection |
options.deps.ExampleGroup | constructor function for subgroups |
options.deps.Example | constructor function for specs |
options.deps.Result | constructor function for result collection |
options.deps.Context | constructor function for context |
options.deps.SingleResult | constructor function for one result |
options.deps.Pending | constructor function for pending exception |
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.
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 |
{ExampleGroup} The newly created example group
ExampleGroup.prototype.context = ExampleGroup.prototype.describe
An alias for ExampleGroup.describe
ExampleGroup.prototype.after = function( options, block )
Add an after hook to be run after all specs in the group
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.
ExampleGroup.prototype.subject = function( name, block )
Define a “subject” that is lazily evaluated and made available to specs
[name] | {string} Optional variable name, defaults to “subject” |
block | {function} definition function, returns the subject’s value |
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.
ExampleGroup.prototype.example = function( description, options, block )
Define an Example to be executed against this group
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.
this within the function is bound to the test context
group.example("1 + 1 = 2", function() { this.assert.equal(1 + 1, 2); })
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); });
ExampleGroup.prototype.exec = function( emitter, callback/*(err, result)*/ )
Execute all of the children of this group in sequence.
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 |
groupStart (ExampleGroup) | Group is about to be executed |
groupComplete (ExampleGroup) | Group execution has completed |
function ExampleGroup( description, options, definition_fn )
Create a sub-ExampleGroup to describe some behaviour
ExampleGroup.prototype.describe = function( description, options, dfn )
An alias for ExampleGroup.describe
ExampleGroup.prototype.context = ExampleGroup.prototype.describe
Add a before hook to be run before all specs in the group
ExampleGroup.prototype.before = function( options, block )
Add an after hook to be run after all specs in the group
ExampleGroup.prototype.after = function( options, block )
Define a “subject” that is lazily evaluated and made available to specs
ExampleGroup.prototype.subject = function( name, block )
Define an Example to be executed against this group
ExampleGroup.prototype.example = function( description, options, block )
Execute all of the children of this group in sequence.
ExampleGroup.prototype.exec = function( emitter, callback/*(err, result)*/ )
Create an ExampleGroup to describe some behaviour
nodespec.describe = function describe( description, options, definition )
Create another top-level nodespec container, keyed by name
function nodespec( name, deps )
Add a before hook to be run before all specs in the suite
nodespec.before = function before( block )
Add an after hook to be run after all specs in the suite
nodespec.after = function after( block )