Return null when throws() and throwsAsync() assertions fail

Make the behavior explicit in the documentation and type definition.

Author: novemberborn

docs/03-assertions.md

@@ -229,7 +229,7 @@ Finally, this returns a boolean indicating whether the assertion passed.
 
 ### `.throws(fn, expectation?, message?)`
 
-Assert that an error is thrown. `fn` must be a function which should throw. The thrown value *must* be an error. It is returned so you can run more assertions against it.
+Assert that an error is thrown. `fn` must be a function which should throw. The thrown value *must* be an error. It is returned so you can run more assertions against it. If the assertion fails then `null` is returned.
 
 `expectation` can be an object with one or more of the following properties:
 
@@ -257,13 +257,11 @@ test('throws', t => {
 });
 ```
 
-Does not return anything.
-
 ### `.throwsAsync(thrower, expectation?, message?)`
 
 Assert that an error is thrown. `thrower` can be an async function which should throw, or a promise that should reject. This assertion must be awaited.
 
-The thrown value *must* be an error. It is returned so you can run more assertions against it.
+The thrown value *must* be an error. It is returned so you can run more assertions against it. If the assertion fails then `null` is returned.
 
 `expectation` can be an object with one or more of the following properties:
 
@@ -294,8 +292,6 @@ test('rejects', async t => {
 });
 ```
 
-Does not return anything.
-
 ### `.notThrows(fn, message?)`
 
 Assert that no error is thrown. `fn` must be a function which shouldn't throw. Does not return anything.

lib/assert.js

@@ -469,7 +469,7 @@ export class Assertions {
 			let [fn, expectations, message] = args;
 
 			if (!checkMessage('throws', message)) {
-				return;
+				return null;
 			}
 
 			if (typeof fn !== 'function') {
@@ -479,14 +479,14 @@ export class Assertions {
 					message: '`t.throws()` must be called with a function',
 					values: [formatWithLabel('Called with:', fn)]
 				}));
-				return;
+				return null;
 			}
 
 			try {
 				expectations = validateExpectations('throws', expectations, args.length, experiments);
 			} catch (error) {
 				fail(error);
-				return;
+				return null;
 			}
 
 			let retval;
@@ -501,7 +501,7 @@ export class Assertions {
 						message,
 						values: [formatWithLabel('Function returned a promise. Use `t.throwsAsync()` instead:', retval)]
 					}));
-					return;
+					return null;
 				}
 			} catch (error) {
 				actual = error;
@@ -513,7 +513,7 @@ export class Assertions {
 					message,
 					values: [formatWithLabel('Function returned:', retval)]
 				}));
-				return;
+				return null;
 			}
 
 			try {
@@ -531,11 +531,11 @@ export class Assertions {
 			}
 		});
 
-		this.throwsAsync = withSkip((...args) => {
+		this.throwsAsync = withSkip(async (...args) => {
 			let [thrower, expectations, message] = args;
 
 			if (!checkMessage('throwsAsync', message)) {
-				return Promise.resolve();
+				return null;
 			}
 
 			if (typeof thrower !== 'function' && !isPromise(thrower)) {
@@ -545,14 +545,14 @@ export class Assertions {
 					message: '`t.throwsAsync()` must be called with a function or promise',
 					values: [formatWithLabel('Called with:', thrower)]
 				}));
-				return Promise.resolve();
+				return null;
 			}
 
 			try {
 				expectations = validateExpectations('throwsAsync', expectations, args.length, experiments);
 			} catch (error) {
 				fail(error);
-				return Promise.resolve();
+				return null;
 			}
 
 			const handlePromise = async (promise, wasReturned) => {
@@ -583,6 +583,7 @@ export class Assertions {
 					return await intermediate;
 				} catch {
 					// Don't reject the returned promise, even if the assertion fails.
+					return null;
 				}
 			};
 
@@ -605,7 +606,7 @@ export class Assertions {
 					actualStack: actual.stack,
 					values: [formatWithLabel('Function threw synchronously. Use `t.throws()` instead:', actual)]
 				}));
