Mocha breakpoints using Visual Studio Code

Is it possible to add breakpoints to Mocha tests using Visual Studio Code?

Normally when debugging code, one needs to configure the launch.json, setting the program attribute to the Javascript file to execute. I am not sure how to do this for Mocha though.

Did you know, that you just go into your launch config, put your cursor after or between your other configs and press ctrl-space to get a current, valid mocha config auto-generated?

Which works perfectly fine for me. Including stopping at breakpoints. ( I also had a prior, now outdated one, that did no longer for various setting-related reasons. )

As of VSCode 1.21.1 (March 2018) this yields:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Mocha (Test single file)",
      "type": "node",
      "request": "launch",
      "runtimeArgs": [
        "${workspaceRoot}/node_modules/.bin/mocha",
        "--inspect-brk",
        "${relativeFile}",
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "port": 9229
    }
}

On a side-note: debug-brk is deprectated (for anyone with Node >= Version 8 at least).

If you don't want to use --debug-brk+Attach or state an absolute path to your global mocha installation (which will brake if you keep your launch.json under version control and have multiple developers on different machines), install mocha as a dev dependency and add this to your launch.json:

{
  "name": "mocha",
  "type": "node",
  "request": "launch",
  "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
  "stopOnEntry": false,
  "args": ["--no-timeouts", "--colors"], //you can specify paths to specific tests here
  "cwd": "${workspaceRoot}",
  "runtimeExecutable": null,
  "env": {
    "NODE_ENV": "testing"
  }
}

Full debugging support in your tests by just pressing F5.

--no-timeouts makes sure your tests don't time out because you stopped at a breakpoint, and --colors makes sure Mocha outputs colors even though it doesn't detect that VS Code supports colors.

Another way is to use the --debug-brk command line option of mocha and the default Attach launch setting of the Visual Studio Code debugger.

---

Suggested deeper explanation (from André)

To do this:

Run mocha from the command line using this command:

mocha --debug-brk

Now in VS Code click on the Debug icon, then select Attach from the option next to the start button. Add breakpoints in VS Code and then click start.

I've made this work on VSCode on OS X 10.10. Just replace your ./settings/launch.json file with this.

{
	"version": "0.1.0",
	"configurations": [
		{
			"name": "Run app.js",
			"type": "node",
			"program": "app.js", // Assuming this is your main app file.
			"stopOnEntry": false,
			"args": [],
			"cwd": ".",
			"runtimeExecutable": null,
			"env": { "NODE_ENV": "production"}
		},
		{
			"name": "Run mocha",
			"type": "node",
			"program": "/Users/myname/myfolder/node_modules/mocha/bin/_mocha",
			"stopOnEntry": false,
			"args": ["test/unit.js"],
			"cwd": ".",
			"runtimeExecutable": null,
			"env": { "NODE_ENV": "production"}
		}
	]
}

It is also available as a gist here.

The key values you need to change are program, which should be set to the _mocha executable, and args, which should be an array of your test files.

1. Go to Debug > Add Configuration... menu
2. Select Node.js environment
3. Select Mocha Tests option from the appeared drop-down list
4. Type the path of your test file as the last item of the args property
5. Add a breakpoint
6. Click on Debug icon
7. Select Mocha Tests as a configuration
8. Press Start debugging button
9. :-)

The way I got it to work on VS Code (1.8.2) on Mac OS X is:

{
    "name": "Mocha",
    "type": "node",
    "request": "launch",
    "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
    "stopOnEntry": false,
    "args": ["--recursive"], //you can specify paths to specific tests here
    "cwd": "${workspaceRoot}",
    "runtimeExecutable": null,
    "env": {
        "NODE_ENV": "testing"
    }
}

Mocha needs to be installed in the npm modules directory.

I've figured out a way to do this which I classify as a workaround. I expect the Visual Studio Code team to provide a more definitive solution for this but meanwhile this what I've done:

1. I've created a ./settings/mocha.js file which runs mocha programatically passing arguments as a list of files to be run. You can see the full file here;

2. I've created a launch config which will run the ./settings/mocha.js as the program and passes the files/file patterns we need to test as arguments:

    {
    	"name": "Unit tests",
    	"type": "node",
    	"program": ".settings/mocha.js",
    	"stopOnEntry": true,
    	"args": ["test/unit/*.js", "test/unit/**/*.js"],
    	"cwd": ".",
    	"runtimeExecutable": null,
    	"env": { }
    }
   

   Full launch.json example

So this is the equivalent of doing mocha test/unit/*.js test/unit/**/*.js and now we can use breakpoints in our mocha tests.

If you add ${file} variable at the end of the args list you can start debugging directly from the file you have open:

        {
            "type": "node",
            "request": "launch",
            "name": "Mocha Tests",
            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
            "args": [
                "-u",
                "tdd",
                "--timeout",
                "999999",
                "--colors",
                "${file}"
            ],
            "internalConsoleOptions": "openOnSessionStart"
        }

