Configuration file: Reference

Overview

Option Default Type Description
'testFramework' 'jasmine' for browser and 'mocha' for node

'jasmine' | 'mocha' | 'qunit' | 'jest' | 'ava'
Please check: Supported testing frameworks

Testing framework to run your tests with.
Format: 'name@version' | 'name'

'delays' It’s recommended to skip setting the property. Numeric delay property 'run' specifies the number of milliseconds to wait before letting wallaby.js automatically run your tests as a result of your code changes.

Delays to specify how much time wait before proceeding to the next stage of the automated test run workflow.

'trace' 'false' 'boolean'

If Debugging is 'true', produces a detailed wallaby.js log viewable in the Wallaby Console.

'preserveComments' 'false' 'boolean'

If Preserve Comments setting is 'true', preserves comments in the instrumented files that wallaby generates.

'reportConsoleErrorAsError' 'false' 'boolean'

If property Report console.error as test run error is 'true', reports your tests as failed, if as a result of a test run some 'console.error' calls were made.

'maxConsoleMessagesPerTest' 100 'number'

Set Maximum console messages logged per test to increase the limit of console messages logged per test.

'slowTestThreshold' 75 ms 'number'

Use setting slowTestThreshold to set the time above which the executed test duration is reported as slow.

'runMode' 'automatic' 'onsave' | 'automatic'
  • 'automatic' makes your current Wallaby session start a test run whenever code is changed in your editor or when code is saved on disk
  • 'onsave' starts a test run ONLY when your code is saved to disk.

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

'lowCoverageThreshold' 80% 'number'

Use setting lowCoverageThreshold to set the value below which the coverage is reported as low.

'name' Default project name 'string'

To change the displayed project name.

'filesWithNoCoverageCalculated' the file name(s) 'string'

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.

'reportUnhandledPromises' 'boolean' 'true'

To change the behaviour when running in node.js environment, wallaby.js reports all unhandled promise rejections as errors, the Unhandled promise rejections setting should be set as 'false'.

'runAllTestsInAffectedTestFile' 'boolean' if 'false', re-runs a minimal set of tests for a code change.

To run all tests in the test file every time when one/multiple test(s) of the file are affected by your code changes, the setting should be set as 'true'.

'ignoreFileLoadingDependencyTracking' 'boolean' 'false'

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, the setting should be set as 'true'.

'maxLogEntrySize' 'number' 16,384 characters

If the Maximum Log Entry Size setting is 'true', changes the maximum number of characters.

'screenshot' 'boolean' 'false'

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, the setting should be set as 'true'.

'files' the mandatory configuration property ['string'|'object']

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

Make sure that all files used by your tests are listed in the config 'files' list.

Exceptions:

  • the 'node_modules' folder does not need to be included in the 'files' list.
  • 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.

Please check about an object additional properties details here.

'tests' the mandatory configuration property ['string'| 'object']

To specify an array of test files or test file name patterns, use the tests array property.

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).

Please check about an object additional properties details here.

'env' 'PhantomJs' ['boolean' | 'string' | 'object']

The env property to specify a different test runner or change the runner settings. Please see runner settings.

'compilers' 'TypeScript' & 'CoffeeScript' An object with file patterns as keys and compiler functions as values.

To allow for compilation from anything to JavaScript (ES6 or earlier), wallaby.js supports compilers that run before instrumentation and preprocessors.

Wallaby.js has three built-in compilers: TypeScript, CoffeeScript and Babel.

All files that satisfy 'files' and 'tests' patterns will be tested against the 'compilers' pattern, and those that match will be compiled.

'middleware' Wallaby.js copies all files specified in the 'files' and 'tests' lists to its own cache. 'object'

Function middleware to just specify some file(s) or a folder that wallaby.js will serve ‘as is,’ without copying it to its local cache, or instrumenting or processing it.

You may serve anything by specifying 'middleware' function that takes 2 arguments: express application instance and express instance, and allows you to set and use any middleware.

'workers' It’s recommended to skip setting the property. 'object'

The workers property specifies the degree of parallelism used to run your tests and controls the way wallaby.js re-uses workers.

Files and tests: an object additional properties

Option Default Type Description
'pattern' 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. 'string'

Use the property Pattern to represent the file name or pattern. Each file is checked against patterns from the top of the list to the bottom.

'ignore' 'false' 'boolean'

Use the property Ignore to completely exclude the file from being processed by wallaby.js.

'instrument' 'true' 'boolean'

Setting the property Instrument to 'false' stops the file from being compiled, disables file code coverage reporting, and prevents file changes from triggering automatic test execution.

'load' 'true' 'boolean'

Setting the property Load to 'false' is useful if you are using some alternative script loading mechanism, such as RequireJs or Webpack/Browserify.

NOTE: 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' 'false' 'boolean'

The property Binary tells wallaby whether the file is binary (this affects how the file gets copied to wallaby cache).

Runner (environment)

Note: 'env' settings are for test runner workers, not for preprocessors, postprocessor and compilers.
Option Default Type Description
'env.type' 'browser' 'browser'|'node'

To use 'node.js' should be set 'node', to use a browser environment (PhantomJs or Electron) should be set 'browser'

'env.kind' 'chrome' 'chrome'|'electron'|'phantomjs' To set a test runner
'env.options' 'Default' 'object'

The setting env.options is to pass an object of Electron BrowserWindow options.

'env.runner' 'Default' 'string'

The env.runner property should be set to your local node/phantomJs/electron path, or just node/phantomjs (or any other command) that is mapped to your test runner binary. If 'env.type' is set to 'node' but 'env.runner' is not set, wallaby.js will use its own version of node.js or the system default one.

