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:

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 relatively 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 v2 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 element 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'
    ]
  };
};

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 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"
  ]
}

The instrument boolean property (true by default) determines whether the file is instrumented. Setting the property to false disables the file code coverage reporting and prevents the 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.

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.

Note that if your browser tests or code is loading 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 could serve them on its embedded web server.

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.

Re-using file lists between Karma/Mocha/Wallaby

When you run your unit tests using both Karma/Mocha and Wallaby, a lot of configuration entries, such as the file and test paths, are duplicated. If you want to keep things DRY, you may put the lists in a separate file and load them into your Wallaby and Karma config using this module.

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"
  ]
}