Tutorials: VS Code tutorial

First you need to install Wallaby.js extension for VS Code, if you haven’t already done so.

For this tutorial we will use our sample calculator project. You may download a zip file with the source code or else clone the repo using:

git clone https://github.com/wallabyjs/calculator-sample.git

Once you have the source code locally, open the project folder in VS Code.

First steps

Configuring Wallaby

Wallaby for VS Code needs to know what configuration is required to run your tests. If a technology is detected that is supported by automatic configuration, then Wallaby will start automatically without any configuration. If you want to use a configuration file or have a mono-repo and only want to run for one project, you may select a different configuration using the Wallaby.js: Select Configuration command from the editor Command Palette. If you wish to use automatic configuration for a sub-folder within a mono-repo you may also select the folder in the Explorer tree and use the Wallaby.js: Configure and Start context menu item.

If your project does not support automatic configuration then Wallaby will automatically search for a configuration file in your project root and will automatically select it, valid names are: wallaby.js, wallaby.conf.js, wallaby.json, and .wallaby.json. If you use multiple configuration files, use different naming convention, or have the config file not in the root folder, you may select the config file using the Wallaby.js: Select Configuration command from the editor Command Palette.

Wallaby.js Command Palette

As you probably know, you may press Ctrl/Cmd + Shift + P in VS Code to get the editor Command Palette in case if you’ve forgotten some shortcuts or just like invoking commands this way. There you may search for Wallaby to get the list of available commands you can execute.

For convenience, Wallaby adds its own Command Palette to the editor that you may display by pressing Ctrl/Cmd + Shift + =. It is a fast and easy way to quickly get to Wallaby commands.

Now let’s have some fun.

Let’s try starting Wallaby. To do that you need to run the Wallaby Start command. You may do it by using the Ctrl/Cmd + Shift + R, R shortcut, or using the Wallaby Command Palette.

To stop Wallaby, you may use the Stop command.

Wallaby in action

Once you have started Wallaby, at the bottom right corner of the editor you’ll see Wallaby status indicator. It’s job is pretty simple: when it displays a spinner - your tests are running, when it shows a cross - you have some failing tests, when it shows a tick - all of your tests are passing. It also shows the number of failing or passing tests, and you may also use the indicator to show ‘Wallaby.js Tests’ Output Channel by clicking it.

Now, let’s open the sample calculator project spec (test/calculatorSpec.js).

When Wallaby is running, you will see the code coverage in opened source files (specified in Wallaby configuration file). As you can see, there are various colored squares displayed for each line of your source code.

Try jumping to any of the passing tests and break it, for example try changing the 2 plus 2 expectation result to 5 in the should add numbers test, or try breaking the code covered by the test. Right after the change Wallaby automatically runs your tests and displays the result in status bar.

The code coverage and messages are automatically updated, right as you type.

Also, try editing some console.log arguments or just console.log any object you like.

This is a great way to quickly inspect any objects without having to leave your editor, without switching to any other console. Think how cool it is - your code editor is your console with all the required context.

We recommend reading about some more powerful ways to log things and measure code performance with wallaby.js.

Watch expressions in action

Watch performance in action

Coverage indicators

Let’s have a look at the editor gutter where you may see some indicators. Here is what these coverage indicators mean:

  • Gray squares mean that the source line is not covered by any of your tests.
  • Green squares mean that the source line is covered by at least one of your tests.
  • Yellow squares mean that the source line is only partially covered by some of your tests.
  • Red squares mean that the source line is the source of an error or failed expectation, or is in the stack of an error.
  • Pink squares mean that the source line is on the execution path of a failing test.

Failing tests

The ‘Wallaby.js Tests’ Output Channel displays all tests that are currently failing along with the error stacks and registered console.log calls. Some of the information displayed includes hyperlinks so that you can easily navigate to different places, for example to the exact error line, or a line where something is logged to console. To quickly focus the panel you may use the Show Failing Tests wallaby command (Ctrl/Cmd + Shift + R, T).

When a test error contains expected and actual properties, the ‘Wallaby Tests’ output channel, as well as the error hover tip, displays compact diff view and can display side-by-side diff view. This allows you to quickly debug failing equality assertions and snapshots.

Diff views

If you want to view some snapshot content (regardless of whether your tests are failing or not), Wallaby displays hover tip above every expect(...).toMatchSnapshot() line. Go to Definition or Peek to Defintion editor commands also open the line snapshot (Important note: you must be on the line with the snapshot coverage indicator for the hover and commands to operate).

View Jest Snapshots

Problems

Another way to quickly see failing tests is with VS Code’s Problems View, using the command: View: Toggle Problems (Ctrl+Shift+M). You may quickly navigate to the location of a failing test (or its related details) by selecting an item in the problems view. In addition to highlighting the failing test in your code file, the failing test will also be highlighted in the VS Code file explorer.

Problems View

Value Explorer