'env.params.runner' 'Default' 'object'

The env.params.runner property to set space-separated spawned runner process flags.

'env.params.env' 'Default' 'object'

The env.params.env property to set semicolon-separated spawned runner process environment variables.

'env.viewportSize' {width: 800, height: 600} 'object'

The env.viewportSize property to set PhantomJs/Electron page viewport size.

'env.report404AsError' 'false' 'boolean'

The env.report404AsError property allows you to report any 404 server hits as errors to Wallaby Console.

Preprocessors

NOTE: you don’t need a preprocessor to use Babel or Webpack/Browserify with wallaby.js.

Option Default Type Description
'file.content' Default 'string' | 'object' | 'error object' The current content of the file.
'file.path' Default 'string' | 'object' | 'error object' The current path to the file.
'file.rename(newPath)' Default 'string' | 'object' | 'error object' Allows you to rename/move the file.
'file.changeExt(newExt)' Default 'string' | 'object' | 'error object' Allow you to change the file extension.

Please note that if the transformation produces a JavaScript file that you are interested to see the coverage for, then returning the source map is essential. Otherwise, the reported coverage and error stacks may not be correct.

Postprocessors

Option Default Type Description
'logger' 'false' 'boolean'
  • Use 'logger.debug()' to log any debugging information that will only be reported with 'debug': 'true' setting.
  • Use 'logger.trace()' to log any debugging information that will only be reported with 'trace': 'true' setting.
  • Use 'logger.error/logger.warn' to report errors.
'anyFilesAdded' | 'anyFilesDeleted' 'false' 'boolean' Return whether or not any files have been added or deleted for the current batch of changes.
'nodeModulesDir' 'false' 'boolean' Returns the local project node modules folder.
'baseDir' 'false' 'boolean' Returns wallaby cache project folder.
The file objects inside 'allFiles', 'affectedFiles' and 'affectedTestFiles' have the following structure:
'path' Default 'string' The relative path of the file (relative to 'baseDir').
'fullPath' Default 'string' The full path of the file in 'baseDir').
'binary' Default 'boolean' Returns 'true' if the file is a binary file (file content in this case is a base64 encoded string).
'ts' Default 'number' Contains the file change timestamp.
'id' Default Type Contains the file integer identifier in wallaby.js.
'type' Default 'string' Contains the file type, like ‘js’ or ‘html’.
'load' Default 'boolean' Allows to determine whether the file is loaded via a script tag into the generated sandbox.
'instrument' Default 'boolean' Ahe same as in the configuration 'files' object.
'test' Default 'boolean' Allow to determine whether the file is a test file.
'getContent' Default Type The 'getContent' function returns a promise; when resolved it returns the file string content.
File objects passed to the 'createFile' function as an argument should have the following structure:
'path' Default 'string' The relative path of the file (relative to 'baseDir').
'load' Default 'boolean' Allows to determine whether the file is loaded via a script tag into the generated sandbox.
'order' Default 'number' Allows to control the file order in the list of all files included into the sandbox.
'ts' the current time 'number' Contains the file change timestamp.
'content' Default 'string' Content of the file.
'sourceMap' Default 'string' Allow to pass the source map in case the created file is a transformed version of some other file. The property should be used in conjunction with the 'original' file property.
'original' Default 'string' Allow to pass another file object.

Setup

Option Default Type Description
'delayStart()' Default Type To prevent wallaby from starting the test run automatically.
'start()' Default Type Start the test run manually when 'delayStart()' is used.
'tests' Default Type Contain the list of all test files that wallaby.js knows about.
'testFramework' Default Type Contains a reference to the test framework object.
The following additional properties are available in node.js environments:
'localProjectDir' Default 'string' Return the project local folder.
'projectCacheDir' Default 'string' Returns the project cache folder. Note: wallaby.js uses files from this folder to run tests. It copies the files specified in files and tests lists from 'localProjectDir' to 'projectCacheDir'.
'workerId' The number is always between 0 and MAX(worker.initial, workers.regular) - 1. 'number'

Return the id of a worker that runs tests.

'sessionId' Default 'number' A unique identifier of a test run.
'teardown' Default 'object' To clean up after your tests or to set up in the setup function and not in your testing frameworks before/after hooks.

Important: The setup function is executed in the context of the test runner, not in the context of the configuration file.

Workers

Option Default Type Description
'initial' It’s recommended to skip setting the property. 'number'

Use the 'initial' property to specify the number of parallel processes to use to run your tests when your start/restart wallaby.js.

'regular' It’s recommended to skip setting the property. 'number'

Use the 'regular' property to specify the number of parallel processes to use to run your tests every time your code changes.

'restart' It’s recommended to skip setting the property. 'boolean' The 'restart' property determines whether wallaby.js should restart workers.
  • When set to 'true', wallaby.js will restart processes for each run.
  • When set to 'false', wallaby.js will forever keep using processes that were started once, relying on your test cleanup code).
The property is only applicable in a node.js environment, as in the browser environment wallaby.js reloads the page anyway.

Coverage settings

Option Default Type Description
'filesWithNoCoverageCalculated' Default 'string'

To exclude a file from code coverage calculation reported in the Wallaby App use the 'filesWithNoCoverageCalculated' setting.

'ignoreCoverageForFile' '/ignore file coverage/' 'string'

Use the 'ignoreCoverageForFile' setting to ignore a file for coverage purposes by using comment hints.

'ignoreCoverage' '/ignore coverage|istanbul ignore/' 'string' Use the 'ignoreCoverage' setting to ignore code for coverage purposes by using comment hints.