{
  "name": "mocha-as-promised",
  "description": "Adds “thenable” promise support to the Mocha test runner.",
  "keywords": [
    "promises",
    "promises-aplus",
    "mocha",
    "testing"
  ],
  "version": "2.0.0",
  "author": {
    "name": "Domenic Denicola",
    "email": "domenic@domenicdenicola.com",
    "url": "http://domenicdenicola.com"
  },
  "license": "WTFPL",
  "repository": {
    "type": "git",
    "url": "https://github.com/domenic/mocha-as-promised"
  },
  "bugs": {
    "url": "http://github.com/domenic/mocha-as-promised/issues"
  },
  "main": "mocha-as-promised.js",
  "scripts": {
    "test": "mocha",
    "test-browser": "opener ./test/index.html",
    "lint": "jshint mocha-as-promised.js"
  },
  "peerDependencies": {
    "mocha": ">= 1.8.0 <2"
  },
  "devDependencies": {
    "coffee-script": "~1.6.3",
    "chai": "~1.8.1",
    "chai-as-promised": "~4.1.0",
    "jshint": "~2.3.0",
    "mocha": "~1.13.0",
    "opener": "~1.3.0",
    "q": "~0.9.7"
  },
  "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\" alt=\"Promises/A+ logo\" />\n</a>\n\n# Promise-Returning Tests for Mocha\n\nSo you really like [Mocha][]. But you also really like [promises][]. And you'd like to see\n[support in Mocha][mocha-issue] for the promise-returning test style found in [Buster][] and others, i.e. stuff like\n\n```js\nit(\"should be fulfilled with 5\", function () {\n    return promise.then(function (result) {\n        return result.should.equal(5);\n    });\n});\n```\n\nOr even better, if you are using [Chai as Promised][],\n\n```js\nit(\"should be fulfilled with 5\", function () {\n    return promise.should.become(5);\n});\n```\n\nUntil now you've been making do with [hacks][], or perhaps using [my fork of Mocha][mocha-fork], and hoping I rebase\noften enough to keep things nice. But now, with Mocha as Promised, you have a much nicer option available!\n\n## How to Use\n\nOnce you install and set up Mocha as Promised, you now have a second way of creating asynchronous tests, besides Mocha's\nusual `done`-callback style. Just return a promise: if it is fulfilled, the test passes, and if it is rejected, the test\nfails, with the rejection reason as the error. Nice, huh?\n\nIf you want to do multiple assertions in a single test, first, think carefully about whether you should instead break\nthat test up into multiple tests. Once you've decided that yes, you're really OK with multiple assertions, then you'll\nwant to use a promise-aggregator function, like [Q][]'s [`Q.all`][Q.all]:\n\n```js\nit(\"should be fulfilled with an object with the correct properties\", function () {\n    var userPromise = getUserAsynchronously();\n\n    return Q.all([\n        userPromise.should.eventually.be.an(\"object\"),\n        userPromise.should.eventually.have.property(\"id\", 123),\n        userPromise.should.eventually.have.property(\"firstName\", \"Domenic\"),\n        userPromise.should.eventually.have.property(\"lastName\", \"Denicola\")\n    ]);\n});\n```\n\n(Once again I'll plug my [Chai as Promised][] library, so you can do super-awesome “eventual” assertions like these.)\n\nMoch as Promised works with all Mocha interfaces: BDD, TDD, QUnit, whatever. It hooks in at such a low level, the\ninterfaces don't even get involved.\n\n## Installation and Usage\n\n### Node\n\nDo an `npm install mocha-as-promised --save-dev` to get up and running. Then:\n\n```javascript\nrequire(\"mocha-as-promised\")();\n```\n\nYou can of course put this code in a common test fixture file; for an example, see\n[the Mocha as Promised tests themselves][fixturedemo].\n\n### AMD\n\nMocha as Promised supports being used as an [AMD][amd] module, registering itself anonymously. So, assuming you have\nconfigured your loader to map the Mocha and Mocha as Promised files to the respective module IDs `\"mocha\"` and\n`\"mocha-as-promised\"`, you can use them as follows:\n\n```javascript\ndefine(function (require, exports, module) {\n    var mocha = require(\"mocha\");\n    var mochaAsPromised = require(\"mocha-as-promised\");\n\n    mochaAsPromised(mocha);\n});\n```\n\n### `<script>` tag\n\nIf you include Mocha as Promised directly with a `<script>` tag, after the one for Mocha itself, then it will\nautomatically plug in to Mocha and be ready for use:\n\n```html\n<script src=\"mocha.js\"></script>\n<script src=\"mocha-as-promised.js\"></script>\n```\n\n### Node, the Advanced Version\n\nThe `require(\"mocha-as-promised\")()` above tries to detect which instance of Mocha is being used automatically. This\nway, Mocha as Promised can plug into either the local Mocha instance installed into your project, or into the global\nMocha instance if you're running your tests using the globally-installed command-line runner.\n\nIn some cases, if you're doing something weird, this can fall down. In these cases, you can pass an array of Mocha\ninstances into the Mocha as Promised function. For example, if you somehow had your Mocha module as a property of the\n`foo` module, instead of it being found in the usual npm directory structures, you would do\n\n```javascript\nrequire(\"mocha-as-promised\")([require(\"foo\").MyMocha]);\n```\n\n## How Does This Work!?\n\n**Black magic**. No, seriously, this is a big hack.\n\nThe essential strategy is to intercept any test functions that Mocha runs, and inspect their return values. If they\nreturn a promise, then translate fulfillment/rejection appropriately. It's explained in more detail how exactly this is\ndone in a large comment block at the top of the source. You can also check out [`d98f2d9`][] for an alternative\napproach at the interception, which was abandoned in favor of the current one.\n\nNote that Mocha as Promised *doesn't* just override `Runnable.prototype.run`, as is done by [my Mocha fork][mocha-fork].\nThat seemed a bit too fragile to be a long-term solution. The interception approach involves more black magic, but\nis probably more resilient in the face of upstream changes. At least, that's the hope.\n\n\n[Mocha]: http://visionmedia.github.com/mocha/\n[promises]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript\n[Buster]: http://busterjs.org/\n[mocha-issue]: https://github.com/visionmedia/mocha/pull/329\n[Chai as Promised]: https://github.com/domenic/chai-as-promised/\n[hacks]: https://github.com/domenic/chai-as-promised/#working-with-non-promise%E2%80%93friendly-test-runners\n[mocha-fork]: https://github.com/domenic/mocha/tree/promises\n[Q]: https://github.com/kriskowal/q\n[Q.all]: https://github.com/kriskowal/q#combination\n[fixturedemo]: https://github.com/domenic/mocha-as-promised/tree/master/test/\n[grunt-mocha-test]: https://npmjs.org/package/grunt-mocha-test\n[amd]: https://github.com/amdjs/amdjs-api/wiki/AMD\n[`d98f2d9`]: https://github.com/domenic/mocha-as-promised/commit/d98f2d95197896cd7b948b6208cb6c1235f43eed\n",
  "readmeFilename": "README.md",
  "homepage": "https://github.com/domenic/mocha-as-promised",
  "_id": "mocha-as-promised@2.0.0",
  "_from": "mocha-as-promised@~2.0.0"
}