Browse files

Release 2.1.0, with updated documentation.

  • Loading branch information...
1 parent 265bf04 commit 5ff21e998e9859494b37e749245cbba902052473 @domenic committed Apr 12, 2012
Showing with 43 additions and 3 deletions.
  1. +42 −2
  2. +1 −1 package.json
@@ -30,7 +30,9 @@ simply
return doSomethingAsync().should.eventually.equal("foo");
-## How to Use: `should`/`expect` Interface
+## How to Use
+### `should`/`expect` Interface
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:
@@ -66,7 +68,7 @@ return;
// Note: other variants of Chai's existing `throw` assertion work too.
-## How to Use: `assert` Interface
+### `assert` Interface
As with the `should`/`expect` interface, Chai as Promised provides an `eventually` extender to `chai.assert`, allowing
any existing Chai assertion to be used on a promise:
@@ -99,6 +101,43 @@ return assert.isRejected(promise, /error message matcher/, "optional message");
return assert.isBroken(promise, /error message matcher/, "optional message");
+### Working with Non-Promise–Friendly Test Runners
+As mentioned, many test runners (\*cough\* [mocha][mocha-makes-me-sad] \*cough\*) don't support the nice `return` style
+shown above. Instead, they take a callback indicating when the asynchronous test run is over. Chai as Promised adapts to
+this situation with the `notify` method, like so:
+it("should be fulfilled", function (done) {
+it("should be rejected", function (done) {
+In these examples, if the conditions are not met, the test runner will receive an error of the form `"expected promise
+to be fulfilled but it was rejected with [Error: error message]"`, or `"expected promise to be rejected but it was
+There's another form of notify which is useful in certain situations, like doing assertions after a promise is complete.
+For example:
+it("should change the state", function (done) {
+ otherState.should.equal("before");
+ () {
+ otherState.should.equal("after");
+ }).should.notify(done);
+Notice how `.notify(done)` is hanging directly off of `.should`, instead of appearing after a promise assertion. This
+indicates to Chai as Promised that it should pass fulfillment or rejection directly through to the testing framework.
+Thus, the above code will fail with a Chai as Promised error (`"expected promise to be fulfilled…"`) if `promise` is
+rejected, but will fail with a simple Chai error (`expected "before" to equal "after"`) if `otherState` does not change.
## Installation and Usage
### Node
@@ -143,6 +182,7 @@ window.chai.use(window.chaiAsPromised);
@@ -6,7 +6,7 @@
- "version": "2.0.0",
+ "version": "2.1.0",
"author": "Domenic Denicola <> (",
"repository": {
"type": "git",

0 comments on commit 5ff21e9

Please sign in to comment.