First you need to install wallaby.js plugin for your IDE, if you haven’t done it yet.

This tutorial demonstrates how to use wallaby.js in WebStorm, IntelliJ IDEA, Rider, PhpStorm, RubyMine, or PyCharm. You may also find a sample calculator project with created run configurations and config files for Mocha, QUnit and Jasmine in this repository.

Configuration file

After the plugin is installed, you can start by creating a wallaby configuration file. The configuration file is just a simple JSON or JavaScript file in your project root with just a couple of mandatory settings. It’s recommended to prefix or suffix it with wallaby, for example wallaby.json or wallaby.js.

A simple configuration file would include files and tests (and testFramework, if you are not using jasmine) properties.

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

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

or

module.exports = function () {
  return {
    files: [
      'src/**/*.js'
    ],

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

The files property should list your source files and other files used by your tests, while the tests property should list your test files. Any test helpers or other test related files that are not the files with actual tests/specs should be listed under the files property. Glob patterns can also be used.

Finally, the testFramework property defines the name and the version of the testing framework you will be (or are) using to write your tests. The supported testing frameworks are listed here.

The configuration file example above assumes that your source files are in the src folder, that you are using Jasmine and your tests are in the test folder and their names end with Spec. Source files location is specified as a pattern, however in many case the loading order of your source files matters, so you may need to specify some of them one by one.

You can read more about the configuration file format and other settings in the corresponding section.

Run configuration

Continue by creating a new wallaby.js Run Configuration. Select Edit configurations from the drop-down menu in the top right-hand corner of the navigation bar, or from the Run menu.

In the configuration you can specify:

rc

When you create a Run Configuration, it is recommended to use the node.js version selected by default, unless you really need to change the version for some reason.

Once you have created and saved the configuration, you can start it. The first time you run it, wallaby.js may take a minute or two to install all the dependencies it needs, such as node.js and PhantomJs. It only does this once and then uses the saved dependencies. The dependencies are updated automatically when required.

Once you have started the run configuration, in the bottom right-hand corner of the screen you’ll see the wallaby status indicator. Its job is pretty simple: when it displays a spinner, your tests are running; when it’s red, you have some failing tests; when it’s green, all of your tests are passing.

Tool window

When wallaby.js starts, it also displays a tool window. While writing code, you may not need the window to be opened, so you can collapse it. You can expand it any time by clicking the wallaby.js status indicator (or using the standard way to open a run configuration tool window).

status

In the tool window you can see the Failing Tests tab and the Wallaby Console tab.

The Failing Tests tab displays all tests that are currently failing along with the error stacks and registered console.log calls. Some bits of the displayed information are hyperlinks that you can use with your mouse or keyboard to navigate to different places, for example to the exact error line, or a failing test, or a place where something is logged to console.

The Wallaby Console tab displays some additional information about test execution progress. The tab can also be useful for troubleshooting wallaby.js issues.

Code coverage

Once wallaby.js is running, you can see the code coverage in the source files that it tracks (specified in the configuration file). The coverage is live, so you can start changing your code and the coverage will automatically be updated, just as you type.

As you can see, there are various colored squares displayed for each line of your source code.

coverage

Clicking a square against a source code line will display a window with the information about the tests covering the line, including any error messages and console.log messages.

You can search inside the window by using standard Cmd/Ctrl + F command and navigate links by using Cmd/Ctrl + B.

window

Short error messages, expectation failures and console.log messages are also displayed inline, right where and when they happen. This is very convenient as it allows you to avoid context switching and fix the issues in place, as you write your code.

Context actions

Another way to access some source code line/context actions is to use the light bulb quick actions, or just press Alt + Enter on any line. The actions that you can use include:

context

All of the described actions can also be mapped to any keyboard shortcuts you prefer for extra productivity. You can do so in Settings - Keymap (search for wallaby in the keymap settings).

keymap

The recommended workflow is just to keep wallaby.js up and running as you edit your code. It should pick up existing file changes, file deletion, adding new files and tests (as long as they are listed in files patterns in the configuration file). Wallaby.js does its best to track the dependencies between your files and tests, but occasionally you may need to restart it if your changes are not picked up. You can stop/start wallaby.js any time by stopping/starting the active run configuration.

Trial version

Note that trial version of wallaby.js (the one without a valid license) will be displaying prompts and stopping after some time, so you will need to restart the tool or your editor. Please contact us if you would like to arrange a trial period for yourself or your team without activation prompts and restarts.