-				return Promise.resolve();
+				return null;
 			}
 
 			if (isPromise(retval)) {
@@ -617,7 +618,7 @@ export class Assertions {
 				message,
 				values: [formatWithLabel('Function returned:', retval)]
 			}));
-			return Promise.resolve();
+			return null;
 		});
 
 		this.notThrows = withSkip((fn, message) => {

test-d/throws.ts

@@ -12,13 +12,15 @@ class CustomError extends Error {
 }
 
 test('throws', t => {
-	expectType<Error>(t.throws(() => {}));
-	const error2: CustomError = t.throws(() => {});
-	expectType<CustomError>(error2);
-	expectType<CustomError>(t.throws<CustomError>(() => {}));
+	expectType<Error | null>(t.throws(() => {}));
+	const error2: CustomError | null = t.throws(() => {});
+	expectType<CustomError | null>(error2);
+	expectType<CustomError | null>(t.throws<CustomError>(() => {}));
 });
 
 test('throwsAsync', async t => {
-	expectType<Error>(await t.throwsAsync(Promise.reject()));
-	expectType<CustomError>(await t.throwsAsync<CustomError>(Promise.reject()));
+	expectType<Error | null>(await t.throwsAsync(async () => {}));
+	expectType<CustomError | null>(await t.throwsAsync<CustomError>(async () => {}));
+	expectType<Error | null>(await t.throwsAsync(Promise.reject()));
+	expectType<CustomError | null>(await t.throwsAsync<CustomError>(Promise.reject()));
 });

test-tap/assert.js

@@ -112,6 +112,16 @@ function failsWith(t, fn, subset, {expectBoolean = true} = {}) {
 }
 
 function throwsAsyncFails(t, fn, subset) {
+	return add(() => {
+		lastFailure = null;
+		return fn().then(retval => {
+			t.equal(retval, null);
+			assertFailure(t, subset);
+		});
+	});
+}
+
+function notThrowsAsyncFails(t, fn, subset) {
 	return add(() => {
 		lastFailure = null;
 		return fn().then(retval => {
@@ -160,6 +170,8 @@ function throwsAsyncPasses(t, fn) {
 	});
 }
 
+const notThrowsAsyncPasses = throwsAsyncPasses;
+
 test('.pass()', t => {
 	passes(t, () => {
 		return assertions.pass();
@@ -1521,31 +1533,31 @@ test('.notThrows()', gather(t => {
 
 test('.notThrowsAsync()', gather(t => {
 	// Passes because the promise is resolved
-	throwsAsyncPasses(t, () => assertions.notThrowsAsync(Promise.resolve()));
+	notThrowsAsyncPasses(t, () => assertions.notThrowsAsync(Promise.resolve()));
 
-	throwsAsyncPasses(t, () => {
+	notThrowsAsyncPasses(t, () => {
 		return assertions.notThrowsAsync(Promise.resolve());
 	});
 
 	// Fails because the promise is rejected
-	throwsAsyncFails(t, () => assertions.notThrowsAsync(Promise.reject(new Error())), {
+	notThrowsAsyncFails(t, () => assertions.notThrowsAsync(Promise.reject(new Error())), {
 		assertion: 'notThrowsAsync',
 		message: '',
 		values: [{label: 'Promise rejected with:', formatted: /Error/}]
 	});
 
 	// Passes because the function returned a resolved promise
-	throwsAsyncPasses(t, () => assertions.notThrowsAsync(() => Promise.resolve()));
+	notThrowsAsyncPasses(t, () => assertions.notThrowsAsync(() => Promise.resolve()));
 
 	// Fails because the function returned a rejected promise
-	throwsAsyncFails(t, () => assertions.notThrowsAsync(() => Promise.reject(new Error())), {
+	notThrowsAsyncFails(t, () => assertions.notThrowsAsync(() => Promise.reject(new Error())), {
 		assertion: 'notThrowsAsync',
 		message: '',
 		values: [{label: 'Returned promise rejected with:', formatted: /Error/}]
 	});
 
 	// Fails because the function throws synchronously
-	throwsAsyncFails(t, () => assertions.notThrowsAsync(() => {
+	notThrowsAsyncFails(t, () => assertions.notThrowsAsync(() => {
 		throw new Error('sync');
 	}, 'message'), {
 		assertion: 'notThrowsAsync',
@@ -1556,15 +1568,15 @@ test('.notThrowsAsync()', gather(t => {
 	});
 
 	// Fails because the function did not return a promise
-	throwsAsyncFails(t, () => assertions.notThrowsAsync(() => {}, 'message'), {
+	notThrowsAsyncFails(t, () => assertions.notThrowsAsync(() => {}, 'message'), {
 		assertion: 'notThrowsAsync',
 		message: 'message',
 		values: [
 			{label: 'Function did not return a promise. Use `t.notThrows()` instead:', formatted: /undefined/}
 		]
 	});
 
-	throwsAsyncFails(t, () => assertions.notThrowsAsync(Promise.resolve(), null), {
+	notThrowsAsyncFails(t, () => assertions.notThrowsAsync(Promise.resolve(), null), {
 		assertion: 'notThrowsAsync',
 		improperUsage: true,
 		message: 'The assertion message must be a string',

types/assertions.d.ts

@@ -279,9 +279,9 @@ export interface SnapshotAssertion {
 export interface ThrowsAssertion {
 	/**
 	 * Assert that the function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error value.
-	 * The error must satisfy all expectations.
+	 * The error must satisfy all expectations. Returns null when the assertion fails.
 	 */
-	<ThrownError extends Error>(fn: () => any, expectations?: ThrowsExpectation | null, message?: string): ThrownError;
+	<ThrownError extends Error>(fn: () => any, expectations?: ThrowsExpectation | null, message?: string): ThrownError | null;
 
 	/** Skip this assertion. */
 	skip(fn: () => any, expectations?: any, message?: string): void;
@@ -290,27 +290,16 @@ export interface ThrowsAssertion {
 export interface ThrowsAsyncAssertion {
 	/**
 	 * Assert that the async function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error
-	 * value. You must await the result.
+	 * value. Returns null when the assertion fails. You must await the result. The error must satisfy all expectations.
 	 */
-	<ThrownError extends Error>(fn: () => PromiseLike<any>, expectations?: null, message?: string): Promise<ThrownError>;
-
-	/**
-	 * Assert that the async function throws [an error](https://www.npmjs.com/package/is-error). If so, returns the error
-	 * value. You must await the result. The error must satisfy all expectations.
-	 */
-	<ThrownError extends Error>(fn: () => PromiseLike<any>, expectations: ThrowsExpectation, message?: string): Promise<ThrownError>;
-
-	/**
-	 * Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
-	 * rejection reason. You must await the result.
-	 */
-	<ThrownError extends Error>(promise: PromiseLike<any>, expectations?: null, message?: string): Promise<ThrownError>; // eslint-disable-line @typescript-eslint/unified-signatures
+	<ThrownError extends Error>(fn: () => PromiseLike<any>, expectations?: ThrowsExpectation | null, message?: string): Promise<ThrownError | null>;
 
 	/**
 	 * Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the
-	 * rejection reason. You must await the result. The error must satisfy all expectations.
+	 * rejection reason. Returns null when the assertion fails. You must await the result. The error must satisfy all
+	 * expectations.
 	 */
-	<ThrownError extends Error>(promise: PromiseLike<any>, expectations: ThrowsExpectation, message?: string): Promise<ThrownError>; // eslint-disable-line @typescript-eslint/unified-signatures
+	<ThrownError extends Error>(promise: PromiseLike<any>, expectations?: ThrowsExpectation | null, message?: string): Promise<ThrownError | null>; // eslint-disable-line @typescript-eslint/unified-signatures
 
 	/** Skip this assertion. */
 	skip(thrower: any, expectations?: any, message?: string): void;