{
  "name": "chai-as-promised",
  "description": "Extends Chai with assertions about promises.",
  "keywords": [
    "chai",
    "testing",
    "assertions",
    "promises",
    "promises-aplus"
  ],
  "version": "4.1.0",
  "author": {
    "name": "Domenic Denicola",
    "email": "domenic@domenicdenicola.com",
    "url": "http://domenicdenicola.com"
  },
  "license": "WTFPL",
  "repository": {
    "type": "git",
    "url": "git://github.com/domenic/chai-as-promised.git"
  },
  "bugs": {
    "url": "https://github.com/domenic/chai-as-promised/issues"
  },
  "main": "./lib/chai-as-promised.js",
  "scripts": {
    "test": "mocha",
    "test-browser-q": "coffee ./test/browser/runner.coffee q",
    "test-browser-when": "coffee ./test/browser/runner.coffee when",
    "lint": "jshint ./lib",
    "cover": "cover run node_modules/mocha/bin/_mocha && cover report html && opener ./cover_html/index.html"
  },
  "peerDependencies": {
    "chai": ">= 1.7.0 < 2"
  },
  "devDependencies": {
    "chai": "~1.8.1",
    "coffee-script": "~1.6.3",
    "cover": "~0.2.8",
    "ecstatic": "~0.4.12",
    "glob": "~3.2.6",
    "jshint": "~2.3.0",
    "mocha": "~1.13.0",
    "opener": "~1.3",
    "q": "~0.9.7",
    "underscore": "~1.5.2"
  },
  "readme": "<a href=\"http://promises-aplus.github.com/promises-spec\">\n    <img src=\"http://promises-aplus.github.com/promises-spec/assets/logo-small.png\"\n         align=\"right\" valign=\"top\" alt=\"Promises/A+ logo\" />\n</a>\n\n# Chai Assertions for Promises\n\n**Chai as Promised** extends [Chai][chai] with a fluent language for asserting facts about [promises][presentation].\n\nInstead of manually wiring up your expectations to a promise's fulfilled and rejected handlers:\n\n```javascript\ndoSomethingAsync().then(\n    function (result) {\n        result.should.equal(\"foo\");\n        done();\n    },\n    function (err) {\n       done(err);\n    }\n);\n```\n\nyou can write code that expresses what you really mean:\n\n```javascript\ndoSomethingAsync().should.eventually.equal(\"foo\").notify(done);\n```\n\nor if you have a testing framework that follows the [UncommonJS specification][uncommonjs] for handling promises,\nsimply\n\n```javascript\nreturn doSomethingAsync().should.eventually.equal(\"foo\");\n```\n\n## How to Use\n\n### `should`/`expect` Interface\n\nThe most powerful extension provided by Chai as Promised is the `eventually` property. With it, you can transform any\nexisting Chai assertion into one that acts on a promise:\n\n```javascript\n(2 + 2).should.equal(4);\n\n// becomes\nreturn promiseFor(2 + 2).should.eventually.equal(4);\n\n\nexpect({ foo: \"bar\" }).to.have.property(\"foo\");\n\n// becomes\nreturn expect(promiseFor({ foo: \"bar\" })).to.eventually.have.property(\"foo\");\n```\n\nThere are also a few promise-specific extensions (with the usual `expect` equivalents also available):\n\n```javascript\nreturn promise.should.be.fulfilled;\nreturn promise.should.eventually.deep.equal(\"foo\");\nreturn promise.should.become(\"foo\"); // same as `.eventually.deep.equal`\nreturn promise.should.be.rejected;\nreturn promise.should.be.rejectedWith(Error); // other variants of Chai's `throw` assertion work too.\n```\n\n### `assert` Interface\n\nAs with the `should`/`expect` interface, Chai as Promised provides an `eventually` extender to `chai.assert`, allowing\nany existing Chai assertion to be used on a promise:\n\n```javascript\nassert.equal(2 + 2, 4, \"This had better be true\");\n\n// becomes\nreturn assert.eventually.equal(promiseFor(2 + 2), 4, \"This had better be true, eventually\");\n```\n\nAnd there are, of course, promise-specific extensions:\n\n```javascript\nreturn assert.isFulfilled(promise, \"optional message\");\n\nreturn assert.becomes(promise, \"foo\", \"optional message\");\nreturn assert.doesNotBecome(promise, \"foo\", \"optional message\");\n\nreturn assert.isRejected(promise, \"optional message\");\nreturn assert.isRejected(promise, Error, \"optional message\");\nreturn assert.isRejected(promise, /error message matcher/, \"optional message\");\n```\n\n### Progress Callbacks\n\nChai as Promised does not have any intrinsic support for testing promise progress callbacks. The properties you would\nwant to test are probably much better suited to a library like [Sinon.JS][sinon], perhaps in conjunction with\n[Sinon–Chai][sinon-chai]:\n\n```javascript\nvar progressSpy = sinon.spy();\n\nreturn promise.then(null, null, progressSpy).then(function () {\n    progressSpy.should.have.been.calledWith(\"33%\");\n    progressSpy.should.have.been.calledWith(\"67%\");\n    progressSpy.should.have.been.calledThrice;\n});\n```\n\n### Working with Non-Promise–Friendly Test Runners\n\nAs mentioned, many test runners (\\*cough\\* [Mocha][mocha-makes-me-sad] \\*cough\\* … but see [Mocha as Promised][]!)\ndon't support the nice `return` style shown above. Instead, they take a callback indicating when the asynchronous test\nrun is over. Chai as Promised adapts to this situation with the `notify` method, like so:\n\n```javascript\nit(\"should be fulfilled\", function (done) {\n    promise.should.be.fulfilled.and.notify(done);\n});\n\nit(\"should be rejected\", function (done) {\n    otherPromise.should.be.rejected.and.notify(done);\n});\n```\n\nIn these examples, if the conditions are not met, the test runner will receive an error of the form `\"expected promise\nto be fulfilled but it was rejected with [Error: error message]\"`, or `\"expected promise to be rejected but it was\nfulfilled.\"`\n\nThere's another form of `notify` which is useful in certain situations, like doing assertions after a promise is\ncomplete. For example:\n\n```javascript\nit(\"should change the state\", function (done) {\n    otherState.should.equal(\"before\");\n    promise.should.be.fulfilled.then(function () {\n        otherState.should.equal(\"after\");\n    }).should.notify(done);\n});\n```\n\nNotice how `.notify(done)` is hanging directly off of `.should`, instead of appearing after a promise assertion. This\nindicates to Chai as Promised that it should pass fulfillment or rejection directly through to the testing framework.\nThus, the above code will fail with a Chai as Promised error (`\"expected promise to be fulfilled…\"`) if `promise` is\nrejected, but will fail with a simple Chai error (`expected \"before\" to equal \"after\"`) if `otherState` does not change.\n\nAnother example of where this can be useful is when performing assertions on multiple promises:\n\n```javascript\nit(\"should all be well\", function (done) {\n    Q.all([\n        promiseA.should.become(\"happy\"),\n        promiseB.should.eventually.have.property(\"fun times\"),\n        promiseC.should.be.rejectedWith(TypeError, \"only joyful types are allowed\")\n    ]).should.notify(done);\n});\n```\n\nThis will pass any failures of the individual promise assertions up to the test framework, instead of wrapping them in\nan `\"expected promise to be fulfilled…\"` message as would happen if you did\n`Q.all([…]).should.be.fulfilled.and.notify(done)`.\n\n### Customizing Output Promises\n\nBy default, the promises returned by Chai as Promised's assertions are regular Chai assertion objects, extended with\na single `then` method derived from the input promise. To change this behavior, for instance to output a promise with\nmore useful sugar methods such as are found in most promise libraries, you can override\n`chaiAsPromised.transferPromiseness`. Here's an example that transfer's Q's `finally` and `done` methods:\n\n```js\nchaiAsPromised.transferPromiseness = function (assertion, promise) {\n    assertion.then = promise.then.bind(promise); // this is all you get by default\n    assertion.finally = promise.finally.bind(promise);\n    assertion.done = promise.done.bind(promise);\n};\n```\n\n### Compatibility\n\nChai as Promised is compatible with all promises following the [Promises/A+ specification][spec]. Notably, jQuery's\nso-called “promises” are not up to spec, and Chai as Promised will not work with them. In particular, Chai as Promised\nmakes extensive use of the standard [transformation behavior][] of `then`, which jQuery does not support.\n\n## Installation and Setup\n\n### Node\n\nDo an `npm install chai-as-promised` to get up and running. Then:\n\n```javascript\nvar chai = require(\"chai\");\nvar chaiAsPromised = require(\"chai-as-promised\");\n\nchai.use(chaiAsPromised);\n```\n\nYou can of course put this code in a common test fixture file; for an example using [Mocha][mocha], see\n[the Chai as Promised tests themselves][fixturedemo].\n\n### AMD\n\nChai as Promised supports being used as an [AMD][amd] module, registering itself anonymously (just like Chai). So,\nassuming you have configured your loader to map the Chai and Chai as Promised files to the respective module IDs\n`\"chai\"` and `\"chai-as-promised\"`, you can use them as follows:\n\n```javascript\ndefine(function (require, exports, module) {\n    var chai = require(\"chai\");\n    var chaiAsPromised = require(\"chai-as-promised\");\n\n    chai.use(chaiAsPromised);\n});\n```\n\n### `<script>` tag\n\nIf you include Chai as Promised directly with a `<script>` tag, after the one for Chai itself, then it will\nautomatically plug in to Chai and be ready for use:\n\n```html\n<script src=\"chai.js\"></script>\n<script src=\"chai-as-promised.js\"></script>\n```\n\n\n[presentation]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript\n[chai]: http://chaijs.com/\n[mocha]: http://visionmedia.github.com/mocha/\n[mocha-makes-me-sad]: https://github.com/visionmedia/mocha/pull/329\n[Mocha as Promised]: https://github.com/domenic/mocha-as-promised\n[uncommonjs]: http://kriskowal.github.com/uncommonjs/tests/specification\n[spec]: http://promises-aplus.github.com/promises-spec/\n[transformation behavior]: https://gist.github.com/3889970#that-second-paragraph\n[fixturedemo]: https://github.com/domenic/chai-as-promised/tree/master/test/\n[amd]: https://github.com/amdjs/amdjs-api/wiki/AMD\n[sinon]: http://sinonjs.org/\n[sinon-chai]: https://github.com/domenic/sinon-chai\n",
  "readmeFilename": "README.md",
  "homepage": "https://github.com/domenic/chai-as-promised",
  "_id": "chai-as-promised@4.1.0",
  "_from": "chai-as-promised@~4.1.0"
}