Last Updated: 10/22/2015

As your JavaScript code base grows and evolves, the need for a solid unit testing story becomes paramount. It isn’t always the case in the real world, but the two should move in lockstep. To support that testing need, there are several popular unit testing frameworks available, including QUnit, Jasmine, and Mocha. If you’re anything like me, Mocha has become your framework of choice, and Visual Studio Code is your JavaScript editor of choice. Thankfully, VS Code provides first-class Node.js debugging, which makes this type of development experience virtually pain-free.

While working on a recent GitHub pull request for OmniSharp’s ASP.NET 5 Yeoman generator, I needed to test my changes prior to submitting. Unfortunately, one of the pre-existing tests was failing on Windows with the latest version of Node (v4.0+); and, I wanted to dig deeper to understand the root cause. Having never debugged Mocha unit tests in VS Code, I was reluctantly venturing into uncharted territory. What follows is a summary of steps required to setup the desired debugging experience.

Show Me the Steps!

As described in the “Usage” section of Mocha’s Getting Started page, there’s a --debug-brk CLI argument which can be passed to enable a Node debugging session. As an aside, note that this argument will cause Node to halt execution on the first line of the JavaScript file, even without a breakpoint at that location. In the command shell, this looks as follows:

mocha --debug-brk

Stash that command away in a package.json script, and you’ll never have to remember or type it again:


"devDependencies": {
"mocha": "^2.3.3"
},
"scripts": {
"test": "mocha –debug-brk"
}

Specifically, the reserved test script may be a great fit for this. I stress “reserved” because that means the run keyword isn’t required to execute the script. Run it like this in the command shell:

npm test

At the time of writing, I’m using VS Code 0.9.1. Unfortunately, NPM scripts aren’t yet discoverable by VS Code’s Command Palette; however, it is a highly requested feature which is under consideration for a future release. For now, open a command shell and run this command from there. An informative message will appear in the console stating that a debugger is listening on a certain port (see the screenshot below). Take note of that port number, as you’ll need to reference the same number in VS Code.

Mocha debugging

Return to VS Code. If a launch.json file doesn’t already exist within the .vscode folder of your project, now is the time to create it. Its contents should resemble the gist below. Remember that port number you were supposed to jot down? Here’s where it will be needed.


{
"version": "0.1.0",
"configurations": [
{
"name": "Debug Mocha Test",
"type": "node",
"address": "localhost",
"port": 5858,
"sourceMaps": false
}
]
}

view raw

launch.json

hosted with ❤ by GitHub

Now that the debugger configuration file has been created, set a breakpoint on the Mocha test which you’d like to troubleshoot. Next, click the VS Code side bar’s Debug tab, and select the appropriate debugging configuration option from the drop-down list to the right of the green play button. In this example, that debugging configuration name is “Debug Mocha Test”. Once selected, click the green play button. The debugging session has been started, and the typical debugging controls are provided to step into, step out, step over, etc.

breakpoint

10 Comments »

  1. To make it runnable directly from VS Code you could add a task to tasks.json:
    { “version”: “0.1.0”, “command”: “npm”, “isShellCommand”: true, “tasks”: [ {“taskName”: “test”, “isTestCommand”: true, “showOutput”: “always” }] }
    (Setting “isTestCommand”: true makes it running by just pressing Shift+Ctrl+T.)

    But for that you need to make sure you don’t have other custom commands specified other than “npm” (support for multiple custom commands is also a requested feature).

    Liked by 1 person

    • I’ll have to update this blog post to demonstrate the correct approach with VS Code 0.10.0+. You’ll want your launch.json file to look like this:

      {
      "version": "0.2.0",
      "configurations": [
      {
      "request": "launch",
      "name": "Debug Mocha Test",
      "type": "node",
      // Notice, we bypass the launcher and start the test runner directly
      "program": "node_modules/mocha/bin/_mocha",
      "stopOnEntry": true,
      // run the tests in the test folder
      "args": ["test"],
      "cwd": ".",
      "runtimeExecutable": null,
      "env": { }
      }
      ]
      }

      Now, you can launch that “Debug Mocha Tests” debug configuration from the Debug tab. With this approach, there’s no need to attach to the running process.

      Like

  2. You can automate the use of this even more by setting the “preLaunchTask” on the attach to run the tests:

    (have an npm task “test.debug” that has –debug-brk 15429 as a parameter to the test command)

    here is the task:
    {
    “taskName”: “test.debug”,
    // Don’t run on Shift+Ctrl+B
    “isBuildCommand”: false,
    // Run on Ctrl+T
    “isTestCommand”: true,
    “showOutput”: “always”,
    “args”: [
    “test.debug”
    ]
    }

    here is the launch:
    {
    “name”: “Run unit tests”,
    // Type of configuration.
    “type”: “node”,
    “request”: “attach”,
    “port”: 15429,
    “preLaunchTask”: “test.debug”
    }

    Like

  3. I want to debug jasmine test cases which are placed in StockSpec.js . Now in launch.json file i have
    “program”: “spec/StockSpec.js”, (rest config is as default)
    on debugging, I get “describe not defined” as error.
    If i change
    “program”: “gulpfile.js”,
    debugger would blur out step in, step out etc options.
    I’m using gulp which contain task to run karma.conf.js file which run my StockSpec.js file through command line. But I want to use debug feature of VS Code like you did. What am I missing 😦

    Like

  4. “Debugger listening on ws://127.0.0.1:36428/158794f8-e9f1-47e1-ae8b-72da0b9aec4c
    Warning: Could not find any test files matching pattern: test.js
    No test files found
    Debugger attached.
    Waiting for the debugger to disconnect…
    Warning: Could not find any test files matching pattern: test.js
    No test files found” .
    please help me to answer the cause of this result.,thank you very much.

    Like

Leave a comment