Sorry for adding yet another answer, but none of the previous ones quite worked for me as of VS Code 1.8.1 and the standard Node debugger included in it. Here is the way I solved it (with guidance from the previous answers here and from the official VS Code Node.js Debugging docs) so there is one click/keypress debugging:

• Ensure mocha is installed as a devDependency in packages.json: "devDependencies": { "mocha": "^3.2", ... }
• Run npm install in the directory of your package.json to make sure mocha is now installed in node_modules/
• Open .vscode/launch.json (or in VS Code, press F1, start typing "launch", and select "Debug: Open launch.json")
• Click the blue "Add Configuration" button in the bottom right (or just copy and paste one of your others); this step is optional... I mean, you can re-use an existing config. But I suggest adding one to keep it less confusing.
• Change the following in your launch.json, then pick the new config name in the debug window in VS Code and click the green arrow to start debugging your node + mocha tests!

In the new config in launch.json:

"configurations": [{
    "name": "whatever name you want to show in the VS Code debug list",
    "type": "node",
	"cwd": "${workspaceRoot}",
    "program": "${workspaceRoot}/node_modules/mocha/bin/mocha",
	"args": ["--debug-brk=5858", "--no-timeouts", "--colors", "test/**/*.js"],
	"address": "localhost",
	"port": 5858,
    // the other default properties that are created for you are fine as-is
}, ...]

This assumes the pattern test/**/*.js will work for where you put your tests. Change as appropriate.

Feel free to change the port as long as you change it in both of the args and port properties to match.

The key differences for me was making sure mocha was in node_modules, using program to point to the executable, and args needing debug-brk=x pointing to the port specified in port. The rest of the above just makes things prettier and easier.

It's up to you and your team if you put .vscode/launch.json in the repository or not. It's an IDE-only file, but your whole team could use it like this, no problem, since all paths and installs are relative and explicit.

Tip: The package.json can include a scripts tag that also launches mocha with something like "test": "./node_modules/.bin/mocha", but it is not used by VS Code—instead it is used when npm test is run at the command line. This one confused me for a bit. Noting it here in case others get confused too.

EDIT: VS Code 1.9.0 has added an "Add Configuration" option in the debug configuration drop-down, and you can pick "Node.js Mocha Tests" which help simplify most of the above. You still need to make sure mocha is in your node_modules and might have to update the cwd and last runtimeArgs (which is the pattern for finding your tests) to point to the appropriate paths. But once you set those two properties, it should work pretty much from there.

in the launch.json, add 1 more configuration below

{
      "type": "node",
      "request": "launch",
      "name": "Mocha Tests",
      "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
      "args": [
        "--timeout",
        "10000",
        "${workspaceRoot}/services/*.spec.js",
        "${workspaceRoot}/*.spec.js"
      ],
      "internalConsoleOptions": "openOnSessionStart"
    },

if you need to configure node version, simply add runtimeExecutable field like this

{
      "type": "node",
      "request": "launch",
      "name": "Mocha Tests",
      "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
      "args": [
        "--timeout",
        "10000",
        "${workspaceRoot}/services/*.spec.js",
        "${workspaceRoot}/*.spec.js"
      ],
      "internalConsoleOptions": "openOnSessionStart",
      "runtimeExecutable": "${env:HOME}/.nvm/versions/node/v8.2.1/bin/node"
    },

1. Go to

> .vscode

then

> launch.json

file

2. Add the following configuration in launch.json -

   { "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Mocha Test", "cwd": "${workspaceRoot}", "runtimeExecutable": "${workspaceRoot}/folder_path_containing_test/node_modules/.bin/mocha", "windows": { "runtimeExecutable": "${workspaceRoot}/folder_path_containing_test/node_modules/.bin/mocha.cmd" }, "runtimeArgs": [ "--colors", "--recursive", "${workspaceRoot}/folder_path_till_test/tests" ], "internalConsoleOptions": "openOnSessionStart" }, { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceRoot}/folder_path_to_test/app.js" } ] }

3. Set breakpoints in test file and then press F5

For anyone using Windows. If you have installed mocha globally then setting program to the following path worked for me (swap in your username).

"program": "C:\\Users\\myname\\AppData\\Roaming\\npm\\node_modules\\mocha\\bin\\_mocha"

This is working fro me on a Windows 7 machine. I do have mocha installed globally, but this configuration is pointing to the project install to avoid the need for a user profile path (which btw, I tried used %USERPROFILE% variable with no success). I'm able to set breakpoints in my mocha tests now. Yay!

{
        "name": "Mocha Tests",
        "type": "node",
        "request": "launch",
        "stopOnEntry": false,
        "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
        "cwd": "${workspaceRoot}",
        "args": ["./test/**/*.js"],
        "runtimeExecutable": null,
        "envFile": "${workspaceRoot}/.env"
    }

For those that are using grunt or gulp, the configuration is pretty simple.

