If you are using Jest >= v24, Angular CLI >= v8.2, Vue CLI >= v4, Vitest, node:test, Create-React-App >= v3, or NX Workspaces >= v8 then you may use automatic configuration that allows you to start Wallaby without any configuration.

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 uses Google Chrome (headless) to run tests. If you want to use wallaby.js to run your node.js tests or to run your tests using 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:

• localProjectDir string property which returns the project local folder.
• projectCacheDir string property which returns the project cache folder. Note that wallaby.js uses files from this folder to run tests. It copies the files specified in the files and tests lists from localProjectDir to projectCacheDir.
• compilers property which allows you to access the built-in TypeScript, CoffeeScript and Babel compilers.
• defaults property which allows you to set the default values for file object properties.

Quick links

• If you’re using a language compiled to JavaScript, such as TypeScript or CoffeeScript or a newer version like ES6 or ES7 via Babel, then you may need to configure a compiler.
• If you need to set up your testing framework before running a test, or to configure your testing environment before running tests, then you may need to add a setup function.
• If you are running node.js tests, would like to run your tests using the latest Chromium/V8 via Electron, or need to pass some node or Chrome/PhantomJs flags/Electron options or set environment variables, then you may need to configure a testing environment.
• If you’d like to preprocess some of your files such as templates, convert them to JavaScript to load for your tests, then you may need to configure a preprocessor.
• If you are looking for a sample configuration file for a certain framework/technology that your project is using, check out the collection of our samples.

Auto Detect Configuration Setting

For many testing frameworks and environments Wallaby requires no configuration at all and Wallaby can be started without any configuration settings. However, sometimes you may want to override the default configuration settings or configure Wallaby with specific settings overrides.

The autoDetect property indicates whether Wallaby should automatically detect and configure the testing environment for your project. When set to true (default), Wallaby will attempt to identify whether your testing framework supports automatic configuration.

Wallaby’s automatic detection currently works with angular, jest, vitest, and node:test frameworks. If you are using a different framework, you will need to manually configure your testing environment.

If you are using multiple frameworks that are supported by Wallaby, you can specify the framework you want to use by setting the autoDetect property.

module.exports = function (wallaby) {
  return {
    // Default `true` setting will detect and configure
    // in the following order: ['angular', 'jest', 'vitest', 'node:test']

    // Example override: only detect and configure 'vitest'
    autoDetect: ['vitest']
  };
};

Please note: if files or tests settings are added as an array of strings, then the autoDetect setting default will be false and will need to be explicitly provided (e.g. autoDetect: true).

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: name@version. 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.

Please note: the testFramework setting cannot be used together with the autoDetect setting.

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

Debugging

The trace 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'
    ],

    trace: 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
  };
};

Run Mode (Automatic / On Save)

Wallaby’s runMode settings provides two options for when test runs will be triggered, automatic and onsave. The default mode is automatic and will be used if the setting is not provided. The automatic option makes your current Wallaby session start a test run whenever code is changed in your editor or when code is saved on disk. The onsave option starts a test run ONLY when your code is saved to disk.

You may also change the runMode setting after your Wallaby session has started using editor commands. Please refer to the tutorial for your editor on how to change the run mode after starting Wallaby ( VS Code, JetBrains, Visual Studio, Sublime).

Please note: you may also need to change your editor settings to not save files automatically in order to use this feature.

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

    tests: [
      ...
    ],

    runMode: 'onsave'
  };
};

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

Running all tests when change is not related to any code change

Sometimes a change to one or more project files may not be related to any application or test code (e.g. binary files, and any non-code files that are used by your application/tests).

By default, when a change is not associated with any test or application code, Wallaby run all project tests. You may change this behavior by setting the runAllTestsWhenNoAffectedTests setting to false:

  module.exports = function () {

    return {
      ...
      runAllTestsWhenNoAffectedTests: false
    };
  };

Note that when using jest, vitest, or webpack the default value for runAllTestsWhenNoAffectedTests will be false.

Also note that this setting always behaves runAllTestsWhenNoAffectedTests set to false when using the Smart Start or Exclusive Test Run features.

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 such as this:

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.

Maximum Log Entry Size