Value Explorer integrates with Wallaby’s existing variable and expression output mechanisms (console.log, live comments, identifier expressions, and the Show Value command) to display values in an easy-to-navigate, real-time tree view. The tree can be expanded to any depth and can copy paths/values to the clipboard.

Value Explorer in action

Time Travel Debugger

Wallaby’s Time Travel Debugger allows you to move forward and backwards through your code to understand the conditions that led to a specific bug. The Time Travel Debugger accelerates your edit, compile and debug loop by allowing you to jump to a specific line of code, view runtime values, edit-and-continue and step into, over and out of your code.

Time Travel Debugger in action

Once Wallaby has started, the time-travel debugger is available at any time. The debugger can be started from any of your project’s tests. Navigate to the line of code where your test starts and run the command, Wallaby.js: Debug Test (Shift + F5).

In addition to being able to start the debugger on the line of code where your test starts, you may also start the debugger on any line of your code that is executed by your tests. When you start the debugger from a line other than the start of your test, the debugger will start and automatically progress to that line. If you start the debugger from a line of code that is covered by multiple tests, you will be prompted to select which test you want to debug.

Test Stories

Wallaby’s Test Story Viewer provides a unique and highly efficient way of debugging your code and inspecting what code your test is executing in a single logical view. The view is integrated with Wallaby’s Time Travel Debugger and Value Explorer.

Test Story Viewer in action

Test File Coverage

Wallaby’s Test File Coverage view allows you to quickly see currently opened test file’s code coverage. The coverage is updated in realtime as you type.

Test File Coverage

Test focusing

Sometimes when writing or debugging a test, set of tests or test file for a particular feature, you may need to execute this specific test, set of tests or test file and see code coverage and output only for the specified scope. Wallaby fully supports testing frameworks test focusing functions such as it.only, as well as special comments to focus/skip specific test files.

Wallaby also allows you to start for a selected file or folder using the Exclusive Test Run feature. If you have a large test suite which takes long time to run you may use the Start Exclusive Test Run command/menu item that allows you to select a test file or a folder which contains the tests files you would like to focus on and start Wallaby only to run them. If you already have Wallaby started but you would like to focus only on a specific test file or a folder then you may use Add to Exclusive Test Run command/menu item.

To reset the exclusive test run and run all you project tests you may use the Run Project Tests command.

Test filtering

Test Filtering allows you to limit the display of coverage indicators, console messages, live comment messages and errors messages to only the tests that you are working on instead of all tests in your project. You may notice that Test Focusing covers filtering, but there are two key differences between them:

  • The Test Filtering in contrast to the Test Focusing does not re-execute your tests when applying/clearing the filter. When you change from only running selected test(s) to running all tests in your project, all tests are re-run; the Test Filtering does not re-run any tests when the filter is set or cleared.
  • The Test Filtering feature does not actually change Wallaby’s run-time behavior (after any code change, the minimum set of affected tests will be re-run). In contrast, the Test Focusing feature may enable a more efficient workflow for large repositories with many test files, or for slower tests, as Wallaby will only process/run the selected tests.

Wallaby supports three ways of adding and removing tests and test files to/from the test filter:

  • Add test to filter and Remove test from filter code actions
  • Toggle Test Filter command
  • Wallaby App (with full editor synchronization)

You may clear the test filter by pressing Shift+Esc or by executing the Reset Test Filter command, also the Reset Filter link in on Wallaby.js Tests output pane and Reset Test Filter button in Wallaby App are available for you.

Commands

To help you writing/navigating your code and tests more efficiently, Wallaby provides a few commands. You may see the full list in the Wallaby.js Command Palette (Ctrl/Cmd + Shift + =).

These commands include:

  • Show Line Tests: displays the line related test data. The command allows you to quickly view all tests (both failing and passing) that cover the current line of code, navigate to test and code errors, view console messages related to some specific test or some source code line.
  • Jump To Test: allows quick search and navigation to a test.
  • Jump to Failing Test: allows quick navigation to the failing test from any ‘pink’ context (the failing test execution path).
  • Jump to Error Source: allows quick navigation to the source of the test error from any ‘pink’ context (failing test execution path).
  • Toggle Uncovered Code Regions: displays/hides uncovered regions for an opened file. The command is very useful for ‘yellow’ lines to display what is exactly not covered in the line. Highlighted markers will automatically disappear when you start editing your code or if you press Esc.

  • Run Line Tests: the command is pretty simple, it just runs a single test (if invoked from within the test) or all related tests (if invoked within some source code covered by the tests).
  • Run File Tests: the command runs all tests within the test file it is invoked in, or all tests in all the test files that cover the source file that the command is invoked within.
  • Run Project Tests: the command runs all tests in your project.
  • Update Project Snapshots: the command updates all Jest snapshots in your project.
  • Update File Snapshots: the command updates all Jest snapshots in the current (focused) file, or all snapshots in all the test files that cover the source file that the action is invoked within.
  • Update Test Snapshots: the command updates snapshots of a single test (if invoked from within the test) or all snapshots in all related tests (if invoked within some source code covered by the tests).
  • Toggle Test Filter: adds or removes a test or a test file to/from the test filter.
  • Add to Exclusive Test Run: adds the tests from the currently opened file to the exclusive test run. The command is also available as a context menu item in the Explorer tree that works for files and folders.
  • Start Exclusive Test Run: starts Wallaby in exclusive test run mode by executing the tests only from the currently opened file.
  • Show Last Screenshot: the command displays the screenshot for the last run test (Important note: this feature works only when running your tests using Chrome and PhantomJs).
  • Make Current Session Run on Any Change: the command makes your current Wallaby session start a test run when code is changed in your editor or when code is saved on disk.
  • Make Current Session Run Only on Save: the command makes your current Wallaby session start a test run ONLY when code is saved on disk.
  • Toggle Current Session Run Mode (Any Change/On Save): the command toggles between Make Current Session Run on Any Change and Make Current Session Run Only on Save.

