assert: add rejects() and doesNotReject()

Implement asynchronous equivalent for assert.throws() and
assert.doesNotThrow().
Backport-PR-URL: #24019
PR-URL: #18023
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Shingo Inoue <leko.noor@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

Author: feugy

doc/api/assert.md

@@ -242,6 +242,43 @@ If the values are not equal, an `AssertionError` is thrown with a `message`
 property set equal to the value of the `message` parameter. If the `message`
 parameter is undefined, a default error message is assigned.
 
+## assert.doesNotReject(block[, error][, message])
+<!-- YAML
+added: REPLACEME
+-->
+*`block` {Function}
+*`error` {RegExp|Function}
+*`message` {any}
+
+Awaits for the promise returned by function `block` to complete and not be
+rejected. See [`assert.rejects()`][] for more details.
+
+When `assert.doesNotReject()` is called, it will immediately call the `block`
+function, and awaits for completion.
+
+Besides the async nature to await the completion behaves identical to
+[`assert.doesNotThrow()`][].
+
+```js
+(async () => {
+awaitassert.doesNotReject(
+async () => {
+thrownewTypeError('Wrong value');
+ },
+SyntaxError
+ );
+})();
+```
+
+```js
+assert.doesNotReject(
+ () =>Promise.reject(newTypeError('Wrong value')),
+SyntaxError
+).then(() => {
+// ...
+});
+```
+
 ## assert.doesNotThrow(block[, error][, message])
 <!-- YAML
 added: v0.1.21
@@ -631,6 +668,48 @@ If the values are not strictly equal, an `AssertionError` is thrown with a
 `message` property set equal to the value of the `message` parameter. If the
 `message` parameter is undefined, a default error message is assigned.
 
+## assert.rejects(block[, error][, message])
+<!-- YAML
+added: REPLACEME
+-->
+*`block` {Function}
+*`error` {RegExp|Function|Object}
+*`message` {any}
+
+Awaits for promise returned by function `block` to be rejected.
+
+When `assert.rejects()` is called, it will immediately call the `block`
+function, and awaits for completion.
+
+Besides the async nature to await the completion behaves identical to
+[`assert.throws()`][].
+
+If specified, `error` can be a constructor, [`RegExp`][], a validation
+function, or an object where each property will be tested for.
+
+If specified, `message` will be the message provided by the `AssertionError` if
+the block fails to reject.
+
+```js
+(async () => {
+awaitassert.rejects(
+async () => {
+thrownewError('Wrong value');
+ },
+Error
+ );
+})();
+```
+
+```js
+assert.rejects(
+ () =>Promise.reject(newError('Wrong value')),
+Error
+).then(() => {
+// ...
+});
+```
+
 ## assert.throws(block[, error][, message])
 <!-- YAML
 added: v0.1.21
