QUnit.module()

Categories: Test

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

Description: Group related tests under a single label.

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

    • name
      Type: String
      Label for this group of tests.
    • hooks
      Callbacks to run during test execution.
      • before
        Type: Function()
        Runs before the first test.
      • beforeEach
        Type: Function()
        Runs before each test.
      • afterEach
        Type: Function()
        Runs after each test.
      • after
        Type: Function()
        Runs after the last test. If additional tests are defined after the module's queue has emptied, it will not run this hook again.
    • nested
      Type: Function( Object hooks )
      A callback with grouped tests and nested modules to run under the current module 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 test group functions allow you to define nested modules, and QUnit will run tests on the parent module before going deep on the nested ones, even if they're declared first. Additionally, any hook callbacks on a parent module will wrap the hooks on a nested module. In other words, before and beforeEach callbacks will form a queue while the afterEach and after callbacks will form a stack.

You can specify code to run before and after tests using the hooks argument, and also to create properties that will be shared on the testing context. 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 are not preserved between sibling tests, where this will be reset to the initial value for each test.

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 before, beforeEach, afterEach, and after callbacks

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
QUnit.module( "module A", {
  before: function() {
    // prepare something once for all tests
  }
  beforeEach: function() {
    // prepare something before each test
  },
  afterEach: function() {
    // clean up after each test
  },
  after: function() {
    // clean up once after all tests are done
  }
});

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 );
    } );
  } );
} );