Changing Wallaby’s Start Mode

By default, Wallaby will try to automatically start when you open your folder or workspace if it was running when the VS Code window was closed. If you never started Wallaby, then it will never try to run for your project. If Wallaby was started (either automatically or using a command) but test results were never returned, then Wallaby will not try and start automatically when the folder or workspace is re-opened.

After starting Wallaby, if you do not want Wallaby to start automatically when your folder or workspace is re-opened, run the Stop command.

If you never want Wallaby to start automatically, then you can disable this behavior entirely. The option may be configured globally as a User preference and may also be overridden as a Workspace preference. To change the setting, use VS Code’s Preferences: Open Settings (UI) command and tick/untick the Start Automatically checkbox:

Changing icon colors

Coverage indicator colors may be changed in VS Code user settings (settings.json file). You may find the example with the default colors below.

{
    ...

    "wallaby.colors": {
        "covered": "#62b455",
        "errorPath": "#ffa0a0",
        "errorSource": "#fe536a",
        "notCovered": "#cccccc",
        "partiallyCovered": "#d2a032"
    }
}

Windows Subsystem for Linux (WSL)

For Microsoft Windows environments, Wallaby may be configured to run using WSL. Both WSL1 and WSL2 are supported within VS Code. To find out which version you are using, run the terminal command wsl --list --verbose.

WSL 2

You must first install Microsoft’s VS Code Remote WSL extension. Wallaby will automatically use WSL2 when a remote WSL session is available.

There are two ways to start a VS Code WSL session:

  1. Open a WSL terminal for your installed Linux distribution and type code .
  2. Start VS Code, Press Ctrl+Shift+P and select Remote-WSL: New Window

After starting a remote WSL session, you must install the Wallaby extension for your WSL distribution from the Extensions view. You must also re-apply your Wallaby license to your remote WSL distribution.

The supported runtime environments for WSL2 are node.js and chrome (headless).

If you are using node.js then you do not need to do anything further to use WSL2.

If you are using chrome (headless) then the default permissions for your WSL distribution restrict browser tests from being run. You must update your Windows Firewall settings in order for your tests to be able to run. The only known configuration to enable connectivity between the host and the WSL2 distribution is to exclude the vEthernet (WSL) network from your list of public protected network connections in your Windows Defender Firewall settings.

WSL 1

The WSL1 configuration option is available through your VS Code settings. To use WSL1, you must set wallaby.useWsl to true, for example:

{
    "wallaby.useWsl": true
}

This setting is ignored on non-Windows environments. If configuring a custom version of node, the path must refer to a version of node on your Linux installation.

Please note that you need to restart VS Code after changing the configuration before the change will take effect.

Remote Containers

Wallaby supports running in remote docker containers from within VS Code. Our wallaby-vscode-remote-containers sample repo includes .devcontainer settings for sharing your local wallaby license with a dev container (see .devcontainer/docker-compose.yml and .devcontainer/devcontainer.json). If you do not share your local wallaby license with your dev containers then you will need to reapply your Wallaby license every time your container is rebuilt.

To run Wallaby in a container with the sample repo:

  1. From the command line, run: git clone https://github.com/wallabyjs/wallaby-vscode-remote-containers.git.
  2. Open the wallaby-vscode-remote-containers folder created by step 1 in VS Code.
  3. Run the VS Code command Remote-Containers: Reopen in Container.
  4. Run the VS Code command Wallaby.js: Start.

Trial version

Wallaby is installed with a limited-time feature-complete demo license that periodically prompts you to restart your editor to continue using the tool. Free Trial licenses that allow you to evaluate without prompts and restarts are also available.

Troubleshooting

If you encounter any issues with configuring or using Wallaby and are not sure why it happens, check out our troubleshooting docs section or search our public repository issues to see if someone else has experienced something similar.

Another useful technique is to run Wallaby with the trace flag set to true. In this case Wallaby outputs a lot of additional information about the test execution progress which may help you to understand what’s going on if something goes wrong. The output can be viewed in the Wallaby.js Console Output Channel (View - Output).