BDD interface

Mocha supports several interfaces to organize tests. BDD interface is default interface.

function description
describe( name, func) Groups tests.

The func parameter ssshas no xsssarguments. Inside it you can define nested groups, specify the test cases and set hook functions like beforeEach.

context( name, func ) Alias for the describe() function.
it(name, func(done))

Specifies a test case code.

If func has done argument, Mocha will wait for done function to be called to complete the test. Thus you can test Promise and asynchronous code.

The done callback accepts both an Error instance or a falsy value; anything else is invalid usage and throws an error.

specify(name, func) Alias for the it() function.
before(func) Sets the function to run before all tests in the group.
beforeEach(func) Sets the function to run before each test in the group.
afterEach(func) Sets the function to run after each test in the group.
after(func) Sets the function to run after all tests in the group.

Be careful when passing lambdas to Mocha because they cannot access the Mocha context. For example, the following code will fail:

describe('my suite', () => {
  it('my test', () => {
    // should set the timeout of this test to 1000 ms; instead will fail


You can use any assertion library, for example:

  • assert - built-in Node.js assert module.
  • chai - expect(), assert() and should-style assertions.
  • expect - expect() style assertions.
  • should.js - BDD style shown throughout these docs.
  • better-assert - C-style self-documenting assert().
  • unexpected - the extensible BDD assertion toolkit.

asynchronous code

There are three main ways to test the asynchronous code with Mocha:

  1. Use done callback.
  2. Return Promise object. In this case, Mocha will add its own then () to determine if the test is complete. The done() call will be ignored (an exception will be thrown in the old versions).
  3. Using async/await keywords.
var assert = require('assert');

// our async task
function myAsyncMethod(v) {
    return new Promise((resolve, reject) => {
        if (v) {
            setTimeout(() => resolve(), 1000);
        } else {
            reject(new Error("Param is false"));

// change assert.ok(true) on your checking
describe("Test async tasks", () => {

    // with done
    // Be careful, if the async task fails, the test library 
    // will wait for our done callback potentially forever. 
    it("myAsyncMethod with done", (done) => {
        myAsyncMethod(true).then(() => {

    it("myAsyncMethod with return promise", () => {
        return myAsyncMethod(true).then(() => {

    it('myAsyncMethod with return rejected promise ', () => {
        return myAsyncMethod(false)
                () => Promise.reject(new Error('Expected method to reject.')),
                err => assert.ok(err instanceof Error)

    it('myAsyncMethod with async/wait keywords', async() => {
        await myAsyncMethod(true);

run tests in browser

Suppose you have installed Mocha and Chai in your project directory using "npm install mocha chai" command.

<!DOCTYPE html>
        <!-- styling for the test results -->
        <link rel="stylesheet" href="node_modules/mocha/mocha.css" />

        <!-- container that will display test results -->
        <div id="mocha"></div>

        <!-- mocha (test runner) -->
        <script src="node_modules/mocha/mocha.js"></script>
        <!-- chai (assertion library) -->
        <script src="node_modules/chai/chai.js"></script>
            // setup test helpers

            // your tests here
            describe('test suite', function() {
                it('some tst', function() {

            // run tests

You can also load frameworks from cdn

<link rel="stylesheet" href="" />

<script src=""></script>

<!-- You cannot directly use built-in Node.js modules like assert. 
So we load other assertion framework - Chai -->
<script src=""></script>