Mocha Test Explorer for Visual Studio Code

Run your Mocha tests using the Test Explorer UI.

Features

• Shows a Test Explorer in the Test view in VS Code's sidebar with all detected tests and suites and their state
• Adds CodeLenses to your test files for starting and debugging tests
• Adds Gutter decorations to your test files showing the tests' state
• Adds line decorations to the source line where a test failed
• Shows a failed test's log when the test is selected in the explorer
• Lets you choose test suites or individual tests in the explorer that should be run automatically after each file change

Getting started

• Install the extension and restart VS Code
• Put your Mocha command line options (if you have any) in a mocha configuration file (either a .mocharc.* file or a mocha property in your package.json or a mocha.opts file) or VS Code's settings (see below)
• Ensure that your project's root folder is a VS Code root folder. If you are using a "monorepo" architecture (ie. a single repository with multiple projects in separate sub-folders), you may need to add your project sub-folders to VS Code separately. See this article on multi-root workspaces for further details on how to add folders.
• Open the Test view by clicking on the flask icon in the Activity Bar
• Run / Debug your tests using the / icons in the Test Explorer or the CodeLenses in your test file

Using transpilers (Typescript, Babel, etc.)

If you use a transpiler in your project, there are 2 ways to make the tests work in Mocha Test Explorer. The first one is easier to configure, the second one offers better performance (especially in large projects):

• running the original (non-transpiled) sources directly by transpiling them on-the-fly using ts-node for Typescript, babel-register for Babel, etc. Example for Typescript:

  "mochaExplorer.files": "test/**/*.ts",
  "mochaExplorer.require": "ts-node/register"

• enabling source-maps in your transpiler's configuration and running the transpiled test sources using the source-map-support package. Furthermore, you should tell Mocha Test Explorer which files to watch for changes. For example:

  "mochaExplorer.files": "out/test/**/*.js",
  "mochaExplorer.require": "source-map-support/register",
  "mochaExplorer.watch": "out/**/*.js"

  mochaExplorer.watch can be a string, an array of strings or an object with the properties files and optionally ignore and debounce. Make sure that it references the source files of your tests and of the application under test. Watching files consumes system resources, so it shouldn't reference more files than necessary. For this reason, ignore is set to **/node_modules/** by default.

Running VS Code extension tests using vscode-test

Mocha Test Explorer supports running VS Code extension tests using vscode-test: Install the mocha-explorer-launcher-scripts package and add the following settings to your project:

"mochaExplorer.launcherScript": "node_modules/mocha-explorer-launcher-scripts/vscode-test",
"mochaExplorer.autoload": false,
"mochaExplorer.ipcRole": "server",
"mochaExplorer.env": {
  "VSCODE_VERSION": "insiders",
  "ELECTRON_RUN_AS_NODE": null
}

Depending on the structure of your project's tests you may have to add more settings (e.g. mochaExplorer.files, mochaExplorer.ui or mochaExplorer.require). The environment variable VSCODE_VERSION is passed to the runTests() function from the vscode-test package, it specifies the version of VS Code to be used for testing. Note that this needs to be different from the version you're using for development, so if you're using VS Code Insiders, then you must set this variable to "stable".

A sample project for running vscode-test tests using Mocha Test Explorer is available here.

Running tests remotely

If you want/need to run your tests in a remote environment (e.g. in a docker container or on another machine via ssh), you can do so by writing a "launcher script": this script will be called by Mocha Test Explorer (instead of its standard worker script) to load and run the tests in the remote environment. Documentation for writing launcher scripts can be found in the vscode-test-adapter-remoting-util package, which also contains utility functions for writing your launcher script. There are also example projects containing well-documented launcher scripts for running your tests in a docker container or on another machine via ssh.

Alternatively, you can use VS Code Remote Development to move your workspace to the remote environment. If you do so, your tests will also be run in this environment automatically. This is easier to set up (because you don't need to write a launcher script), but requires that your entire workspace and large parts of VS Code run in the remote environment, which (depending on the environment) may be impractical or even impossible.

Configuration

Mocha command line options

You can put any command line options into a mocha configuration file or the legacy mocha.opts file. For mocha.opts, this adapter will use the path test/mocha.opts by default but you can override that with the mochaExplorer.optsFile setting.

Alternatively, you can put supported options into VS Code's settings:

Options from VS Code's settings will override those found in a mocha configuration file.

Custom debugger configuration

If you want to customize the configuration used for debugging your tests (e.g. to set sourceMapPathOverrides or skipFiles), you can do so by creating a debugging configuration in your launch.json and setting mochaExplorer.debuggerConfig to the name of your debugging configuration. Here's the default debugging configuration used by this adapter:

{
  "name": "Debug Mocha Tests",
  "type": "pwa-node",
  "request": "attach",
  "port": 9229,
  "continueOnAttach": true,
  "autoAttachChildProcesses": false,
  "resolveSourceMapLocations": [
    "!**/node_modules/**",
    "!**/.vscode/extensions/hbenl.vscode-mocha-test-adapter-*/**"
  ],
  "skipFiles": [
    "<node_internals>/**"
  ]
}

Other options

Commands

The following commands are available in VS Code's command palette, use the ID to add them to your keyboard shortcuts:

Troubleshooting

If the Test view doesn't show your tests or anything else doesn't work as expected, you can turn on diagnostic logging using one of the following configuration options (note: in multi-root workspaces, these options are always taken from the first workspace folder):

• mochaExplorer.logpanel: Write diagnostic logs to an output panel
• mochaExplorer.logfile: Write diagnostic logs to the given file

Note that the logs usually contain a lot of stacktraces, but if a stacktrace starts with "[INFO] Worker: Looking for \<some path> in Error", then that stacktrace doesn't mean that something went wrong: such stacktraces are used to find the location of a test in a file.

There is a bug in Node 10.6.0 - 10.9.0 that breaks this adapter. If you're using a version of Node affected by this bug, add "mochaExplorer.nodePath": null to your configuration as a workaround.

If you think you've found a bug, please file a bug report and attach the diagnostic logs.