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


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.


Assert the correct error message is received for a custom error object.

QUnit.test( "rejects", function( assert ) {

  assert.rejects(Promise.reject("some error description"));

    Promise.reject(new Error("some error description")),
    "rejects with just a message, not using the 'expectedMatcher' argument"

    Promise.reject(new Error("some error description")),
    "`rejectionValue.toString()` contains `description`"

  // Using a custom error like object
  function CustomError( message ) {
    this.message = message;

  CustomError.prototype.toString = function() {
    return this.message;

    Promise.reject(new CustomError()),
    "raised error is an instance of CustomError"

    Promise.reject(new CustomError("some error description")),
    new CustomError("some error description"),
    "raised error instance matches the CustomError instance"

    Promise.reject(throw new CustomError("some error description")),
    function( err ) {
      return err.toString() === "some error description";
    "raised error instance satisfies the callback function"