Debugging mocha unit tests with WebStorm step by step

Update: WebStorm now supports debugging with Mocha. Kudos to David Henderson for pointing that out in the comments and of course to Jet Brains for making it work!

WebStorm is a pretty awesome IDE (there Hadi, I said it!) which I do not use enough! As a node.js developer one of the great features it offers is a really nice debugging story, something that MANY node developers die without long for. It also has support for various test runners like nodeunit and mocha. Can we put those features together though? I mean can we debug our mocha unit tests in WebStorm? I’ve been wondering this for a while and just the other day Josh and I were chatting about it.

After a bit of investigating, I can say the answer is YES. If you search around the internets you’ll find a post which describes how to do it. In this post I’ll show you step by step exactly how to do it with screenshots :-)

Prereq – Install mocha

npm install mocha –g. (use sudo if you need to)

Step 1 – Open your project

Launch WebStorm and then open the node project that includes your mocha tests.

Screen Shot 2013-01-16 at 10.32.45 PM

Step 2 – Create a new Run/Debug configuration

Click on Run->Edit Configurations in the menu or select “Edit Configurations” from the configuration drop down. Then press the + to add a new configuration and select “Node.js”.

Screen Shot 2013-01-16 at 10.39.54 PM

Step 3 – Enter the configuration information

Now there’s a few pieces of information you need to enter.

  • Path to Node: Should be set by default, but if you have a specific node version you want, see it here.
  • Path to Node App JS File: This should point to where your mocha module is installed globally. It’s very important that you point to the _mocha file as you can see below.
    • On Mac / Linux it will be in /usr/local/lib/node_modules/mocha.
    • On Windows you’ll find it in your %APPDATA%/npm/node_modules/mocha folder.
  • Application Parameters: If you want to debug a specific file (rather than running all) put the name of the file you want to debug (cli-buddy-tests.js in the example) as well as any additional mocha params.
  • If your tests rely on any environment variables, set those in the “Environment Variables Window”

Screen Shot 2013-01-16 at 10.01.59 PM

Step 4 – Add a break point and go!

Add a break point for where you want to start debugging. Then hit the debug button are you are on your way.

Screen Shot 2013-01-16 at 10.01.15 PM

As you can see above I hit my breakpoint. I can now step, see variables, etc.

All I can say is booyah.js!

This entry was posted in node.js, webstorm. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Shujaat Ali Chand

    thanks man it helped me a lot, a little addition to this is for the people who are using latest web storm, i didn’t get “Path to node js file” instead i added the _mocha path in “Javascript file” filed and it worked for me

  • Nikos

    How can I debug chai tests? Do I also need mocha? I’m running tests with just chai + wallabyjs

  • Glenn Block

    I updated the blog to tell people. Thanks!

  • Glenn Block

    Of course, because Hadi is a good friend and an AVID follower of my blog :-) #joke (not the friends part) This is good to see!

  • David Henderson

    There’s now no need – the latest Webstorm release supports Mocha natively. See

  • Steve Gentile

    Very helpful thanks – now if I could just figure out how to set it up to run node first then mocha – seems when I try to run node as a pre-config to my mocha – it runs the node but the mocha doesn’t run

  • Glenn Block


    Yes, it is due to the spawning. I didn’t want to go into detail which is why I put ‘It’s very important that you point to the _mocha file as you can see below.’, however if you think it is valuable to add I can.

    @ryan. Glad it helped!

  • Ryan Regalado

    Thanks for posting. This was super helpful in a node.js app I’ve been debugging and writing tests for. Awesome

  • Andy Fleming

    Answering my own question, but might be worth updating the post.

    From the linked post:
    “Pointing the run configuration to _mocha is quite important since the main mocha binary spawns a new process you cannot connect via a debugger!”

  • Andy Fleming

    Quick question: Why is it “very important that you point to the _mocha file” rather than the mocha file.

    Looking at the source it seems mocha is a wrapper for the “real” _mocha – but presumably they’ve done this for a reason and you’re bypassing it?

    Just curious :)