How to set up a test runner for modern JavaScript using Webpack, Mocha, and Chai

We've all been there: You're about to build another front-end feature. You know you want to start unit testing your JavaScript. You know that because React employs one-way data binding, it means writing tests is made easier than the Backbone MVC days of yore. But the setup... oh my, the setup. It's painful. There are so many tools, so much boilerplate. So you say to yourself, we'll do it next sprint.

But then the regressions start mounting. Your team is frustrated when QA sends back your work and tells you the new thing works, but that you broke 2 old things. And so now you're back to the grind, trying to ship a working build before the end of the week.

We've all been there, but let's put our procrastination to rest once and for all. The truth is, JavaScript testing is more awesome than ever. It might not be as distilled as say, Rails testing. But after reading this guide, you'll be able to go back to your team and proudly say this is the week you start testing your JavaScript.

If you've already read the guide, or just want to play around with some real, working code, I've prepared an example app here: Webpack+Mocha+Chai Example


Right now, the landscape of tools for testing JavaScript is large. In this guide, we're going to focus on what I've found to be the most productive combination:

  • Mocha to run our tests.
  • Chai to make assertions.
  • Webpack to glue everything together.

Install Packages

I'll assume you're already familiar with npm, have created a package.json file, and are using it in your project. If not, here's a tutorial to get you started. The npm command installs packages you want to use in your application and provides an interface for working with them. We're going to install the packages that will support our tests. Because these packages are for our development use only, we use the --save-dev option when running npm:

npm install --save-dev webpack mocha chai mocha-webpack

Create a Webpack Configuration

Webpack is a module bundler for the web. You might have used Browserify or CommonJS in the past to modularize your JavaScript. Webpack takes this paradigm a step further and lets you produce a dependency for just about any type of file. A full explanation of the tool is outside the scope of this tutorial, but Ryan Christiani has a great Introduction to Webpack tutorial to get you started.

For now, create a file webpack.config.js and fill it with the following:

var webpack = require('webpack');

