chai-as-promised

What is chai-as-promised?

The chai-as-promised npm package extends Chai with a fluent language for asserting facts about promises. It allows developers to work with promises in their test assertions in a more natural and expressive way, which is particularly useful when dealing with asynchronous operations in tests.

What are chai-as-promised's main functionalities?

Asserting a promise is fulfilled

This feature allows you to assert that a promise will be fulfilled. In other words, it checks that the promise will eventually resolve.

expect(promise).to.be.fulfilled;

Asserting a promise is rejected

This feature allows you to assert that a promise will be rejected. This is useful for testing error handling in asynchronous code.

expect(promise).to.be.rejected;

Asserting a promise is rejected with a specific error

With this feature, you can assert that a promise is not only rejected but also that it is rejected with a specific type of error.

expect(promise).to.be.rejectedWith(Error);

Asserting a promise's fulfillment value

This feature allows you to assert what value a promise will be resolved with. The 'eventually' chain is used to wait for the promise to resolve before making the assertion.

expect(promise).to.eventually.equal('foo');

Chaining assertions

chai-as-promised supports chaining assertions, allowing for more complex assertions on the resolved value of a promise.

expect(promise).to.eventually.have.property('bar').that.is.a('string');

Other packages similar to chai-as-promised

jest

Jest is a testing framework that includes its own assertion library and has built-in support for testing asynchronous code. It can handle promises and async/await syntax without the need for additional plugins.

expect

Expect is an assertion library that can be used independently or with Jest. It provides a way to make assertions about promises, similar to chai-as-promised, but it is more tightly integrated with Jest when used in that context.

README

Chai Assertions for Working with Promises

Chai as Promised extends Chai with a fluent language for asserting facts about promises.

Instead of manually wiring up your expectations to a promise's fulfilled and rejected handlers:

doSomethingAsync().then(
    function (result) {
        result.should.equal("foo");
        done();
    },
    function (err) {
       done(err);
    }
);

you can write code that expresses what you really mean:

doSomethingAsync().should.eventually.equal("foo").then(done, done);

or if you have a testing framework that follows the UncommonJS specification for handling promises, simply

return doSomethingAsync().should.eventually.equal("foo");

How to Use

The most powerful extension provided by Chai as Promised is the eventually property. With it, you can transform any existing Chai assertion into one that acts on a promise:

(2 + 2).should.equal(4);

// becomes
return promiseFor(2 + 2).should.eventually.equal(4);

({ foo: "bar" }).should.have.property("foo");

// becomes
return promiseFor({ foo: "bar" }).should.eventually.have.property("foo");

There are also a few promise-specific extensions, grouped here as synonymic blocks:

return promise.should.be.fulfilled;

return promise.should.be.rejected;
return promise.should.be.broken;

return promise.should.eventually.eql("foo");
return promise.should.become("foo");

return promise.should.be.rejected.with(Error);
return promise.should.be.broken.with(Error);

// Note: other variants of Chai's existing `throw` assertion work too.

Installation and Usage

Node

Do an npm install chai-as-promised to get up and running. Then:

var chai = require("chai");
var chaiAsPromised = require("chai-as-promised");

chai.use(chaiAsPromised);

You can of course put this code in a common test fixture file; for an example using [Mocha][mocha], see the Chai as Promised tests themselves.

AMD

Chai as Promised supports being used as an AMD module, registering itself anonymously (just like Chai). So, assuming you have configured your loader to map the Chai and Chai as Promised files to the respective module IDs "chai" and "chai-as-promised", you can use them as follows:

define(function (require, exports, module) {
    var chai = require("chai");
    var chaiAsPromised = require("chai-as-promised");

    chai.use(chaiAsPromised);
});

<script> tag

If you include Chai as Promised directly with a <script> tag, it creates a window.chaiAsPromised global (again, just like Chai). Then your setup code becomes:

window.chai.use(window.chaiAsPromised);