Skip to content

Commit

Permalink
Stop manually wrapping readme lines
Browse files Browse the repository at this point in the history
  • Loading branch information
@domenic
domenic committed Aug 25, 2015
1 parent d6b25cf commit 815a379
Showing 1 changed file with 17 additions and 50 deletions.
67 changes: 17 additions & 50 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,24 +27,19 @@ you can write code that expresses what you really mean:
return doSomethingAsync().should.eventually.equal("foo");
```

or if you have a case where `return` is not preferable (e.g. style considerations) or not possible (e.g. the testing
framework doesn't allow returning promises to signal asynchronous test completion), then you can use the following
workaround (where `done()` is supplied by the test framework):
or if you have a case where `return` is not preferable (e.g. style considerations) or not possible (e.g. the testing framework doesn't allow returning promises to signal asynchronous test completion), then you can use the following workaround (where `done()` is supplied by the test framework):

```javascript
doSomethingAsync().should.eventually.equal("foo").notify(done);
```

*Notice*: either `return` or `notify(done)` _must_ be used with promise assertions. This can be a slight departure from
the existing format of assertions being used on a project or by a team. Those other assertions are likely synchronous
and thus do not require special handling.
*Notice*: either `return` or `notify(done)` _must_ be used with promise assertions. This can be a slight departure from the existing format of assertions being used on a project or by a team. Those other assertions are likely synchronous and thus do not require special handling.

## 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:
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:

```javascript
(2 + 2).should.equal(4);
Expand All @@ -71,8 +66,7 @@ return promise.should.be.rejectedWith(Error); // other variants of Chai's `throw

### `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:
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:

```javascript
assert.equal(2 + 2, 4, "This had better be true");
Expand All @@ -96,9 +90,7 @@ return assert.isRejected(promise, /error message matcher/, "optional message");

### Progress Callbacks

Chai as Promised does not have any intrinsic support for testing promise progress callbacks. The properties you would
want to test are probably much better suited to a library like [Sinon.JS][sinon], perhaps in conjunction with
[Sinon–Chai][sinon-chai]:
Chai as Promised does not have any intrinsic support for testing promise progress callbacks. The properties you would want to test are probably much better suited to a library like [Sinon.JS][sinon], perhaps in conjunction with [Sinon–Chai][sinon-chai]:

```javascript
var progressSpy = sinon.spy();
Expand All @@ -112,10 +104,7 @@ return promise.then(null, null, progressSpy).then(function () {

### Customizing Output Promises

By default, the promises returned by Chai as Promised's assertions are regular Chai assertion objects, extended with
a single `then` method derived from the input promise. To change this behavior, for instance to output a promise with
more useful sugar methods such as are found in most promise libraries, you can override
`chaiAsPromised.transferPromiseness`. Here's an example that transfer's Q's `finally` and `done` methods:
By default, the promises returned by Chai as Promised's assertions are regular Chai assertion objects, extended with a single `then` method derived from the input promise. To change this behavior, for instance to output a promise with more useful sugar methods such as are found in most promise libraries, you can override `chaiAsPromised.transferPromiseness`. Here's an example that transfer's Q's `finally` and `done` methods:

```js
chaiAsPromised.transferPromiseness = function (assertion, promise) {
Expand All @@ -127,8 +116,7 @@ chaiAsPromised.transferPromiseness = function (assertion, promise) {

### Transforming Arguments to the Asserters

Another advanced customization hook Chai as Promised allows is if you want to transform the arguments to the
asserters, possibly asynchronously. Here is a toy example:
Another advanced customization hook Chai as Promised allows is if you want to transform the arguments to the asserters, possibly asynchronously. Here is a toy example:

```js
chaiAsPromised.transformAsserterArgs = function (args) {
Expand All @@ -139,9 +127,7 @@ Promise.resolve(2).should.eventually.equal(2); // will now fail!
Promise.resolve(2).should.eventually.equal(3); // will now pass!
```

The transform can even be asynchronous, returning a promise for an array instead of an array directly. An example
of that might be using `Promise.all` so that an array of promises becomes a promise for an array. If you do that,
then you can compare promises against other promises using the asserters:
The transform can even be asynchronous, returning a promise for an array instead of an array directly. An example of that might be using `Promise.all` so that an array of promises becomes a promise for an array. If you do that, then you can compare promises against other promises using the asserters:

```js
// This will normally fail, since within() only works on numbers.
Expand All @@ -158,17 +144,11 @@ Promise.resolve(2).should.eventually.be.within(Promise.resolve(1), Promise.resol

### Compatibility

Chai as Promised is compatible with all promises following the [Promises/A+ specification][spec]. Notably, jQuery's
so-called “promises” are not up to spec, and Chai as Promised will not work with them. In particular, Chai as Promised
makes extensive use of the standard [transformation behavior][] of `then`, which jQuery does not support.
Chai as Promised is compatible with all promises following the [Promises/A+ specification][spec]. Notably, jQuery's so-called “promises” are not up to spec, and Chai as Promised will not work with them. In particular, Chai as Promised makes extensive use of the standard [transformation behavior][] of `then`, which jQuery does not support.

### Working with Non-Promise–Friendly Test Runners

Some test runners (e.g. Jasmine, QUnit, or tap/tape) do not have the ability to use the returned promise to signal
asynchronous test completion. If possible, I'd recommend switching to ones that do, such as [Mocha][mocha-promises],
[Buster][buster-promises], or [blue-tape][]. But if that's not an option, Chai as Promised still has you covered. As
long as your test framework takes a callback indicating when the asynchronous test run is over, Chai as Promised can
adapt to that situation with its `notify` method, like so:
Some test runners (e.g. Jasmine, QUnit, or tap/tape) do not have the ability to use the returned promise to signal asynchronous test completion. If possible, I'd recommend switching to ones that do, such as [Mocha][mocha-promises], [Buster][buster-promises], or [blue-tape][]. But if that's not an option, Chai as Promised still has you covered. As long as your test framework takes a callback indicating when the asynchronous test run is over, Chai as Promised can adapt to that situation with its `notify` method, like so:

```javascript
it("should be fulfilled", function (done) {
Expand All @@ -180,12 +160,9 @@ 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
fulfilled."`
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:
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) {
Expand All @@ -196,10 +173,7 @@ it("should change the state", function (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.
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.

### Multiple Promise Assertions

Expand All @@ -215,10 +189,7 @@ it("should all be well", function (done) {
});
```

This will pass any failures of the individual promise assertions up to the test framework, instead of wrapping them in
an `"expected promise to be fulfilled…"` message as would happen if you did
`return Promise.all([…]).should.be.fulfilled`. If you can't use `return`, then use `.should.notify(done)`, similar to
the previous examples.
This will pass any failures of the individual promise assertions up to the test framework, instead of wrapping them in an `"expected promise to be fulfilled…"` message as would happen if you did `return Promise.all([…]).should.be.fulfilled`. If you can't use `return`, then use `.should.notify(done)`, similar to the previous examples.

## Installation and Setup

Expand All @@ -233,14 +204,11 @@ 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][], see
[the Chai as Promised tests themselves][fixturedemo].
You can of course put this code in a common test fixture file; for an example using [Mocha][], see [the Chai as Promised tests themselves][fixturedemo].

### AMD

Chai as Promised supports being used as an [AMD][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:
Chai as Promised supports being used as an [AMD][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:

```javascript
define(function (require, exports, module) {
Expand All @@ -253,8 +221,7 @@ define(function (require, exports, module) {

### `<script>` tag

If you include Chai as Promised directly with a `<script>` tag, after the one for Chai itself, then it will
automatically plug in to Chai and be ready for use:
If you include Chai as Promised directly with a `<script>` tag, after the one for Chai itself, then it will automatically plug in to Chai and be ready for use:

```html
<script src="chai.js"></script>
Expand Down

0 comments on commit 815a379

Please sign in to comment.