Learn how to harness AI for faster, more stable tests | Join us

Mocha Assertions: What They Are and How to Use Them

Test automation makes verifying an application's behavior more straightforward and consistent. Unlike manual testing, automated testing can test even the…

By Testim,

Test automation makes verifying an application’s behavior more straightforward and consistent. Unlike manual testing, automated testing can test even the smallest unit, such as a single method, without running the entire app. Usually, to perform automated tests, you’ll need a testing library. Mocha is one such library. You can test one or more methods in your JavaScript code with Mocha.

Assertions are a key part of writing automated tests with a tool like Mocha. They do the job of verifying that a piece of code returns the expected result. For example, if you have a function that adds two numbers you want to test, you can use an assert method to verify that the function’s result equals a predefined value (expectation).

There are different things we can verify using assertions. In this post, you’ll learn about assertions in Mocha and how to use them.

What Are Assertions?

Assertions are functions that verify that a result meets a specific expectation. Usually, the function we’re testing returns a result while we match that value to an expectation. A test will fail if the assertion is false.

How Do Assertions Work?

There are several types of assertion functions to test for specific behavior. These functions include the following:

  • assert.equal()
  • assert.notEqual()
  • assert.deepEqual()
  • assert.notDeepEqual()

Now let’s walk through some examples. We’ll refer to the Node.js built-in assert module for these examples.

Example 1: assert.equal()

A test using this function will pass when the two values we’re verifying are equal. In non-strict mode, it works similarly to the “==” operator. The following code shows the complete syntax for the assert.equal() method:

assert.equal(actual, expected, message);

Here the “actual” parameter is what results from the code we’re testing. Meanwhile, the “expected” parameter is the value we wish to validate. The “message” parameter is optional, and you can use it to display a custom error message when the assertion fails. If you omit “message,” the function will throw a default AssertionError message.

Example 2: assert.notEqual()

The assert.notEqual() method is the exact opposite of the equal method in the previous example. It will throw an assertion error when the two values you’re comparing are equal or identical. The following code shows the structure for this function:

assert.notEqual(actual, expected, message);

Like in the equal() function, the “actual” parameter represents the result from the tested function. However, this time the “expected” parameter is a value the actual must not equal for the test to pass. That’s to say, “actual != expected” is the condition for the test to pass. The optional message parameter lets you customize the error message when the test fails.

Example 3: assert.deepEqual()

Deep equality means testing even child elements in the value of the “actual” and “expected” parameters. Hence, we can use this function to test the result of a function that is an array against an expected array. The test will pass when both arrays are equal (containing the same child). Here’s the syntax for this function:

assert.deepEqual(actual, expected, message);

Example 4: assert.notDeepEqual()

This is the opposite of the deepEqual() function. Hence, this test will only pass when the actual and expected values are not equal. We can use this to verify that one or more child element of an array isn’t equal. The following code shows the syntax for the notDeepEqual() function:

assert.notDeepEqual(actual, expected, message);

Mocha Assertions: Does Mocha Have Built-In Assertions?

If you consider assertions as any way of determining when a test should fail or pass due to a returned result, the answer to the above question will be yes! However, Mocha has no built-in module for handling assertions like the one from Node.js we looked at in the previous section. Instead, Mocha allows developers to import their favorite assertion tools like Chai.

It’s also possible to do assertions in Mocha without any other third-party tool. One way to do this is to use a conditional statement to compare two values and manually throw an exception when the test fails. The following code demonstrates how to use the “if” statement for Mocha assertion:

describe("Test utils class", function () {
it("fail always", function () {
if (2 !== 2) throw new Error("2 should always be identical to 2");

If you run the above test and an exception is not thrown, the test passes.

How to Use Mocha Assertions When Testing Your Application

In this section, we’ll show you the steps for using assertions in Mocha to test your applications. We’ll be using the Node.js assert module and other third-party assertion tools.

Step 1: Install Mocha

To use Mocha in your project, you first need to install it. To install Mocha, run the following command from your project directory:

npm install --save-dev mocha

Step 2: Write Your Test

We’ll test a custom method that adds two numbers for this example. To write your test, create a new specs folder at the root of your project directory. Next, create a new test file and save it as test.spec.js inside the specs folder, then add the following code to the file:

var Utils = require("../src/utils");
var assert = require("assert");

var utilsObj = new Utils();

describe("Test utils class", function () {
  it("add two numbers", function () {
    assert.equal(utilsObj.add(2, 2), 4);

To run the above code without any modifications, create your own Utils class and include the add() method. Here’s a sample of the code from the Utils class for this example:

class Utils {

  add(a, b) {
    return a + b;

module.exports = Utils;

Step 3: Run the Test

To run the test, ensure you configure the test command for your project. Doing this will help Mocha know which directory to look for test files.

The following code includes the sample configuration for this example:

"scripts": {
    "test": "mocha './specs/*.spec.js'"

You should add the above configuration to your project’s package.json file.

After the above configuration, run the following command to start the test:

npm run test

Since the result for 2+2 is 4, your test should pass with the following output in the terminal:

Test utils class
    ✔ add two numbers

  1 passing (3ms)

Step 4: Repeat Test Using Other Assertion Tools

We’ll repeat our last test using different third-party assertion libraries in this step.

1. Using Chai

To run the same test using the Chai library, first install Chai using the following command:

npm install chai

Next, modify the content of your test.spec.js file to the following:

var Utils = require("../src/utils");
var assert = require("chai");

var utilsObj = new Utils();

describe("Test utils class", function () {
  it("add two numbers", function () {
    assert.expect(utilsObj.add(2, 2)).to.equal(4);

One advantage of assertion libraries like Chai is that they offer more human-readable code.

2. Expect.js

Let’s rerun the same test using the Expect.js assertion library. First, install the package by running the following command:

npm install expect

After the installation is complete, modify the content of test.spec.js to the following, then rerun the test:

var Utils = require("../src/utils");
var assert = require("expect");

var utilsObj = new Utils();

describe("Test utils class", function () {
  it("add two numbers", function () {
    assert.expect(utilsObj.add(2, 2)).toEqual(4);

If you followed this correctly, the test should pass again. Just like Chai, Expect.js offers a more human-readable syntax for performing assertions. In addition, it provides many functions for verifying different things in your tests.


Though Mocha has no built-in functions for assertions, it is possible to do assertions using different techniques. In this post, we explained what Mocha assertions are and walked through different ways of doing them.

Finally, the assertion techniques we covered in this post include using Node.js built-in assertion functions, pairing a conditional statement with throwing an exception and using a third-party assertion library. Your test needs may determine the technique you decide to use. You can check their official documentation to learn more about the full features of Node.js assertions and the third-party assertion libraries.

Expand Your Test Coverage

Fast and flexible authoring of AI-powered end-to-end tests — built for scale.
Start Testing Free

Testim's latest articles, right in your inbox.

From our latest feature releases, to the way it impacts the businesses of our clients, follow the evolution of our product

[formidable id=2]