module.exports = {
    module: {
        loaders: [
                test: /.*\.js$/,
                exclude: /node_modules/,
                loaders: ['babel']
    entry: 'index.js',
    resolve: {
        root: [ __dirname, __dirname + '/lib' ],
        extensions: [ '', '.js' ]
    output: {
        path: __dirname + '/output',
        filename: 'app.bundle.js'

Configure Babel

Babel is a JavaScript compiler that allows us to use next generation JavaScript (ES6, ES7, etc) in browsers that only support ES5. As you'll see when we begin writing tests, having ES6 import statements and fat arrow function notation (() => { }) will make our tests more readable and require less typing.

You'll notice, in the loaders section above, we're using the babel loader to process our JavaScript. This will allow us to write our application and test code in ES6. However, Babel requires that we configure it with presets, which will tell Babel how it should process our input code.

For our example, we need just one preset: es2015. This tells Babel we want to use the ECMAScript 2015 standard so we can use things like the import and export statements, class declarations, and fat arrow (() => {}) function syntax.

To use the preset, we'll first install its package using npm:

npm install --save-dev babel-preset-es2015

Then, we'll tell Babel to use it by creating a .babelrc file:

    "presets": [

Create the entry file and test Webpack configuration

Our Webpack configuration states that our entry file, the JavaScript module Webpack will run when our bundle is included in the page, is index.js. So let's create that file now. For now, let's just alert "Hello, World!". We're not going to run this code anyway, since we're really just using this entry file to be sure Webpack is configured properly.

// index.js

alert("Hello, World!");

Then we'll create an output directory. This is where we've configured Webpack to write our bundle file:

mkdir output

If we've configured everything properly, running Webpack should spit out our bundle file:


If the file output/app.bundle.js is present and you can locate our alert("Hello, World!") code in its contents, then you've configured Webpack successfully!

Set up the Mocha runner command

NPM has a scripts configuration option that allows creating macros for running common commands. We'll use this to create a command that will run our test suite on the command line.

In your package.json file, add the following key to the JSON hash:

  "scripts": {
    "test": "mocha-webpack --webpack-config webpack.config.test.js \"spec/**/*.spec.js\" || true"

For an actual example of this command in a real package.json file, see the package.json file in the example code.

Dang though, that is one hefty command. Let's go through this piece by piece.

First, we're assigning this to the test command. That means that when we run npm run test, NPM will execute the mocha-webpack --webpack-config ... command for us.

The mocha-webpack executable is a module that precompiles your Webpack bundles before running Mocha, which actually runs your tests. Now, mocha-webpack is designed for server-side code, but so far I haven't had any problems using it for client-side JavaScript. Your mileage may vary.

When we call the mocha-webpack command, we pass it the --webpack-config option with the argument webpack.config.test.js. This tells mocha-webpack where to find the Webpack configuration file to use when precompiling our bundle. Notice that the file has a .test suffix and that we haven't created it yet. We'll do that in the next step.

After that, we pass mocha-webpack a glob of our test files. In this case, we're passing it spec/**/*.spec.js, which means we'll run all the test files contained within the spec folder and all folders within it.

And finally, we append || true to the end of the command. This tells NPM that in the event of an error (non-zero) exit code from the mocha-webpack command, we shouldn't assume something horrific went wrong and print a lengthy error message explaining that something probably did. Most of the time we run tests, a test or few will fail, resulting in a non-zero exit status. This addition cleans up our output a bit so we don't have to read a nagging error message each time. I'm sure the NPM team meant well when they added this message, but I think it's a bit silly we have to resort to this to remove it. If you know a better way, leave a comment!

Create our test Webpack configuration

Because we're running our tests on the command line and not in the browser, we need to be sure to tell Webpack that our target environment is Node and not browser JavaScript. To do this, we'll create a specialized test Webpack configuration which targets Node in webpack.config.test.js:

var config = require('./webpack.config'); = 'node';
module.exports = config;

I also want to point out how nice it is that Webpack configurations are just plain JavaScript objects. We're able to require our base configuration, set the target property, and then export the modified configuration. This pattern is especially useful when producing production configuration files, but that's a topic for another guide.

Write a basic test

It's the moment we've been waiting for! We've laid the foundation for testing in our project. Now let's write a basic (failing) test to see Mocha in action!

Create the spec directory in your project if you haven't already. Before we get testing React components, let's just try our hand at testing a plain old function. Let's call that function sum, and test that it does indeed sum two numbers. I know, it's real exciting. But it'll give us confidence our test setup is working.

Create a file spec/sum.spec.js with the following:

import sum from 'sum';
import { expect } from 'chai';

describe("sum", () => {
    context("when both arguments are valid numbers", () => {
        it("adds the numbers together", () => {

Let's go over that one line at a time.

First, we import a function called sum from a module called 'sum'. You probably guessed we're going to need to create that file. You guessed right.

Create the file lib/sum.js:

export default function() { }

Note that we're creating the file inside the lib folder. Way back in step 2, we told Webpack that we should resolve modules in both the root folder as well as the /lib folder. We use lib because it indicates to other developers that this file is part of our application library code, as opposed to a test, or configuration, or our build system, etc.

Assertion Styles

The second line in our test file imports a function expect from the Chai module. Chai has a couple different assertion styles which dictate how tests will be written. Without going too far into the details, it means your tests could either read like this:

Assert that x is 10.

Or like this:

Expect x to be 10.

Or like this:

x should be 10.

This is largely a matter of developer preference. In my time as a developer, I've seen the Ruby community shift its consensus from assert, toward should, and now toward expect. So let's settle on expect for now.

Run our test suite

Now that we've created our spec/sum.spec.js file, let's go ahead and run our npm run test command:

npm run test

> react-webpack-testing-example@1.0.0 test /Users/teejayvanslyke/src/react-webpack-testing-example
> mocha-webpack --webpack-config webpack.config.test.js "spec/**/*.spec.js" || true

  when both arguments are valid numbers
    1) adds the numbers together

0 passing (7ms)
1 failing

1) sum when both arguments are valid numbers adds the numbers together:
  AssertionError: expected undefined to equal 3
    at Context.<anonymous> (.tmp/mocha-webpack/01b73f0d4e3c95d9c729f459c86e1fc4/01b73f0d4e3c95d9c729f459c86e1fc4-output.js:93:61)

Success! Well, sort of. Our test runs, but it looks like it's failing because we never implemented the sum function. Let's do that now.

Make the test pass

Let's make our sum function take two arguments, a and b. We'll return the result of adding both of them together, like so:

export default function(a, b) { return a + b; }

Now run our test again. It passes!

npm run test

> react-webpack-testing-example@1.0.0 test /Users/teejayvanslyke/src/react-webpack-testing-example
> mocha-webpack --webpack-config webpack.config.test.js "spec/**/*.spec.js" || true

  when both arguments are valid numbers
    ✓ adds the numbers together

1 passing (6ms)

Watch for changes to streamline your workflow

Now that we've written a passing test, we'll want to iterate on our math.js library. But rather than running npm run test every time we want to check the pass/fail status of our tests, wouldn't it be nice if it ran automatically whenever we modified our code?

Mocha includes a --watch option which does exactly this. When we pass mocha-webpack the --watch option, Mocha will re-run our test suite whenever we modify a file inside our working directory.

To enable file watching, let's add another NPM script to our package.json:

  "scripts": {
    "test": "mocha-webpack --webpack-config webpack.config.test.js \"spec/**/*.spec.js\" || true",
    "watch": "mocha-webpack --webpack-config webpack.config.test.js --watch \"spec/**/*.spec.js\" || true"

Notice how the watch script just runs the same command as the test script, but adds the --watch option. Now run the watch script:

npm run watch

Your test suite will run, but you'll notice the script doesn't exit. With the npm run watch command still running, add another test to spec/sum.spec.js:

import sum from 'sum';
import { expect } from 'chai';

describe("sum", () => {
    context("when both arguments are valid numbers", () => {
        it("adds the numbers together", () => {

    context("when one argument is undefined", () => {
        it("throws an error", () => {
            expect(sum(1,2)).to.throw("undefined is not a number");

Save the file. Mocha will have re-run your suite, and it should now report that your new test fails.

Reduce duplication in package.json

In the previous step, we copied and pasted the test script into the watch script. While this works fine, copy and paste should bother every developer just a little bit.

Luckily, mocha-webpack provides a way to specify the default options to the command so we needn't include them in each line of our package.json's scripts section.

Create a new file called mocha-webpack.opts in your project's root directory:

--webpack-config webpack.config.test.js

And now, your package.json file can be shortened like this:

  "scripts": {
    "test": "mocha-webpack || true",
    "watch": "mocha-webpack --watch || true"

Helpful links

Hiring A Software Consultant? Read This First

You're about to embark upon your first custom software build, but you're terrified at the breadth of terminology and wary of consultants nickel-and-diming you.

My free book Why Software Projects Fail offers that framework. In this companion to your hiring and discovery process, you'll learn how to inform your next decisions and to empower yourself along the way.

In the book, you'll learn:

  • How to find and hire a trustworthy consultant
  • Why it's critical you pay for a software discovery
  • How to assess your consultant's bid
  • What to expect—and be wary of—during the development process
  • How to take control of your project

Enter your email address below and then click the "Send Me My Free Gift" button. I'll send you Why Software Projects Fail, and you'll be equipped for success on your next project.