Launch.json

{
"version": "0.2.0",
"configurations": [

    {
        "name": "Run mocha by grunt",
        "type": "node",
        "program": "${workspaceRoot}/node_modules/grunt/bin/grunt",
        "stopOnEntry": false,
        "args": ["mochaTest"],
        "cwd": "${workspaceRoot}",
        "runtimeExecutable": null
    }
]}

Gruntfile.js

module.exports = function (grunt) {

grunt.initConfig({
    mochaTest: {
        test: {
            options: {
                reporter: 'spec'
            },
            src: ['test/**/*test.js']
        }
    }
});

grunt.loadNpmTasks('grunt-mocha-test');

grunt.registerTask('default', 'mochaTest');};

In VSCode version 1.13.0 (macOS), they have it built-in under configurations -> Mocha Tests.

When using Babel, or generating javascript files yet placing breakpoints in the source - you have to make sure to enable sourceMaps and define outFiles. Here's an example config that worked for me.

    {
        "name": "Mocha Test",
        "type": "node",
        "request": "launch",
        "program": "${workspaceRoot}/packages/api/node_modules/mocha/bin/_mocha",
        "cwd": "${workspaceRoot}/packages/api",
        "args": ["--colors", "--no-timeouts", "out/test"],
        "outFiles": ["${workspaceRoot}/packages/api/out/*"],
        "sourceMaps": true,
    },

Note - you'll need to modify outFiles to include everything you might want to add a breakpoint to. This can be more tedious when in a monorepo and multiple dependent projects.

The official microsoft/vscode-recipes on Github has this launch.json for debugging mocha tests (enter the link for more mocha tests configurations):

{
  "version": "0.2.0",
  "configurations": [
    {
        "type": "node",
        "request": "launch",
        "name": "Mocha All",
        "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
        "args": [
            "--timeout",
            "999999",
            "--colors",
            "${workspaceFolder}/test"
        ],
        "console": "integratedTerminal",
        "internalConsoleOptions": "neverOpen",
        "skipFiles": [
            "<node_internals>/**/*.js"
        ]
    },
    {
        "type": "node",
        "request": "launch",
        "name": "Mocha Current File",
        "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
        "args": [
            "--timeout",
            "999999",
            "--colors",
            "${file}"
        ],
        "console": "integratedTerminal",
        "internalConsoleOptions": "neverOpen",
        "skipFiles": [
            "<node_internals>/**/*.js"
        ]
    }
  ]
}

When using TypeScript, the following configuration works for me in Visual Studio Code 0.8.0 (tsc 1.5.3)

tsconfig.json

{
    "compilerOptions": {
        "module": "commonjs",
        "target": "es5",
        "noImplicitAny": false,
        "removeComments": true,
        "preserveConstEnums": true,
        "sourceMap": true,
        "outDir": "build",
        "declaration": false
    },
    "files": [
        "./src/index.ts",
        "./src/test/appTests.ts"
    ]
}

The important things to note here is that source maps are generated and that the output directory for the js is set to build

launch.json

	{
		"name": "Attach",
		"type": "node",
		// TCP/IP address. Default is "localhost".
		"address": "localhost",
		// Port to attach to.
		"port": 5858,
		"sourceMaps": true,
		"outDir": "build"
	}

Please note that sourceMaps is set to true and that the outDir is set to build

to debug

1. Stick breakpoints in index.ts any other imported typescript file
2. Open a terminal and run : mocha --debug-brk ./build/test/appTests.js
3. From VSC, run the 'Attach' launch configuration

Here is an example of launch configuration (launch.json) from Microsoft, which works with Mocha and allows using the debugger.

Also, there is a description of how to use the --debug-brk option.

Finally, here is an alternative version of how to debug code with Mocha tests using tasks.json file of VS Code and Gulp task runner.

If you have some dependency in the test it is also easy to attach it.

For example, I am using mongo-unit-helper to also have unit tests integrated with Database.

package.json script is: mocha --recursive --require ./test/mongo-unit-helper.js --exit"

My launch.json looks like:

  "configurations": [
  {
  "type": "node",
  "request": "launch",
  "name": "Mocha Tests",
  "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
  "args": [
    "-u",
    "tdd",
    "--timeout",
    "999999",
    "--colors",
    "--recursive",
    "--require",
    "${workspaceFolder}/test/mongo-unit-helper.js",
    "${workspaceFolder}/test/**/*.js",
  ],
  "internalConsoleOptions": "openOnSessionStart"
 }
]

Solution is to put --require separately in args in launch.json.

Simplest solution

Add the following code to the launch.json inside the .vscode folder :

{
            "name": "Unit tests",
            "type": "node",
            "request": "launch",
            "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
            "args": [
            ],
        }

You might want however to add a timeout argument as well:

 {
            "name": "Unit tests",
            "type": "node",
            "request": "launch",
            "program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
            "args": [
                "--timeout",
                "999999"
            ],
        }