assert.rejects() Function in Node.js

Node.js provides a set of assert functions that are extremely useful when writing tests for your applications. One such function is the assert.rejects(), which plays an essential role when testing asynchronous functions that are expected to reject a promise. In this blog, we’ll explore what assert.rejects() is, how it works, and how you can use it effectively in your Node.js tests.

What is assert.rejects() in Node.js?

The assert.rejects() function in Node.js is a part of the built-in assert module. This function is used to verify that a promise returned by an asynchronous function is rejected. If the promise resolves instead of rejecting, the test will fail.

Syntax of assert.rejects()

The syntax of the assert.rejects() method is as follows:

assert.rejects(promise, [error], [message]);

• promise: The asynchronous operation or promise you are testing.
• error (optional): This argument checks for a specific error. If provided, it will compare the rejection reason with this error.
• message (optional): This is a custom error message that will be displayed if the assertion fails.

How Does assert.rejects() Work?

When you use assert.rejects(), Node.js will execute the asynchronous function that returns a promise. If the promise is rejected, it means the test passes. However, if the promise resolves (i.e., the function doesn't throw an error or reject the promise), the test fails.

Additionally, you can specify a particular error you expect the promise to reject with. If the promise rejects with a different error, or does not reject at all, the test will fail.

Example of Using assert.rejects()

Let’s take a look at a basic example where assert.rejects() is used to test an asynchronous function that is expected to reject:

const assert = require('assert');

async function exampleAsyncFunction() {
    return Promise.reject(new Error('Something went wrong'));
}

assert.rejects(exampleAsyncFunction(), {
    name: 'Error',
    message: 'Something went wrong'
}, 'The promise did not reject as expected');
    

In this example, the exampleAsyncFunction returns a promise that gets rejected with an error. The assert.rejects() function verifies if the rejection occurs and matches the expected error.

Handling Specific Error Types

If you want to check for specific error types, you can pass an expected error object as the second argument to assert.rejects(). This allows you to make sure that the promise rejection corresponds to a particular error. Let’s consider an example:

async function throwError() {
    throw new TypeError('Invalid data type');
}

assert.rejects(throwError(), {
    name: 'TypeError',
    message: 'Invalid data type'
});
    

In this example, we test that throwError() rejects with a TypeError having the message Invalid data type. If the function throws a different error or does not throw anything, the test will fail.

When to Use assert.rejects()

Using assert.rejects() is particularly helpful when you are writing unit tests for asynchronous functions that are expected to fail under certain conditions. It ensures that your functions behave as expected when they encounter errors, and helps in maintaining the reliability of your code by catching issues early.

Conclusion

The assert.rejects() function is a valuable tool for testing asynchronous code that is expected to reject a promise. It simplifies the process of verifying that promises are rejected and provides an easy way to handle error validation. By integrating assert.rejects() into your Node.js testing suite, you can ensure that your application behaves correctly even in the presence of errors and failures.