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.
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.
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).
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.
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.
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.
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 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 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 theTest 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; theTest 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, theTest 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
andRemove 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:
- Open a WSL terminal for your installed Linux distribution and type
code .
- Start VS Code, Press
Ctrl+Shift+P
and selectRemote-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:
- From the command line, run:
git clone https://github.com/wallabyjs/wallaby-vscode-remote-containers.git
. - Open the
wallaby-vscode-remote-containers
folder created by step 1 in VS Code. - Run the VS Code command
Remote-Containers: Reopen in Container
. - 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
).