QUnit.module()


QUnit.module( name [, hooks ] [, nested ] )

Description: Group related tests under a single label.

You can use the module name to organize, select, and filter tests to run.

All tests inside a module callback function will be grouped into that module. The test names will all be preceded by the module name in the test results. Other modules can be nested inside this callback function, where their tests' names will be labeled by their names recursively prefixed by their parent modules.

If QUnit.module is defined without a nested callback argument, all subsequently defined tests will be grouped into the module until another module is defined.

Modules with grouped test functions allow defining nested modules, and QUnit will run tests on the parent module before going deep on the nested ones, even if they're declared first. The beforeEach and afterEach callbacks on a nested module call will stack (LIFO - last in, first out) to the parent hooks.

You can specify code to run before and after each test using the hooks argument, and also to create properties that will be shared on the context of each test. Any additional properties on the hooks object will be added to that context. The hooks argument is still optional if you call QUnit.module with a callback argument.

The module's callback is invoked with the test environment as its this context, with the environment's properties copied to the module's tests, hooks, and nested modules. Note that changes on tests' this won't affect sibling tests, where this will be reset to the same value for each test.

DEPRECATION Note: beforeEach and afterEach were previously named setup and teardown, which still exist and will be removed in QUnit 2.0.0.

Examples:

Use the QUnit.module() function to group tests together:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
QUnit.module( "group a" );
QUnit.test( "a basic test example", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.test( "a basic test example 2", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.module( "group b" );
QUnit.test( "a basic test example 3", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.test( "a basic test example 4", function( assert ) {
assert.ok( true, "this test is fine" );
});

Use the QUnit.module() function to group tests together:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
QUnit.module( "module a", function() {
QUnit.test( "a basic test example", function( assert ) {
assert.ok( true, "this test is fine" );
});
});
QUnit.module( "module b", function() {
QUnit.test( "a basic test example 2", function( assert ) {
assert.ok( true, "this test is fine" );
});
QUnit.module( "nested module b.1", function() {
// This test will be prefixed with the following module label:
// "module b > nested module b.1"
QUnit.test( "a basic test example 3", function( assert ) {
assert.ok( true, "this test is fine" );
});
});
});

A sample for using the beforeEach and afterEach callbacks

1
2
3
4
5
6
7
8
QUnit.module( "module A", {
beforeEach: function() {
// prepare something for all following tests
},
afterEach: function() {
// clean up after each test
}
});

Hooks share the same context as their respective test

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
QUnit.module( "Machine Maker", {
beforeEach: function() {
this.maker = new Maker();
this.parts = [ "wheels", "motor", "chassis" ];
}
});
QUnit.test( "makes a robot", function( assert ) {
this.parts.push( "arduino" );
assert.equal( this.maker.build( this.parts ), "robot" );
assert.deepEqual( this.maker.made, [ "robot" ] );
});
QUnit.test( "makes a car", function( assert ) {
assert.equal( this.maker.build( this.parts ), "car" );
this.maker.duplicate();
assert.deepEqual( this.maker.made, [ "car", "car" ] );
});

Hooks stack on nested modules

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
QUnit.module( "grouped tests argument hooks", function( hooks ) {
hooks.beforeEach( function( assert ) {
assert.ok( true, "beforeEach called" );
} );
hooks.afterEach( function( assert ) {
assert.ok( true, "afterEach called" );
} );
QUnit.test( "call hooks", function( assert ) {
assert.expect( 2 );
} );
QUnit.module( "stacked hooks", function( hooks ) {
// This will run after the parent module's beforeEach hook
hooks.beforeEach( function( assert ) {
assert.ok( true, "nested beforeEach called" );
} );
// This will run before the parent module's afterEach
hooks.afterEach( function( assert ) {
assert.ok( true, "nested afterEach called" );
} );
QUnit.test( "call hooks", function( assert ) {
assert.expect( 4 );
} );
} );
} );