Assert: Add assert.rejects.

docs/assert/rejects.md

@@ -0,0 +1,83 @@
+---
+layout: default
+title: rejects
+description: Test if the provided promise rejects, and optionally compare the rejection value.
+categories:
+  - assert
+---
+
+## `rejects( promise, expectedMatcher [, message ] )`
+
+Test if the provided promise rejects, and optionally compare the rejection value.
+
+| name               | description                          |
+|--------------------|--------------------------------------|
+| `promise` (thenable) | promise to test for rejection      |
+| `expectedMatcher`  | Rejection value matcher              |
+| `message` (string) | A short description of the assertion |
+
+
+### Description
+
+When testing code that is expected to return a rejected promise based on a
+specific set of circumstances, use `assert.rejects()` for testing and
+comparison.
+
+The `expectedMatcher` argument can be:
+
+* A function that returns `true` when the assertion should be considered passing.
+* A base constructor to use ala `rejectionValue instanceof expectedMatcher`
+* A RegExp that matches (or partially matches) `rejectionValue.toString()`
+
+Note: in order to avoid confusion between the `message` and the `expectedMatcher`, the `expectedMatcher` **can not** be a string.
+
+### Example
+
+Assert the correct error message is received for a custom error object.
+
+```js
+QUnit.test( "rejects", function( assert ) {
+
+  assert.rejects(Promise.reject("some error description"));
+
+  assert.rejects(
+    Promise.reject(new Error("some error description")),
+    "rejects with just a message, not using the 'expectedMatcher' argument"
+  );
+
+  assert.rejects(
+    Promise.reject(new Error("some error description")),
+    /description/,
+    "`rejectionValue.toString()` contains `description`"
+  );
+
+  // Using a custom error like object
+  function CustomError( message ) {
+    this.message = message;
+  }
+
+  CustomError.prototype.toString = function() {
+    return this.message;
+  };
+
+  assert.rejects(
+    Promise.reject(new CustomError()),
+    CustomError,
+    "raised error is an instance of CustomError"
+  );
+
+  assert.rejects(
+    Promise.reject(new CustomError("some error description")),
+    new CustomError("some error description"),
+    "raised error instance matches the CustomError instance"
+  );
+
+  assert.rejects(
+    Promise.reject(throw new CustomError("some error description")),
+    function( err ) {
+      return err.toString() === "some error description";
+    },
+    "raised error instance satisfies the callback function"
+  );
+});
+```

src/assert.js

@@ -305,6 +305,113 @@ class Assert {
 			message
 		} );
 	}
+
+	rejects( promise, expected, message ) {
+		let result = false;
+
+		const currentTest = ( this instanceof Assert && this.test ) || config.current;
+
+		// 'expected' is optional unless doing string comparison
+		if ( objectType( expected ) === "string" ) {
+			if ( message === undefined ) {
+				message = expected;
+				expected = undefined;
+			} else {
+				message = "assert.rejects does not accept a string value for the expected " +
+					"argument.\nUse a non-string object value (e.g. validator function) instead " +
+					"if necessary.";
+
+				currentTest.assert.pushResult( {
+					result: false,
+					message: message
+				} );
+
+				return;
+			}
+		}
+
+		const then = promise && promise.then;
+		if ( objectType( then ) !== "function" ) {
+			const message = "The value provided to `assert.rejects` in " +
+				"\"" + currentTest.testName + "\" was not a promise.";
+
+			currentTest.assert.pushResult( {
+				result: false,
+				message: message,
+				actual: promise
+			} );
+
+			return;
+		}
+
+		const done = this.async();
+
+		return then.call(
+			promise,
+			function handleFulfillment() {
+				const message = "The promise returned by the `assert.rejects` callback in " +
+				"\"" + currentTest.testName + "\" did not reject.";
+
+				currentTest.assert.pushResult( {
+					result: false,
+					message: message,
+					actual: promise
+				} );
+
+				done();
+			},
+
+			function handleRejection( actual ) {
+				if ( actual ) {
+					const expectedType = objectType( expected );
+
+					// We don't want to validate
+					if ( expected === undefined ) {
+						result = true;
+						expected = null;
+
+						// Expected is a regexp
+					} else if ( expectedType === "regexp" ) {
+						result = expected.test( errorString( actual ) );
+
+						// Expected is a constructor, maybe an Error constructor
+					} else if ( expectedType === "function" && actual instanceof expected ) {
+						result = true;
+
+						// Expected is an Error object
+					} else if ( expectedType === "object" ) {
+						result = actual instanceof expected.constructor &&
+							actual.name === expected.name &&
+							actual.message === expected.message;
+
+						// Expected is a validation function which returns true if validation passed
+					} else {
+						if ( expectedType === "function" ) {
+							result = expected.call( {}, actual ) === true;
+							expected = null;
+
+							// Expected is some other invalid type
+						} else {
+							result = false;
+							message = "invalid expected value provided to `assert.rejects` " +
+								"callback in \"" + currentTest.testName + "\": " +
+								expectedType + ".";
+						}
+					}
+				}
+
+
+				currentTest.assert.pushResult( {
+					result,
+					actual,
+					expected,
+					message
+				} );
+
+				done();
+			}
+		);
+	}
 }
 
 // Provide an alternative to assert.throws(), for environments that consider throws a reserved word