Update promise.js

lib/ext/promise.js

@@ -31,14 +31,22 @@ module.exports = function(should) {
   });
 
   /**
-   * Assert given promise will be fulfilled
+   * Assert given promise will be fulfilled. Result of assertion is still .thenable and should be handled accordingly.
    *
    * @name fulfilled
    * @memberOf Assertion
    * @returns {Promise}
    * @category assertion promises
    * @example
-   * (new Promise(function(resolve, reject) { resolve(10); })).should.be.fulfilled()
+   * 
+   * // don't forget to handle async nature
+   * (new Promise(function(resolve, reject) { resolve(10); })).should.be.fulfilled();
+   * 
+   * // test example with mocha it is possible to return promise
+   * it('is async', () => {
+   *    return new Promise(resolve => resolve(10))
+   *      .should.be.fulfilled();
+   * });
    */
   Assertion.prototype.fulfilled = function Assertion$fulfilled() {
     this.params = {operator: 'to be fulfilled'};
@@ -60,14 +68,23 @@ module.exports = function(should) {
   };
 
   /**
-   * Assert given promise will be rejected
+   * Assert given promise will be rejected. Result of assertion is still .thenable and should be handled accordingly.
    *
    * @name rejected
    * @memberOf Assertion
    * @category assertion promises
    * @returns {Promise}
    * @example
-   * (new Promise(function(resolve, reject) { resolve(10); })).should.not.be.rejected()
+   * 
+   * // don't forget to handle async nature
+   * (new Promise(function(resolve, reject) { resolve(10); }))
+   *    .should.not.be.rejected();
+   * 
+   * // test example with mocha it is possible to return promise
+   * it('is async', () => {
+   *    return new Promise((resolve, reject) => reject(new Error('boom')))
+   *      .should.be.rejected();
+   * });
    */
   Assertion.prototype.rejected = function() {
     this.params = {operator: 'to be rejected'};
@@ -89,14 +106,24 @@ module.exports = function(should) {
   };
 
   /**
-   * Assert given promise will be fulfilled with some expected value.
+   * Assert given promise will be fulfilled with some expected value (value compared using .eql).
+   * Result of assertion is still .thenable and should be handled accordingly.
    *
    * @name fulfilledWith
    * @memberOf Assertion
    * @category assertion promises
    * @returns {Promise}
    * @example
-   * (new Promise(function(resolve, reject) { resolve(10); })).should.be.fulfilledWith(10)
+   * 
+   * // don't forget to handle async nature
+   * (new Promise(function(resolve, reject) { resolve(10); }))
+   *    .should.be.fulfilledWith(10);
+   * 
+   * // test example with mocha it is possible to return promise
+   * it('is async', () => {
+   *    return new Promise((resolve, reject) => resolve(10))
+   *       .should.be.fulfilledWith(10);
+   * });
    */
   Assertion.prototype.fulfilledWith = function(expectedValue) {
     this.params = {operator: 'to be fulfilled'};
@@ -119,7 +146,8 @@ module.exports = function(should) {
   };
 
   /**
-   * Assert given promise will be rejected with some sort of error. Arguments is the same for Assertion#throw
+   * Assert given promise will be rejected with some sort of error. Arguments is the same for Assertion#throw.
+   * Result of assertion is still .thenable and should be handled accordingly.
    *
    * @name rejectedWith
    * @memberOf Assertion
@@ -128,15 +156,20 @@ module.exports = function(should) {
    * @example
    *
    * function failedPromise() {
-  *   return new Promise(function(resolve, reject) {
-  *     reject(new Error('boom'))
-  *   })
-  * }
-   * failedPromise().should.be.rejectedWith(Error)
-   * failedPromise().should.be.rejectedWith('boom')
-   * failedPromise().should.be.rejectedWith(/boom/)
-   * failedPromise().should.be.rejectedWith(Error, { message: 'boom' })
-   * failedPromise().should.be.rejectedWith({ message: 'boom' })
+   *   return new Promise(function(resolve, reject) {
+   *     reject(new Error('boom'))
+   *   })
+   * }
+   * failedPromise().should.be.rejectedWith(Error);
+   * failedPromise().should.be.rejectedWith('boom');
+   * failedPromise().should.be.rejectedWith(/boom/);
+   * failedPromise().should.be.rejectedWith(Error, { message: 'boom' });
+   * failedPromise().should.be.rejectedWith({ message: 'boom' });
+   * 
+   * // test example with mocha it is possible to return promise
+   * it('is async', () => {
+   *    return failedPromise().should.be.rejectedWith({ message: 'boom' });
+   * });
    */
   Assertion.prototype.rejectedWith = function(message, properties) {
     this.params = {operator: 'to be rejected'};
@@ -204,7 +237,9 @@ module.exports = function(should) {
   };
 
   /**
-   * Assert given object is promise and wrap it in PromisedAssertion, which has all properties of Assertion. That means you can chain as with usual Assertion.
+   * Assert given object is promise and wrap it in PromisedAssertion, which has all properties of Assertion. 
+   * That means you can chain as with usual Assertion.
+   * Result of assertion is still .thenable and should be handled accordingly.
    *
    * @name finally
    * @memberOf Assertion
@@ -213,7 +248,14 @@ module.exports = function(should) {
    * @returns {PromisedAssertion} Like Assertion, but .then this.obj in Assertion
    * @example
    *
-   * (new Promise(function(resolve, reject) { resolve(10); })).should.be.eventually.equal(10)
+   * (new Promise(function(resolve, reject) { resolve(10); }))
+   *    .should.be.eventually.equal(10);
+   * 
+   * // test example with mocha it is possible to return promise
+   * it('is async', () => {
+   *    return new Promise(resolve => resolve(10))
+   *      .should.be.finally.equal(10);
+   * });
    */
   Object.defineProperty(Assertion.prototype, 'finally', {
     get: function() {