By default, wallaby.js truncates logged messages that exceed 16,384 characters in length. You may change the maximum number of characters using the maxLogEntrySize setting:

  module.exports = function () {

    return {
      ...
      maxLogEntrySize: 32768
    };
  };

Maximum Trace Steps

Wallaby.js limits the number of steps that are recorded during a debug session to limit memory and processor use. By default, 999,999 steps are recorded. You may change the maximum number steps to record using the maxTraceSteps setting:

  module.exports = function () {

    return {
      ...
      maxTraceSteps: 2000000
    };
  };

Note: Increasing this setting may negatively impact Wallaby’s memory and CPU usage.

Show last run screen shot

If you are running your tests using Chrome or PhantomJs then you may use an editor command to show a screen shot of the last test that was executed by Wallaby.

This feature may impact Wallaby performance and must be enabled with a setting:

  module.exports = function () {

    return {
      ...
      screenshot: true
    };
  };

Tip: if you want to see a screenshot for a specific test, you may use it.only for that test or else modify just that test after Wallaby has started before using the command.

Stack Traces within console.log

If for some reason you are logging stack traces within console.log messages and you would like the stack traces to be mapped back to your original source code then you may use the mapConsoleMessagesStackTrace setting.

Because this feature can impact Wallaby performance, it must be enabled with a setting:

  module.exports = function () {

    return {
      ...
      mapConsoleMessagesStackTrace: true
    };
  };

Note: because stack traces may be lossy, the original source mapping is limited to file and line (excludes column). If a stack trace entry does not map to files used by Wallaby in your project then the stack trace entry will be omitted.

Resolve getters in output and value explorer

By default, Wallaby doesn’t resolve property getters when logging values to avoid any possible side effects introduced by executing getters code. You may change the default behaviour by using the resolveGetters setting:

module.exports = function () {
  return {
    ...
    resolveGetters: true
  };
};

With the config above, in case of

var a = {
  get b() {
    return 1;
  }
};

a; //?

the output will be { b: 1 }.

Alternatively, to resolve getters when logging values without changing your config, you may use Wallaby auto-expand comment //?+.

Capture Console Log Output

By default, Wallaby will capture and display any console.log values that are executed by your code and tests. This behavior can be changed with the captureConsoleLog setting:

module.exports = function () {
  return {
    ...
    captureConsoleLog: false
  };
};

File Scanning Configuration

By default, Wallaby uses your system’s native file system scanner to efficiently detect file modifications in real-time.

However, if you have issues with the native file system scanner, you configure Wallaby to poll your file system for changes by setting the fileScanMethod configuration option to poll. If you choose to use the polling file system scanner, you can also set the fileScanPollInterval configuration option to specify the interval (in milliseconds) at which the system will poll the file system to detect changes.

module.exports = function () {
  return {
...
    // Override the default scan method to 'poll'
    fileScanMethod: 'poll',

    // Applicable only if fileScanMethod is 'poll'
    // Default is 100ms and binary files will be 3 times less frequent
    fileScanPollInterval: 100,
  };
};

Log Limits

Wallaby has carefully determined various limits that are used when logging values to ensure that logged values are as readable as possible and that processing logged values is not too computationally expensive.

These limits can be overridden by using the logLimits setting:

module.exports = function () {
  return {
    ...
    logLimits: {
      inline: {
        // The depth to log for values displayed inline beside your code
        depth: 5,

        // The maximum number of elements to log for values displayed 
        // inline beside your code
        elements: 5000,
      },
      values: {
        default: {
          // The string length at which strings are truncated within
          // value explorer and log messages
          stringLength: 8192,
        },
        autoExpand: {
          // The string length at which strings are truncated when
          // using the auto-expand feature
          stringLength: 8192,

          // The maximum number of elements to log for values displayed
          // using the auto-expand feature
          elements: 5000,

          // The maximum depth to log for values displayed using the
          // auto-expand feature
          depth: 10,
        }
      }
    }
  };
};

ESM Hooks and Preload Modules

Wallaby provides the ability to specify the ESM hooks and preload modules that are used when running your tests tests.

These settings can be overridden by using the esmHooks and preloadModules settings. For example:

module.exports = () => ({
  ...
  
  esmHooks: [
    'tsx/esm',
  ],

  preloadModules: [
    'tsx/cjs',
  ]
});

Note: currently only applicable for projects using the node:test framework.