Configuration file: Setup

Setup function

If you need to configure your testing framework or sandbox environment before a test run starts, you can use the setup setting (or its alias bootstrap). This allows you to specify a function to be executed just before a test run starts.

 module.exports = function () {
   return {
     files: [
       'src/**/*.js'
     ],

     tests: [
       'test/**/*Spec.js'
     ],

     setup: function (wallaby) {
       // wallaby.testFramework is jasmine/QUnit/mocha object
       wallaby.testFramework.ui('tdd');

       // you can access 'window' object in a browser environment,
       // 'global' object or require(...) something in node environment

       // if you have setup logic that is asynchronous, you can return
       // a `Promise` for Wallaby to wait for before running your tests
       return require('externalDepdency').setupAsync();
     }
   };
 };

The parameter of the function (named wallaby in the code above) has the following functions and properties:

• tests property that contains the list of all test files that wallaby.js knows about.
• testFramework property that contains a reference to the test framework object. The property can be used to configure your test framework before executing tests, for example to change some of its default settings.

The following additional properties are available in node.js environments:

• localProjectDir string property returns the project local folder.
• projectCacheDir string property returns the project cache folder. Note that wallaby.js uses files from this folder to run tests. It copies the files specified in files and tests lists from localProjectDir to projectCacheDir.
• workerId numeric property returns the id of a worker that runs tests. The number is always between 0 and MAX(worker.initial, workers.regular) - 1.
• sessionId is a unique identifier of a test run.

Important: The setup function is executed in the context of the test runner, not in the context of the configuration file.

This means that you cannot use objects/variables defined within the configuration file code. For example, this code:

module.exports = function () {
  var myParam = 'hello from config';
  return {
    files: [
      'src/**/*.js'
    ],

    tests: [
      'test/**/*Spec.js'
    ],

    setup: function (wallaby) {
      console.log(myParam);
    }
  };
};

will output undefined, because myParam will not be defined in the context of the test runner, when the setup function will be executed.

However, because the setup function is executed in the context of the test runner, you can use its environment to initialize it the way you need.

For example, you can access the window object if you are running browser tests or use the global object in case of node.js tests (or the require modules you need).

For a typical scenario of configuring a testing framework before the test run, for example mocha options, the configuration may look as follows:

module.exports = function () {
  return {
    files: [
      'src/**/*.js'
    ],

    tests: [
      'test/**/*Spec.js'
    ],

    setup: function (wallaby) {
      var mocha = wallaby.testFramework;
      mocha.ui('tdd');
      // etc.
    }
  };
};

Teardown function

Please note that the feature described below works only for node.js test runner.

Sometimes you may need to clean up after your tests, and it may be something that you have set up in the setup function and not in your testing frameworks before/after hooks. To do that, wallaby.js supports the teardown function:

module.exports = function () {
  return {
    files: [
      'src/**/*.js'
    ],

    tests: [
      'test/**/*Spec.js'
    ],

    setup: function (wallaby) {
      console.log('Setup');
      console.log('Current worker id: ' + wallaby.workerId);
      console.log('Current session id: ' + wallaby.sessionId);
    },

    teardown: function (wallaby) {
      console.log('Teardown');
      console.log('Current worker id: ' + wallaby.workerId);
      console.log('Current session id: ' + wallaby.sessionId);

      // if you have teardown logic that is asynchronous, you can return
      // a `Promise` for Wallaby to wait for before starting a subsequent
      // test run
      return require('externalDepdency').teardownAsync();
    },

    globalSetupTeardownTimeout: 5000
  };
};

The teardown function will only be invoked if the setup was invoked.

For asynchronous teardown functions, by default, Wallaby will terminate the worker process and start a new worker process if the teardown logic has not been completed within 5000ms. This setting can be overridden by setting globalSetupTeardownTimeout (milliseconds).