Introduction: Configuration

Ensure tests are passing outside of Wallaby

Before you get started, we recommend ensuring that your tests are executing correctly (and passing) outside of Wallaby. While not strictly necessary, sometimes test environments (especially complex ones - e.g. babel + webpack + browser) are not working before starting Wallaby, which may confuse you into thinking that Wallaby is not working properly when instead the problem is with your tests or test runner configuration.

Automatic configuration

For many testing frameworks and environments Wallaby requires no configuration at all. Automatic configuration is available for projects that are using Jest >= v24, Angular CLI >= v8.2, Vitest, node:test, Vue CLI >= v4, Create-React-App >= v3, and NX Workspaces >= v8.

If automatic configuration for your testing framework is not yet supported, you may continue to use Wallaby with a simple configuration file.

Select your editor

The content of this page is adjusted based on your editor of choice. Please select your editor by clicking on your editor’s logo below before proceeding:

VS Code

To start Wallaby in VS Code you may run Select Configuration command and then select Automatic Configuration <project directory> option once. After that you may keep using Wallaby Start command as usual and it will start Wallaby with automatic configuration.

JetBrains IDEs

To start Wallaby in JetBrains IDEs, you may edit (or create a new) wallaby.js Run Configuration by selecting Edit configurations from the drop-down menu in the top right-hand corner of the navigation bar, or from the Run menu. In the run configuration editor set Configuration Type filed value to Automatic.

Visual Studio

To start Wallaby in Visual Studio, you may use the Start Wallaby.js (Automatic Configuration) context menu item for your project folder in the Solution Explorer. After the first start, the selected project will be remembered for your solution and Wallaby can be started with Tools->Start Wallaby.js (Alt-W, 1).

Sublime Text

To start Wallaby in Sublime Text you may use the Select for Wallaby.js Automatic Configuration context menu item for your project folder in the project’s file tree. After that you may keep using Wallaby Start command as usual and it will start Wallaby with automatic configuration.

Overriding automatic defaults

In order to override any defaults, you may use a Wallaby Configuration file or add a wallaby section to your package.json file.

If you do not have a files or tests array defined in your configuration settings then Wallaby will use Automatic Configuration. If you have a files or tests array defined, then you must specify the autoDetect: true setting to use Automatic Configuration.

package.json

{
  "name": "...",
  ...

  "dependencies": {
    ...
  },

  "devDependencies": {
    ...
  },

  ...

  "wallaby": {
    ...
  }
}

wallaby.js

module.exports = () => ({
   autoDetect: true,
   ...
});

After creating Wallaby config file to override automatic defaults in VS Code you need to run Select Configuration command and then select the config file once. After that you may keep using Wallaby Start command as usual and it will start Wallaby with the configuration file.

After creating Wallaby config file to override automatic defaults in JetBrains IDEs, you may edit (or create a new) wallaby.js Run Configuration by selecting Edit configurations from the drop-down menu in the top right-hand corner of the navigation bar, or from the Run menu. In the run configuration editor set Configuration Type filed value to Configuration File.

Configuration file

Wallaby.js configuration file lists your files/tests and describes the build/setup process for your testing environment.

For example, if you are using a compiler or a module bundler, it needs a configuration for the compiler, such as Babel or TypeScript compiler, or the module bundler, such as Browserify or Webpack.

These things are configured in wallaby.js configuration file, that should be placed to your project root folder. Recommended name is wallaby.js or wallaby.conf.js.

The configuration file is a simple 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'
    ]
    ...
    // for node.js tests you need to set env property as well
    // https://wallabyjs.com/docs/integration/node.html
  };
};

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 run your tests in the latest Chromium/V8 via Electron, or run your tests in PhantomJs, you will also need to specify the env configuration property.

You may read more about various configuration settings, such as files, in the corresponding documentation sections. For example, how to configure wallaby to use Webpack or Babel.

Configuration in package.json

You may use wallaby section in your package.json file to configure Wallaby.js, specify some settings in addition to those specified in your Wallaby config file, or to or override automatic configuration mode defaults:

package.json

{
  "name": "...",
  ...

  "dependencies": {
    ...
  },

  "devDependencies": {
    ...
  },

  ...

  "wallaby": {
    "slowTestThreshold": 200
  }
}

Applying Configuration Changes

Wallaby determines your configuration once, when it first starts. This means that configuration changes will not take effect until Wallaby is next started.