Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Release 2.1.0, with updated documentation.

  • Loading branch information...
commit 5ff21e998e9859494b37e749245cbba902052473 1 parent 265bf04
@domenic authored
Showing with 43 additions and 3 deletions.
  1. +42 −2 README.md
  2. +1 −1  package.json
View
44 README.md
@@ -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 promise.should.be.broken.with(Error);
// 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:
+
+```javascript
+it("should be fulfilled", function (done) {
+ promise.should.be.fulfilled.and.notify(done);
+});
+
+it("should be rejected", function (done) {
+ otherPromise.should.be.rejected.and.notify(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
+fulfilled."`
+
+There's another form of notify which is useful in certain situations, like doing assertions after a promise is complete.
+For example:
+
+```javascript
+it("should change the state", function (done) {
+ otherState.should.equal("before");
+ promise.should.be.fulfilled.then(function () {
+ 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);
[presentation]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript
[chai]: http://chaijs.com/
[mocha]: http://visionmedia.github.com/mocha/
+[mocha-makes-me-sad]: https://github.com/visionmedia/mocha/pull/329
[uncommonjs]: http://kriskowal.github.com/uncommonjs/tests/specification
[fixturedemo]: https://github.com/domenic/chai-as-promised/tree/master/test/
[amd]: https://github.com/amdjs/amdjs-api/wiki/AMD
View
2  package.json
@@ -6,7 +6,7 @@
"testing",
"promises"
],
- "version": "2.0.0",
+ "version": "2.1.0",
"author": "Domenic Denicola <domenic@domenicdenicola.com> (http://domenicdenicola.com)",
"repository": {
"type": "git",
Please sign in to comment.
Something went wrong with that request. Please try again.