Overview
Wallaby has 2 types of configuration: automatic and manual.
If you are using Jest >= v24, Vitest, Angular CLI >= v8.2, node:test, Create React App >= v3, Vue CLI >= v4, or NX Workspaces >= v8 then automatic configuration is used and it allows you to start Wallaby without any configuration files.
If automatic configuration for your testing framework is not supported, then you need to use manual configuration.
If you are using Wallaby with automatic configuration, you may still override some settings.
Configuration file
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:
wallaby.js
module.exports = function () { return { reportConsoleErrorAsError: true, };};Wallaby configuration may also be specified in the wallaby section of your package.json file:
package.json
{ "name": "my-package", ... "wallaby": { "reportConsoleErrorAsError": true }}Auto Detect Configuration Setting
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 { ...
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 { ...
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 { ...
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 { ...
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 { ...
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 { ...
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 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 { ...
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
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 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
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 // 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.