@@ -786,6 +865,7 @@ For more information, see
 [`assert.ok()`]: #assert_assert_ok_value_message
 [`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message
 [`assert.throws()`]: #assert_assert_throws_block_error_message
+[`assert.rejects()`]: #assert_assert_rejects_block_error_message
 [`strict mode`]: #assert_strict_mode
 [Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
 [Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring

lib/assert.js

@@ -718,17 +718,27 @@ function getActual(block) {
 }
 }
 
-// Expected to throw an error.
-assert.throws=functionthrows(block,error,message){
-constactual=getActual(block);
+asyncfunctionwaitForActual(block){
+if(typeofblock!=='function'){
+thrownewerrors.ERR_INVALID_ARG_TYPE('block','Function',block);
+}
+try{
+awaitblock();
+}catch(e){
+returne;
+}
+returnerrors.NO_EXCEPTION_SENTINEL;
+}
 
+// Expected to throw an error.
+functionexpectsError(stackStartFn,actual,error,message){
 if(typeoferror==='string'){
-if(arguments.length===3)
+if(arguments.length===4){
 thrownewerrors.TypeError('ERR_INVALID_ARG_TYPE',
 'error',
 ['Function','RegExp'],
 error);
-
+}
 message=error;
 error=null;
 }
@@ -739,21 +749,21 @@ assert.throws = function throws(block, error, message) {
 details+=` (${error.name})`;
 }
 details+=message ? `: ${message}` : '.';
+constfnType=stackStartFn===rejects ? 'rejection' : 'exception';
 innerFail({
  actual,
 expected: error,
-operator: 'throws',
-message: `Missing expected exception${details}`,
-stackStartFn: throws
+operator: stackStartFn.name,
+message: `Missing expected ${fnType}${details}`,
+ stackStartFn
 });
 }
 if(error&&expectedException(actual,error,message)===false){
 throwactual;
 }
-};
+}
 
-assert.doesNotThrow=functiondoesNotThrow(block,error,message){
-constactual=getActual(block);
+functionexpectsNoError(stackStartFn,actual,error,message){
 if(actual===undefined)
 return;
 
@@ -764,16 +774,41 @@ assert.doesNotThrow = function doesNotThrow(block, error, message) {
 
 if(!error||expectedException(actual,error)){
 constdetails=message ? `: ${message}` : '.';
+constfnType=stackStartFn===doesNotReject ? 'rejection' : 'exception';
 innerFail({
  actual,
 expected: error,
-operator: 'doesNotThrow',
-message: `Got unwanted exception${details}\n${actual.message}`,
-stackStartFn: doesNotThrow
+operator: stackStartFn.name,
+message: `Got unwanted ${fnType}${details}\n${actual.message}`,
+ stackStartFn
 });
 }
 throwactual;
-};
+}
+
+functionthrows(block, ...args){
+expectsError(throws,getActual(block), ...args);
+}
+
+assert.throws=throws;
+
+asyncfunctionrejects(block, ...args){
+expectsError(rejects,awaitwaitForActual(block), ...args);
+}
+
+assert.rejects=rejects;
+
+functiondoesNotThrow(block, ...args){
+expectsNoError(doesNotThrow,getActual(block), ...args);
+}
+
+assert.doesNotThrow=doesNotThrow;
+
+asyncfunctiondoesNotReject(block, ...args){
+expectsNoError(doesNotReject,awaitwaitForActual(block), ...args);
+}
+
+assert.doesNotReject=doesNotReject;
 
 assert.ifError=functionifError(err){if(err)throwerr;};
 

test/parallel/test-assert-async.js

@@ -0,0 +1,66 @@
+'use strict';
+constcommon=require('../common');
+constassert=require('assert');
+const{ promisify }=require('util');
+constwait=promisify(setTimeout);
+
+/* eslint-disable prefer-common-expectserror, no-restricted-properties */
+
+// Test assert.rejects() and assert.doesNotReject() by checking their
+// expected output and by verifying that they do not work sync
+
+assert.rejects(
+()=>assert.fail(),
+common.expectsError({
+code: 'ERR_ASSERTION',
+type: assert.AssertionError,
+message: 'Failed'
+})
+);
+
+assert.doesNotReject(()=>{});
+
+{
+constpromise=assert.rejects(async()=>{
+awaitwait(1);
+assert.fail();
+},common.expectsError({
+code: 'ERR_ASSERTION',
+type: assert.AssertionError,
+message: 'Failed'
+}));
+assert.doesNotReject(()=>promise);
+}
+
+{
+constpromise=assert.doesNotReject(async()=>{
+awaitwait(1);
+thrownewError();
+});
+assert.rejects(()=>promise,
+(err)=>{
+assert(errinstanceofassert.AssertionError,
+`${err.name} is not instance of AssertionError`);
+assert.strictEqual(err.code,'ERR_ASSERTION');
+assert(/^Gotunwantedrejection\.\n$/.test(err.message));
+assert.strictEqual(err.operator,'doesNotReject');
+assert.ok(!err.stack.includes('at Function.doesNotReject'));
+returntrue;
+}
+);
+}
+
+{
+constpromise=assert.rejects(()=>{});
+assert.rejects(()=>promise,
+(err)=>{
+assert(errinstanceofassert.AssertionError,
+`${err.name} is not instance of AssertionError`);
+assert.strictEqual(err.code,'ERR_ASSERTION');
+assert(/^Missingexpectedrejection\.$/.test(err.message));
+assert.strictEqual(err.operator,'rejects');
+assert.ok(!err.stack.includes('at Function.rejects'));
+returntrue;
+}
+);
+}

test/parallel/test-assert.js

@@ -443,6 +443,7 @@ assert.throws(makeBlock(thrower, TypeError));
 }catch(e){
 threw=true;
 assert.ok(einstanceofa.AssertionError);
+assert.ok(!e.stack.includes('at Function.doesNotThrow'));
 }
 assert.strictEqual(true,threw,
 'a.doesNotThrow is not catching type matching errors');
@@ -544,6 +545,16 @@ a.throws(makeBlock(thrower, TypeError), (err) => {
 code: 'ERR_ASSERTION',
 message: /^Missingexpectedexception\(TypeError\):fhqwhgads$/
 }));
+
+letthrew=false;
+try{
+a.throws(noop);
+}catch(e){
+threw=true;
+assert.ok(einstanceofa.AssertionError);
+assert.ok(!e.stack.includes('at Function.throws'));
+}
+assert.ok(threw);
 }
 
 constcircular={y: 1};