Docs: Add assert.rejects API documentation.

docs/assert/rejects.md

@@ -0,0 +1,77 @@
+---
+layout: default
+title: rejects
+description: Test if the provided promise rejects, and optionally compare the rejection value.
+categories:
+  - assert
+---
+
+## `rejects( promise, expected [, message ] )`
+
+Test if the provided promise rejects, and optionally compare the rejection value.
+
+| name               | description                          |
+|--------------------|--------------------------------------|
+| `promise` (thenable) | promise to test for rejection      |
+| `expected`         | Expected rejection value (generally an error) |
+| `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 `expected` argument can be an Error Object (instance), an Error Function
+(constructor), a RegExp that matches (or partially matches) the String
+representation, or a callback Function that must return `true` to pass the
+assertion check.
+
+### Example
+
+Assert the correct error message is received for a custom error object.
+
+```js
+QUnit.test( "rejects", function( assert ) {
+
+  function CustomError( message ) {
+    this.message = message;
+  }
+
+  CustomError.prototype.toString = function() {
+    return this.message;
+  };
+
+  assert.rejects(
+    Promise.reject("error"),
+    "rejects with just a message, not using the 'expected' argument"
+  );
+
+  assert.rejects(
+    Promise.reject(new CustomError("some error description")),
+    /description/,
+    "raised error message contains 'description'"
+  );
+
+  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"
+  );
+});
+```