Wallaby.js configuration file is a JavaScript file, with a root object containing the properties listed below or exporting a function that returns an object of the same structure.

For example:

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

    tests: [
      'test/**/*Spec.js'
    ]
    ...
  };
};

Please note that by default, wallaby.js is using PhantomJs to run tests. If you want to use wallaby.js to run your node.js tests or to run your tests in Google Chrome, or the latest Chromium/V8 via Electron, you will also need to specify env configuration property.

As wallaby.js JavaScript file is executed in node.js environment, you can require any locally installed modules, and write and execute any code you need. You can also require other configuration files, such as karma or webpack config, to re-use values declared there in a wallaby.js configuration.

The wallaby parameter contains the following properties:

Testing framework setting

The testFramework string property specifies the name and version of the testing framework you are using for your tests. It uses the following format: [email protected]. As an option, you can specify only the name and wallaby.js will use the latest supported version of that framework. For example, the configuration below will load and use the latest supported version of mocha:

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

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

    testFramework: 'mocha'
  };
};

The list of currently supported frameworks/versions is available here.

Delays setting

The delays object property specifies how much time (in milliseconds) wallaby.js should wait before proceeding to the next stage of the automated test run workflow. It’s recommended to skip setting the property and leave it up to wallaby.js to decide what timeouts to use, until you actually encounter a case where you think tuning the delays may help. Depending on how frequently you’d like to run your tests or how powerful your system is, fine-tuning the delays may help to optimize wallaby.js and your system performance.

The run numeric delay property specifies the number of milliseconds to wait before letting wallaby.js automatically run your tests as a result of your code changes.

In the configuration sample below, wallaby.js will wait 0.5 seconds after editing a source file before running any affected tests.

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

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

    delays: {
      run: 500
    }
  };
};

Debug setting

The debug boolean property, when set to true, produces a detailed wallaby.js log viewable in the Wallaby Console. It can be used to investigate any possible issues and can be provided when reporting bugs.

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

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

    debug: true
  };
};

Preserve Comments setting

The preserveComments boolean property specifies whether the wallaby.js instrumented code should retain your code comments. This property value defaults to false. If you need to preserve comments in the instrumented files that wallaby generates (e.g. you are using a runtime library that uses comments in your code as a part of its logic), then set this property to true.

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

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

    preserveComments: true
  };
};

Report console.error as test run error

Wallaby.js reports console output, including console.error calls, for specific tests, but sometimes you may need to always be notified if somewhere in your tests, app or frameworks that you app is using, console.error is called. The reportConsoleErrorAsError boolean property, when set to true, will make your tests be reported as failed, if as a result of a test run some console.error calls were made.

module.exports = function (wallaby) {
  return {
    files: [
      ...
    ],

    tests: [
      ...
    ],

    reportConsoleErrorAsError: true
  };
};

Maximum console messages logged per test

Wallaby.js has a default limit (100) of console messages logged per test. If you see the Number of console messages per test exceeded maximum allowed value message in Wallaby Console and would like to increase the limit, you may use the maxConsoleMessagesPerTest setting.

module.exports = function (wallaby) {
  return {
    files: [
      ...
    ],

    tests: [
      ...
    ],

    maxConsoleMessagesPerTest: 10000
  };
};

Slow tests

Wallaby.js reports slow tests in wallaby.js app. If you would like to set the time above which the executed test duration is reported as slow, you may use the slowTestThreshold setting (the default value is 75 ms).

module.exports = function (wallaby) {
  return {
    files: [
      ...
    ],

    tests: [
      ...
    ],

    slowTestThreshold: 200 // 200 ms
  };
};

Low code coverage level

Wallaby.js reports low code coverage level in wallaby.js app. If you would like to set the value below which the coverage is reported as low, you may use the lowCoverageThreshold setting (the default value is 80 percent).

module.exports = function (wallaby) {
  return {
    files: [
      ...
    ],

    tests: [
      ...
    ],

    lowCoverageThreshold: 70 // 70%
  };
};

Project name

  module.exports = function () {

    return {
      name: 'My Project Name',
      ...
    };
  };

This will change the displayed project name (the project folder name by default) to the My Project Name text in wallaby app.

Excluding file patterns from code coverage calculation

While there’s the instrument flag which can be used to stop some file(s) instrumentation, sometimes you may just need to exclude the file from code coverage calculation, and still be able to see its coverage indicators, inline errors and messages, etc., when it is opened.

You may use the filesWithNoCoverageCalculated setting in these scenarios. For example, the following config will exclude all files that name ends with -helper.js from code coverage calculation:

  module.exports = function () {

    return {
      ...
      filesWithNoCoverageCalculated: ['src/**/*-helper.js']
    };
  };

Unhandled promise rejections

By default, when running in node.js environment, wallaby.js reports all unhandled promise rejections as errors. You may change the behaviour by using the reportUnhandledPromises setting:

  module.exports = function () {

    return {
      ...
      reportUnhandledPromises: false
    };
  };

Note that the default value of the setting in browser environment is false, and you may set it to true if you want to make sure that none fo your code produces unhandled promise rejections.

Running all tests in changed or affected test files

By default, wallaby.js re-runs a minimal set of tests for a code change. For example, if you are changing a particular test, wallaby will only be re-running this test. If you want all tests in the test file to run every time when one/multiple test(s) of the file are affected by your code changes, then you may use the runAllTestsInAffectedTestFile setting.

  module.exports = function () {

    return {
      ...
      runAllTestsInAffectedTestFile: true
    };
  };

Ignoring file loading chains for files dependency tracking purposes

By default, wallaby.js tracks dependencies between source files and test files that import/require those source files. For example, if a test file imports a module:

import a from './aModule'

it('test', () => {
  ...
});

then wallaby may need to re-run the test when aModule file changes, even if the imported a object (or anything from the module, or other modules imported by aModule) is not used in the test file at all. Wallaby works this way because imported modules may contains some logic executed on import (like some program scope logic, importing other modules, etc.) that may potentially break and make the importing test file fail, even though it is not directly testing anything from the module.

If you want to ignore file loading chains for files dependency tracking purposes, so that wallaby only re-runs tests that are directly using affected files exported functionality, then you may use the ignoreFileLoadingDependencyTracking setting:

  module.exports = function () {

    return {
      ...
      ignoreFileLoadingDependencyTracking: true
    };
  };

With the config above, if you have a test file like

import a from './aModule'
import b from './bModule'

it('test', () => {
  expect(B.sayHello()).toBe('hello');
});

and you change the bModule module sayHello function, then the test will re-run. However, if you change anything inside the aModule, the test will not re-run.