Fulfill or betray promises

.travis.yml

@@ -9,6 +9,7 @@ node_js:
   - "5"
   - "6"
   - "7"
+  - "8"
 
 notifications:
   email: ["[email protected]"]

must.d.ts

@@ -8,6 +8,8 @@ interface Must {
     be: CallableMust;
     before(expected): Must;
     below(expected): Must;
+    betray<TResult>(catchCondition?: (reason: any) => TResult | PromiseLike<TResult>): Promise<TResult>;
+    betray(catchCondition?: (reason: any) => void): Promise<any>;
     between(begin, end): Must;
     boolean(): Must;
     contain(expected): Must;
@@ -24,6 +26,8 @@ interface Must {
     false(): Must;
     falsy(): Must;
     frozen(): Must;
+    fulfill<TResult>(fulfilledCondition?: (value?: any) => TResult | PromiseLike<TResult>): Promise<TResult>;
+    fulfill(fulfilledCondition?: (value?: any) => void): Promise<any>;
     function(): Must;
     gt(expected: number): Must;
     gte(expected: number): Must;
@@ -52,6 +56,7 @@ interface Must {
     ownProperties(properties: any): Must;
     ownProperty(property: string, value?): Must;
     permutationOf(expected: Array<any>): Must;
+    promise(): Must;
     properties(properties: any): Must;
     property(property: string, value?): Must;
     regexp(): Must;
@@ -93,4 +98,41 @@ declare global {
     interface Array<T> {
         must: Must;
     }
+
+    // copied from https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/es6-shim/index.d.ts
+    interface PromiseLike<T> {
+        /**
+         * Attaches callbacks for the resolution and/or rejection of the Promise.
+         * @param onfulfilled The callback to execute when the Promise is resolved.
+         * @param onrejected The callback to execute when the Promise is rejected.
+         * @returns A Promise for the completion of which ever callback is executed.
+         */
+        then<TResult>(onfulfilled?: (value: T) => TResult | PromiseLike<TResult>, onrejected?: (reason: any) => TResult | PromiseLike<TResult>): PromiseLike<TResult>;
+
+        then<TResult>(onfulfilled?: (value: T) => TResult | PromiseLike<TResult>, onrejected?: (reason: any) => void): PromiseLike<TResult>;
+    }
+
+    /**
+     * Represents the completion of an asynchronous operation
+     */
+    interface Promise<T> {
+        /**
+         * Attaches callbacks for the resolution and/or rejection of the Promise.
+         * @param onfulfilled The callback to execute when the Promise is resolved.
+         * @param onrejected The callback to execute when the Promise is rejected.
+         * @returns A Promise for the completion of which ever callback is executed.
+         */
+        then<TResult>(onfulfilled?: (value: T) => TResult | PromiseLike<TResult>, onrejected?: (reason: any) => TResult | PromiseLike<TResult>): Promise<TResult>;
+
+        then<TResult>(onfulfilled?: (value: T) => TResult | PromiseLike<TResult>, onrejected?: (reason: any) => void): Promise<TResult>;
+
+        /**
+         * Attaches a callback for only the rejection of the Promise.
+         * @param onrejected The callback to execute when the Promise is rejected.
+         * @returns A Promise for the completion of the callback.
+         */
+        catch(onrejected?: (reason: any) => T | PromiseLike<T>): Promise<T>;
+
+        catch(onrejected?: (reason: any) => void): Promise<T>;
+    }
 }

must.js

@@ -1183,6 +1183,149 @@ defineGetter(Must.prototype, "reject", function() {
   return Rejectable(this)
 })
 
+/**
+ * Assert that an object is a promise, and returns it.
+ *
+ * The determination uses duck typing, i.e., it checks whether the object has
+ * a `then` and a `catch` method.
+ *
+ * There are several implementations of promises in the wild, and a promise you
+ * receive from a library might not be an `instanceof` _your_ `Promise` type,
+ * although they can work together.
+ *
+ * ```javascript
+ * promise.must.be.a(Promise)
+ * ```
+ *
+ * might fail, while
+ *
+ * ```javascript
+ * promise.must.be.a.promise
+ * ```
+ *
+ * might be upheld.
+ *
+ * @example
+ * Promise.resolve(42).must.be.a.promise()
+ * Promise.reject(42).must.be.a.promise()
+ *
+ * @method promise
+ */
+Must.prototype.promise = function() {
+  this.assert(isPromise(this.actual), isPromiseMsg, { actual: this.actual })
+  return this.actual
+}
+
+/**
+ * Assert that an object is a promise (see `promise`), that eventually resolves.
+ * The assertion returns a promise that settles to the outcome (resolve result or
+ * reject error) of `fulfilledCondition`. `fulfilledCondition` is called with the
+ * resolution (resolve result) of the original promise when it resolves.
+ * If the original promise is rejected, this assertion fails, and `fulfilledCondition`
+ * is not called. `fulfilledCondition` is optional.
+ *
+ * This approach makes it possible to immediate express assertions about the original
+ * promise's resolve result.
+ *
+ * You should not use `not` to negate `fulfill`. Things will get weird. Use `betray`
+ * to express that the promise should be rejected instead.
+ *
+ * @example
+ * Promise.resolve(42).must.fulfill()
+ * Promise.resolve(42).must.fulfill(function(result) {
+ *   result.must.be.a.number()
+ *   result.must.be.truthy()
+ *   return result // the resulting promise will be fulfilled
+ * })
+ * Promise.resolve(42).must.fulfill(function(result) {
+ *   result.must.be.a.number()
+ *   result.must.be.truthy()
+ *   throw result // the resulting promise will be rejected
+ * })
+ * Promise.resolve(42).must.fulfill(function(result) {
+ *   result.must.not.be.a.number() // fails
+ *   result.must.be.truthy()
+ *   return result
+ * })
+ * Promise.reject(new Error()).must.fulfill(function(result) { // fulfill fails, callback is not executed
+ *   result.must.not.be.a.number()
+ *   result.must.be.truthy()
+ *   return result
+ * })
+ *
+ * @method fulfill
+ * @param fulfilledCondition
+ */
+Must.prototype.fulfill = function(fulfilledCondition) {
+  var must = this
+  must.assert(isPromise(this.actual), isPromiseMsg, {actual: this.actual})
+  var caught = must.actual.catch(function(err) {
+    must.assert(
+      false,
+      "resolve, but got rejected with \'" + (err && err.message ? err.message : err) + "\'",
+      {actual: must.actual}
+    )
+  })
+  return fulfilledCondition ? caught.then(fulfilledCondition) : caught
+}
+
+/**
+ * Assert that an object is a promise (see `promise`), that eventually rejects ("betrays" the promise).
+ * The assertion returns a promise that settles to the outcome (resolve result or
+ * reject error) of `catchCondition`. `catchCondition` is called with the
+ * error (reject result) of the original promise when it rejects.
+ * If the original promise is fulfilled (resolved), this assertion fails, and `catchCondition`
+ * is not called. `catchCondition` is optional.
+ *
+ * This approach makes it possible to immediate express assertions about the original
+ * promise's reject error.
+ *
+ * You should not use `not` to negate `betray`. Things will get weird. Use `fulfill`
+ * to express that the promise should be resolved instead.
+ *
+ * @example
+ * Promise.reject(new Error()).must.betray()
+ * Promise.reject(42).must.betray(function(err) {
+ *   err.must.be.a.number()
+ *   err.must.be.truthy()
+ *   return result // the resulting promise will be fulfilled
+ * })
+ * Promise.reject(42).must.betray(function(err) {
+ *   err.must.be.a.number()
+ *   err.must.be.truthy()
+ *   throw result // the resulting promise will be rejected
+ * })
+ * Promise.reject(42).must.betray(function(err) {
+ *   err.must.not.be.a.number() // fails
+ *   err.must.be.truthy()
+ *   return result
+ * })
+ * Promise.resolve(42).must.betray(function(err) { // betray fails, callback is not executed
+ *   err.must.not.be.a.number()
+ *   err.must.be.truthy()
+ *   return result
+ * })
+ *
+ * @method betray
+ * @param catchCondition
+ */
+Must.prototype.betray = function(catchCondition) {
+  var must = this
+  must.assert(isPromise(this.actual), isPromiseMsg, {actual: this.actual})
+  return must.actual.then(
+    function(result) {
+      must.assert(
+        false,
+        "reject, but got fulfilled with \'" + stringify(result) + "\'",
+        {actual: must.actual}
+      )
+    },
+    catchCondition
+      ? catchCondition
+      : function(err) { throw err }
+  )
+}
+
 /**
  * Assert a string starts with the given string.
  *
@@ -1285,4 +1428,10 @@ function messageFromError(err) {
 
 function isFn(fn) { return typeof fn === "function" }
 function isNumber(n) { return typeof n === "number" || n instanceof Number }
+
+var isPromiseMsg = "be a promise (i.e., have a \'then\' and a \'catch\' function)"
+function isPromise(p) {
+  return p && typeof p.then === "function" && typeof p.catch === "function"
+}
+
 function passthrough() { return this }

test/must/_failing_promise_tests.js

@@ -0,0 +1,66 @@
+var Must = require("../..")
+var assert = require("./assert")
+var assertionErrorTest = require("./_assertion_error_test")
+
+function dummy () {}
+
+var thenNoCatch = {then: dummy}
+var catchNoThen = {catch: dummy}
+var catchAndThen = {then: dummy, catch: dummy}
+
+module.exports = function(callToTest) {
+  it("must fail given null", function () {
+    assert.fail(function () { callToTest(Must(null)) })
+  })
+
+  it("must fail given undefined", function () {
+    assert.fail(function () { callToTest(Must(undefined)) })
+  })
+
+  it("must fail given boolean primitive", function () {
+    assert.fail(function () { callToTest(Must(true)) })
+    assert.fail(function () { callToTest(Must(false)) })
+  })
+
+  it("must fail given number primitive", function () {
+    assert.fail(function () { callToTest(Must(42)) })
+  })
+
+  it("must fail given string primitive", function () {
+    assert.fail(function () { callToTest(Must("")) })
+  })
+
+  it("must fail given array", function () {
+    assert.fail(function () { callToTest(Must([])) })
+  })
+
+  it("must fail given object", function () {
+    assert.fail(function () { callToTest(Must({})) })
+  })
+
+  it("must fail given an object with a then function, but not a catch function", function () {
+    assert.fail(function () { callToTest(Must(thenNoCatch)) })
+  })
+
+  it("must fail given an object with a catch function, but not a then function", function () {
+    assert.fail(function () { callToTest(Must(catchNoThen)) })
+  })
+
+  assertionErrorTest(
+    function() { callToTest(Must(catchNoThen)) },
+    {
+      actual: catchNoThen,
+      message: "{} must be a promise (i.e., have a \'then\' and a \'catch\' function)"
+    }
+  )
+
+  describe(".not", function() {
+    it("must invert the assertion", function() {
+      assert.fail(function() { callToTest(Must(catchAndThen).not) })
+    })
+  })
+}
+
+module.exports.thenNoCatch = thenNoCatch
+module.exports.catchNoThen = catchNoThen
+module.exports.catchAndThen = catchAndThen