diff --git a/types/qunit/index.d.ts b/types/qunit/index.d.ts index 120c61d667..2b8851848c 100644 --- a/types/qunit/index.d.ts +++ b/types/qunit/index.d.ts @@ -236,6 +236,34 @@ interface Assert { throws(block: () => void, expected?: any, message?: any): void; raises(block: () => void, expected?: any, message?: any): void; + /** + * Test if the provided promise rejects, and optionally compare the + * rejection value. + * + * 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. + * An Error object + * 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. + * + * @param promise promise to test for rejection + * @param expectedMatcher Rejection value matcher + * @param message A short description of the assertion + */ + rejects(promise: Promise, message?: string): void; + rejects( + promise: Promise, + expectedMatcher?: any, + message?: string, + ): void; + /** * A marker for progress in a given test. * diff --git a/types/qunit/qunit-tests.ts b/types/qunit/qunit-tests.ts index ae519cd0bc..b90346a325 100644 --- a/types/qunit/qunit-tests.ts +++ b/types/qunit/qunit-tests.ts @@ -562,6 +562,53 @@ QUnit.test( "throws", function( assert ) { ); }); +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 + class CustomError { + message?: string; + constructor(message?: string) { + this.message = message; + } + toString() { + 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(new CustomError("some error description")), + function( err ) { + return err.toString() === "some error description"; + }, + "raised error instance satisfies the callback function" + ); +}); + QUnit.module( "module", { beforeEach: function( assert ) { assert.ok( true, "one extra assert per test" );