chai-as-promised 4.3.0 → 5.3.0

package/README.md

@@ -27,19 +27,19 @@ you can write code that expresses what you really mean:
 return doSomethingAsync().should.eventually.equal("foo");
 ```
 
-or if you have a testing framework that doesn't allow returning promises to signal asynchronous test completion, then
-you can use the following workaround:
+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.
+
 ## 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);
@@ -66,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");
@@ -91,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();
@@ -107,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) {
@@ -122,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) {
@@ -134,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.
@@ -153,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 promises were not up to spec before jQuery 3.0, 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<3.0 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) {
@@ -175,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) {
@@ -191,26 +173,23 @@ 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
 
-Another example of where this can be useful is when performing assertions on multiple promises:
+To perform assertions on multiple promises, use `Promise.all` to combine multiple Chai as Promised assertions:
 
 ```javascript
-it("should all be well", function (done) {
-    Q.all([
+it("should all be well", function () {
+    return Promise.all([
         promiseA.should.become("happy"),
         promiseB.should.eventually.have.property("fun times"),
         promiseC.should.be.rejectedWith(TypeError, "only joyful types are allowed")
-    ]).should.notify(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
-`Q.all([…]).should.be.fulfilled.and.notify(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.
 
 ## Installation and Setup
 
@@ -225,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) {
@@ -245,27 +221,32 @@ 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>
 <script src="chai-as-promised.js"></script>
 ```
 
+### Karma
+
+If you're using [Karma][], check out the accompanying [karma-chai-as-promised][] plugin.
+
 ### Browser Compatibility
 
 Chai as Promised is only compatible with modern browsers (IE ≥9, Safari ≥6, no PhantomJS).
 
 [presentation]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript
 [chai]: http://chaijs.com/
-[Mocha-promises]: http://visionmedia.github.io/mocha/#asynchronous-code
+[Mocha-promises]: http://mochajs.org/#asynchronous-code
 [Buster-promises]: http://docs.busterjs.org/en/latest/modules/buster-test/spec/#returning-a-promise
 [blue-tape]: https://github.com/spion/blue-tape
 [spec]: http://promisesaplus.com/
 [transformation behavior]: http://domenic.me/2012/10/14/youre-missing-the-point-of-promises/#toc_2
-[Mocha]: http://visionmedia.github.com/mocha/
+[Mocha]: http://mochajs.org
 [fixturedemo]: https://github.com/domenic/chai-as-promised/tree/master/test/
 [amd]: https://github.com/amdjs/amdjs-api/wiki/AMD
 [sinon]: http://sinonjs.org/
 [sinon-chai]: https://github.com/domenic/sinon-chai
+[Karma]: https://karma-runner.github.io/
+[karma-chai-as-promised]: https://github.com/vlkosinov/karma-chai-as-promised

package/lib/chai-as-promised.js

@@ -34,8 +34,11 @@
         var Assertion = chai.Assertion;
         var assert = chai.assert;
 
-        function isJQueryPromise(thenable) {
-            return typeof thenable.always === "function" &&
+        function isLegacyJQueryPromise(thenable) {
+            // jQuery promises are Promises/A+-compatible since 3.0.0. jQuery 3.0.0 is also the first version
+            // to define the catch method.
+            return typeof thenable.catch !== "function" &&
+                   typeof thenable.always === "function" &&
                    typeof thenable.done === "function" &&
                    typeof thenable.fail === "function" &&
                    typeof thenable.pipe === "function" &&
@@ -47,9 +50,10 @@
             if (typeof assertion._obj.then !== "function") {
                 throw new TypeError(utils.inspect(assertion._obj) + " is not a thenable.");
             }
-            if (isJQueryPromise(assertion._obj)) {
-                throw new TypeError("Chai as Promised is incompatible with jQuery's thenables, sorry! Please use a " +
-                                    "Promises/A+ compatible library (see http://promisesaplus.com/).");
+            if (isLegacyJQueryPromise(assertion._obj)) {
+                throw new TypeError("Chai as Promised is incompatible with thenables of jQuery<3.0.0, sorry! Please " +
+                                    "upgrade jQuery or use another Promises/A+ compatible library (see " +
+                                    "http://promisesaplus.com/).");
             }
         }
 
@@ -233,8 +237,8 @@
             doNotify(getBasePromise(this), done);
         });
 
-        method("become", function (value) {
-            return this.eventually.deep.equal(value);
+        method("become", function (value, message) {
+            return this.eventually.deep.equal(value, message);
         });
 
         ////////
@@ -258,28 +262,22 @@
         });
 
         getterNames.forEach(function (getterName) {
-            var propertyDesc = propertyDescs[getterName];
-
             // Chainable methods are things like `an`, which can work both for `.should.be.an.instanceOf` and as
             // `should.be.an("object")`. We need to handle those specially.
-            var isChainableMethod = false;
-            try {
-                isChainableMethod = typeof propertyDesc.get.call({}) === "function";
-            } catch (e) { }
+            var isChainableMethod = Assertion.prototype.__methods.hasOwnProperty(getterName);
 
             if (isChainableMethod) {
-                Assertion.addChainableMethod(
+                Assertion.overwriteChainableMethod(
                     getterName,
-                    function () {
-                        var assertion = this;
-                        function originalMethod() {
-                            return propertyDesc.get.call(assertion).apply(assertion, arguments);
-                        }
-                        doAsserterAsyncAndAddThen(originalMethod, this, arguments);
+                    function (originalMethod) {
+                        return function() {
+                            doAsserterAsyncAndAddThen(originalMethod, this, arguments);
+                        };
                     },
-                    function () {
-                        var originalGetter = propertyDesc.get;
-                        doAsserterAsyncAndAddThen(originalGetter, this);
+                    function (originalGetter) {
+                        return function() {
+                            doAsserterAsyncAndAddThen(originalGetter, this);
+                        };
                     }
                 );
             } else {

package/package.json

@@ -1,41 +1,47 @@
 {
-    "name": "chai-as-promised",
-    "description": "Extends Chai with assertions about promises.",
-    "keywords": [
-        "chai",
-        "testing",
-        "assertions",
-        "promises",
-        "promises-aplus"
-    ],
-    "version": "4.3.0",
-    "author": "Domenic Denicola <d@domenic.me> (https://domenic.me)",
-    "license": "WTFPL",
-    "repository": "domenic/chai-as-promised",
-    "main": "./lib/chai-as-promised.js",
-    "files": [
-        "lib"
-    ],
-    "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": "istanbul cover node_modules/mocha/bin/_mocha && opener ./coverage/lcov-report/lib/chai-as-promised.js.html"
-    },
-    "peerDependencies": {
-        "chai": ">= 1.7.0 < 3"
-    },
-    "devDependencies": {
-        "chai": "^2.0.0",
-        "coffee-script": "1.9.0",
-        "istanbul": "0.3.5",
-        "ecstatic": "0.5.8",
-        "glob": "^4.3.5",
-        "jshint": "^2.6.0",
-        "mocha": "^1.21.5",
-        "opener": "^1.4.0",
-        "q": "^1.1.2",
-        "underscore": "1.7.0"
-    }
+  "name": "chai-as-promised",
+  "description": "Extends Chai with assertions about promises.",
+  "keywords": [
+    "chai",
+    "chai-plugin",
+    "browser",
+    "async",
+    "testing",
+    "assertions",
+    "promises",
+    "promises-aplus"
+  ],
+  "version": "5.3.0",
+  "author": "Domenic Denicola <d@domenic.me> (https://domenic.me)",
+  "license": "WTFPL",
+  "repository": "domenic/chai-as-promised",
+  "main": "./lib/chai-as-promised.js",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "test": "npm run test-plugin && npm run test-intercompatibility",
+    "test-plugin": "mocha",
+    "test-intercompatibility": "mocha test-intercompatibility --opts test-intercompatibility/mocha.opts",
+    "test-browser-jquery": "coffee ./test/browser/runner.coffee jquery",
+    "test-browser-q": "coffee ./test/browser/runner.coffee q",
+    "test-browser-when": "coffee ./test/browser/runner.coffee when",
+    "lint": "jshint ./lib",
+    "cover": "istanbul cover node_modules/mocha/bin/_mocha && opener ./coverage/lcov-report/lib/chai-as-promised.js.html"
+  },
+  "peerDependencies": {
+    "chai": ">= 2.1.2 < 4"
+  },
+  "devDependencies": {
+    "chai": "^3.0.0",
+    "coffee-script": "1.10.0",
+    "istanbul": "0.4.1",
+    "ecstatic": "^1.3.1",
+    "glob": "^6.0.1",
+    "jshint": "^2.8.0",
+    "mocha": "^2.3.4",
+    "opener": "^1.4.1",
+    "q": "^1.4.1",
+    "underscore": "1.8.3"
+  }
 }