Wallaby.js Configuration file: Files and tests

Properties

Files

The files array property specifies an array of source files or file name patterns.

In browser, the files will be loaded in the test sandbox in the order specified. If the loading of one of your scripts depends on another, you should list the second one before the first one. If you have a configuration file for Karma runner or runner HTML page, you can use the order of files from there.

Files may be of any type, not just JavaScript files, but also CSS files, JSON files, images and other types of files.

Make sure that all files used by your tests are listed in the config files list. Wallaby.js uses its own cache to process/instrument files and run tests, so it has to copy used files there. For example, if you are loading some .json files from your source code or tests (dynamically from browser tests or require('...') in node.js), they have to be included in the files list.

There are few exceptions from the rule:

unless you have a specific use-case, the node_modules folder does not need to be included in the files list, because wallaby uses the local version of it.
if you are using a module bundler for browser tests, such as webpack or browserify you do not need to include folders with your external modules in the files list (unless you would like to load some modules globally as opposed to require/import them).
if you are using a middleware function for your browser tests and making an embedded web server to some of your local folders with libraries, like node_modules, then you do not need to include those folders in the files list.

Tests

The tests array property specifies an array of test files or test file name patterns. IMPORTANT: only actual test files should be specified in the tests list, i.e. the files with specs/tests (for example with describe/it for mocha/jasmine). Any test helpers or testing frameworks extensions should be specified in the files list (normally at the end of the list).

Both files and tests paths are specified relative to the location of the wallaby.js configuration file.

For example, the configuration sample below makes wallaby.js track all .js files in the src folder, as well as a CSS file and an HTML file. The sample also includes all test files from the test folder whose name ends with Spec.

{
  "files": [
    "style/calculator.css",
    "html/calculator.html",
    "src/**/*.js"
  ],

  "tests": [
    "test/**/*Spec.js"
  ]
}

Files and tests are the only mandatory configuration properties; the rest are optional. (Please note that jasmine v3 is the default testing framework.)

Both files and tests properties support glob patterns, so you can use wildcards, etc. to avoid specifying each and every file.

File object

Both files and tests property elements can either be a string representing a file name/name pattern, or an object that defines additional properties.

module.exports = function (wallaby) {
  return {
    files: [
      'src/**/*.js',
      // is the same as
      { pattern: 'src/**/*.js', instrument: true, load: true, ignore: false }
    ],

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

Pattern

The pattern string property represents the file name or pattern. Each file is checked against patterns from the top of the list to the bottom. If a file satisfies multiple patterns, the first file configuration (from the top of the list) with a matching pattern will be used for the file. The rule applies to all file configuration properties, except the ignore property - if a file pattern is marked as ignored, it will be ignored regardless of its position in the files/tests list.

Ignore

The ignore boolean property (false by default) is used to completely exclude the file from being processed by wallaby.js. The setting may be useful for adjusting some broader patterns. Note that if you’d like to ignore a file, you can also just add an exclamation mark as the first character of the path to negate the ignore property (which is false by default). For example, if your tests are in the same folder as your source files, your config may look as follows:

{
  "files": [
    "src/**/*.js",
    "!src/**/*Spec.js"
  ],

  "tests": [
    "src/**/*Spec.js"
  ]
}

Instrument

The instrument boolean property (true by default) determines whether the file is instrumented. Setting the property to false stops the file from being compiled, disables file code coverage reporting, and prevents file changes from triggering automatic test execution. The setting should normally be set to false for libraries, utils and other rarely changing files. Using the setting makes wallaby.js run your code faster, as it doesn’t have to perform unnecessary work.

module.exports = function (wallaby) {
  return {
    files: [
      { pattern: 'libs/jquery.js', instrument: false }
    ],

    ...
  };
};

Sometimes you may just need to exclude a file from code coverage calculation, or disable code coverage for certain functions, statements or logical branches.

Load

The load boolean property (default value: true) determines whether the file is loaded to the sandbox HTML (via the script tag in case of JavaScript files). Setting the property to false is useful if you are using some alternative script loading mechanism, such as RequireJs or Webpack/Browserify.

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

    ...
  };
};

Note that if your browser tests or code load some files dynamically and you don’t want them to be loaded into your sandbox immediately via script tags, you still need them in your files list, with load: false flag so that wallaby.js can serve them on its embedded web server.

Binary

The binary boolean property (false by default) tells wallaby whether the file is binary (this affects how the file gets copied to wallaby cache). While in most cases wallaby is able to figure it out automatically, the flag can be useful when your binary file extension is not a well-known binary file extension, like images or archives.

module.exports = function (wallaby) {
  return {
    files: [
      { pattern: 'src/**/*.myBinaryExt', binary: true }
    ],

    ...
  };
};

hideFromErrorStackTrace

The hideFromErrorStackTrace boolean property (false by default) tells wallaby whether the file should be displayed in error stack traces reported by the tool.

Overriding defaults

If you would like to override the default values for file object properties, you may use wallaby parameter defaults property. For example, if most of the items in your configuration files list should have instrument property set to false, you may override the default property value as follows:

module.exports = function (wallaby) {
  wallaby.defaults.files.instrument = false;
  return {
    files: [
      'libs/lib1.js',
      'libs/lib2.js',
      'libs/lib3.js',
      'libs/lib4.js',
      { pattern: 'src/**/*.js', instrument: true }
    ],

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

Note, that the defaults for files and tests are set separately, so in the example above all tests will be instrumented. To set the test defaults in that example, you can use the wallaby.defaults.tests object.

Overriding Automatic Configuration

If your project uses automatic configuration, your files and tests properties will be automatically set based on your project’s configuration. There are two ways to configure different or additional files and tests when using automatic configuration:

Modify automatic configuration `files` and/or `tests`

You may modify the files and/or tests properties that are automatically set by Wallaby’s automatic configuration by creating a files or tests property with an object containing an override function:

module.exports = () => ({
  // modify `files` automatic configuration settings
  files: {
    override: (filePatterns) => {
      // TODO: modify `filePatterns` array as required
      return filePatterns;
    }
  },

  // modify `tests` automatic configuration settings
  tests: {
    override: (testPatterns) => {
      // TODO: modify `testPatterns` array as required
      return testPatterns;
    }
  }
});

Replace automatic configuration `files` and/or `tests`

You may force Wallaby to completely ignore the files and/or tests properties that are automatically set by Wallaby’s automatic configuration by creating a files or tests property with an array of patterns.

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

  // modify `files` automatic configuration settings
  files: [
    "src/**/*.js",
  ],

  // modify `tests` automatic configuration settings
  tests: [
    "test/**/*.spec.js",
  ]
});

Dotfiles and hidden folders (prefixed with dot)

By default, Wallaby’s glob matcher doesn’t allow patterns to match filenames starting with a period. To allow such pattern matching you may use the dot: true setting in your Wallaby config:

module.exports = () => ({
  files: [
    ...
  ],

  tests: [
    ...
  ],

  dot: true
});

Example

To sum it up, the configuration sample below makes wallaby.js track all .js files in the src folder and all its subfolders recursively, excluding any files whose name ends with .generated; include but avoid instrumenting libraries in libs folder; and include but avoid instrumenting test helpers (such as testing frameworks configuration scripts, custom matcher, etc.). The sample also includes all test files from the test folder whose name ends with Spec.

{
  "files": [
    "src/**/*.js",
    { "pattern": "src/**/*.generated.js", "ignore": true },
    { "pattern": "libs/*.js", "instrument": false },
    { "pattern": "test/helpers/*.js", "instrument": false },
  ],

  "tests": [
    "test/**/*Spec.js"
  ]
}