Support expectation object in t.throws()

Fixes #1047. Fixes #1676.

A combination of the following expectations is supported:

```js
t.throws(fn, {of: SyntaxError}) // err instanceof SyntaxError
t.throws(fn, {name: 'SyntaxError'}) // err.name === 'SyntaxError'
t.throws(fn, {is: expectedErrorInstance}) // err === expectedErrorInstance
t.throws(fn, {message: 'expected error message'}) // err.message === 'expected error message'
t.throws(fn, {message: /expected error message/}) // /expected error message/.test(err.message)
```

Author: novemberborn

index.d.ts

@@ -2,7 +2,16 @@ export interface ObservableLike {
 	subscribe(observer: (value: any) => void): void;
 }
 
-export type ThrowsErrorValidator = (new (...args: Array<any>) => any) | RegExp | string;
+export type Constructor = (new (...args: Array<any>) => any);
+
+export type ThrowsExpectation = {
+	instanceOf?: Constructor;
+	is?: Error;
+	message?: string | RegExp;
+	name?: string;
+};
+
+export type ThrowsErrorValidator = Constructor | RegExp | string | ThrowsExpectation;
 
 export interface SnapshotOptions {
 	id?: string;

index.js.flow

@@ -7,7 +7,16 @@ export interface ObservableLike {
 	subscribe(observer: (value: any) => void): void;
 }
 
-export type ThrowsErrorValidator = Class<{constructor(...args: Array<any>): any}> | RegExp | string;
+export type Constructor = Class<{constructor(...args: Array<any>): any}>;
+
+export type ThrowsExpectation = {
+	instanceOf?: Constructor;
+	is?: Error;
+	message?: string | RegExp;
+	name?: string;
+};
+
+export type ThrowsErrorValidator = Constructor | RegExp | string | ThrowsExpectation;
 
 export interface SnapshotOptions {
 	id?: string;

lib/assert.js

@@ -28,6 +28,8 @@ function formatWithLabel(label, value) {
 	return formatDescriptorWithLabel(label, concordance.describe(value, concordanceOptions));
 }
 
+const hasOwnProperty = (obj, prop) => Object.prototype.hasOwnProperty.call(obj, prop);
+
 class AssertionError extends Error {
 	constructor(opts) {
 		super(opts.message || '');
@@ -157,7 +159,7 @@ function wrapAssertions(callbacks) {
 			}
 		},
 
-		throws(thrower, expected, message) {
+		throws(thrower, expected, message) { // eslint-disable-line complexity
 			if (typeof thrower !== 'function' && !isPromise(thrower) && !isObservable(thrower)) {
 				fail(this, new AssertionError({
 					assertion: 'throws',
@@ -169,19 +171,62 @@ function wrapAssertions(callbacks) {
 			}
 
 			if (typeof expected === 'function') {
-				expected = {of: expected};
+				expected = {instanceOf: expected};
 			} else if (typeof expected === 'string' || expected instanceof RegExp) {
 				expected = {message: expected};
-			} else if (arguments.length === 1) {
+			} else if (arguments.length === 1 || expected === null) {
 				expected = {};
-			} else if (expected !== null) {
+			} else if (typeof expected !== 'object' || Array.isArray(expected) || Object.keys(expected).length === 0) {
 				fail(this, new AssertionError({
 					assertion: 'throws',
-					improperUsage: true,
-					message: 'The second argument to `t.throws()` must be a function, string, regular expression or `null`',
+					message: 'The second argument to `t.throws()` must be a function, string, regular expression, expectation object or `null`',
 					values: [formatWithLabel('Called with:', expected)]
 				}));
 				return;
+			} else {
+				if (hasOwnProperty(expected, 'instanceOf') && typeof expected.instanceOf !== 'function') {
+					fail(this, new AssertionError({
+						assertion: 'throws',
+						message: 'The `instanceOf` property of the second argument to `t.throws()` must be a function',
+						values: [formatWithLabel('Called with:', expected)]
+					}));
+					return;
+				}
+
+				if (hasOwnProperty(expected, 'message') && typeof expected.message !== 'string' && !(expected.message instanceof RegExp)) {
+					fail(this, new AssertionError({
+						assertion: 'throws',
+						message: 'The `message` property of the second argument to `t.throws()` must be a string or regular expression',
+						values: [formatWithLabel('Called with:', expected)]
+					}));
+					return;
+				}
+
+				if (hasOwnProperty(expected, 'name') && typeof expected.name !== 'string') {
+					fail(this, new AssertionError({
+						assertion: 'throws',
+						message: 'The `name` property of the second argument to `t.throws()` must be a string',
+						values: [formatWithLabel('Called with:', expected)]
+					}));
+					return;
+				}
+
+				for (const key of Object.keys(expected)) {
+					switch (key) {
+						case 'instanceOf':
+						case 'is':
+						case 'message':
+						case 'name':
+							continue;
+						default:
+							fail(this, new AssertionError({
+								assertion: 'throws',
+								message: 'The second argument to `t.throws()` contains unexpected properties',
+								values: [formatWithLabel('Called with:', expected)]
+							}));
+							return;
+					}
+				}
 			}
 
 			// Note: this function *must* throw exceptions, since it can be used
@@ -196,14 +241,38 @@ function wrapAssertions(callbacks) {
 					});
 				}
 
-				if (expected.of && !(actual instanceof expected.of)) {
+				if (hasOwnProperty(expected, 'is') && actual !== expected.is) {
+					throw new AssertionError({
+						assertion: 'throws',
+						message,
+						stack,
+						values: [
+							formatWithLabel(`${prefix} unexpected exception:`, actual),
+							formatWithLabel('Expected to be strictly equal to:', expected.is)
+						]
+					});
+				}
+
+				if (expected.instanceOf && !(actual instanceof expected.instanceOf)) {
+					throw new AssertionError({
+						assertion: 'throws',
+						message,
+						stack,
+						values: [
+							formatWithLabel(`${prefix} unexpected exception:`, actual),
+							formatWithLabel('Expected instance of:', expected.instanceOf)
+						]
+					});
+				}
+
+				if (typeof expected.name === 'string' && actual.name !== expected.name) {
 					throw new AssertionError({
 						assertion: 'throws',
 						message,
 						stack,
 						values: [
 							formatWithLabel(`${prefix} unexpected exception:`, actual),
-							formatWithLabel('Expected instance of:', expected.of)
+							formatWithLabel('Expected name to equal:', expected.name)
 						]
 					});
 				}

readme.md

@@ -916,7 +916,14 @@ Assert that an error is thrown. `thrower` can be a function which should throw,
 
 The thrown value *must* be an error. It is returned so you can run more assertions against it.
 
-`expected` can be a constructor, in which case the thrown value must be an instance of the constructor. It can be a string, which is compared against the thrown error's message, or a regular expression which is matched against this message. `expected` does not need to be specified. If you don't need it but do want to set an assertion message you have to specify `null`.
+`expected` can be a constructor, in which case the thrown error must be an instance of the constructor. It can be a string, which is compared against the thrown error's message, or a regular expression which is matched against this message. You can also specify a matcher object with one or more of the following properties:
+
+* `instanceOf`: a constructor, the thrown error must be an instance of
+* `is`: the thrown error must be strictly equal to `expected.is`
+* `message`: either a string, which is compared against the thrown error's message, or a regular expression, which is matched against this message
+* `name`: the expected `.name` value of the thrown error
+
+`expected` does not need to be specified. If you don't need it but do want to set an assertion message you have to specify `null`.
 
 Example:
 
@@ -955,11 +962,9 @@ When testing an asynchronous function you must also wait for the assertion to co
 
 ```js
 test('throws', async t => {
-	const error = await t.throws(async () => {
+	await t.throws(async () => {
 		throw new TypeError('🦄');
-	}, TypeError);
-
-	t.is(error.message, '🦄');
+	}, {instanceOf: TypeError, message: '🦄'});
 });
 ```
 

test/assert.js

@@ -145,22 +145,24 @@ function eventuallyFails(t, fn) {
 
 function passes(t, fn) {
 	lastPassed = false;
+	lastFailure = null;
 	fn();
 	if (lastPassed) {
 		t.pass();
 	} else {
-		t.fail('Expected assertion to pass');
+		t.ifError(lastFailure, 'Expected assertion to pass');
 	}
 }
 
 function eventuallyPasses(t, fn) {
 	return add(() => {
 		lastPassed = false;
+		lastFailure = null;
 		return fn().then(() => {
 			if (lastPassed) {
 				t.pass();
 			} else {
-				t.fail('Expected assertion to pass');
+				t.ifError(lastFailure, 'Expected assertion to pass');
 			}
 		});
 	});
@@ -726,8 +728,8 @@ test('.throws()', gather(t => {
 	});
 
 	// Fails because thrown error's message is not equal to 'bar'
-	const err = new Error('foo');
 	failsWith(t, () => {
+		const err = new Error('foo');
 		assertions.throws(() => {
 			throw err;
 		}, 'bar');
@@ -742,6 +744,7 @@ test('.throws()', gather(t => {
 
 	// Fails because thrown error is not the right instance
 	failsWith(t, () => {
+		const err = new Error('foo');
 		assertions.throws(() => {
 			throw err;
 		}, class Foo {});
@@ -756,6 +759,7 @@ test('.throws()', gather(t => {
 
 	// Passes because thrown error's message is equal to 'bar'
 	passes(t, () => {
+		const err = new Error('foo');
 		assertions.throws(() => {
 			throw err;
 		}, 'foo');
@@ -768,6 +772,52 @@ test('.throws()', gather(t => {
 		});
 	});
 
+	// Passes because the correct error is thrown.
+	passes(t, () => {
+		const err = new Error('foo');
+		assertions.throws(() => {
+			throw err;
+		}, {is: err});
+	});
+
+	// Fails because the thrown value is not an error
+	fails(t, () => {
+		const obj = {};
+		assertions.throws(() => {
+			throw obj;
+		}, {is: obj});
+	});
+
+	// Fails because the thrown value is not the right one
+	fails(t, () => {
+		const err = new Error('foo');
+		assertions.throws(() => {
+			throw err;
+		}, {is: {}});
+	});
+
+	// Passes because the correct error is thrown.
+	passes(t, () => {
+		assertions.throws(() => {
+			throw new TypeError();
+		}, {name: 'TypeError'});
+	});
+
+	// Fails because the thrown value is not an error
+	fails(t, () => {
+		assertions.throws(() => {
+			const err = {name: 'Bob'};
+			throw err;
+		}, {name: 'Bob'});
+	});
+
+	// Fails because the thrown value is not the right one
+	fails(t, () => {
+		assertions.throws(() => {
+			throw new Error('foo');
+		}, {name: 'TypeError'});
+	});
+
 	// Fails because the promise is resolved, not rejected.
 	eventuallyFailsWith(t, () => assertions.throws(Promise.resolve('foo')), {
 		assertion: 'throws',
@@ -911,10 +961,58 @@ test('.throws() fails if passed a bad expectation', t => {
 		assertions.throws(() => {}, true);
 	}, {
 		assertion: 'throws',
-		message: 'The second argument to `t.throws()` must be a function, string, regular expression or `null`',
+		message: 'The second argument to `t.throws()` must be a function, string, regular expression, expectation object or `null`',
 		values: [{label: 'Called with:', formatted: /true/}]
 	});
 
+	failsWith(t, () => {
+		assertions.throws(() => {}, {});
+	}, {
+		assertion: 'throws',
+		message: 'The second argument to `t.throws()` must be a function, string, regular expression, expectation object or `null`',
+		values: [{label: 'Called with:', formatted: /\{\}/}]
+	});
+
+	failsWith(t, () => {
+		assertions.throws(() => {}, []);
+	}, {
+		assertion: 'throws',
+		message: 'The second argument to `t.throws()` must be a function, string, regular expression, expectation object or `null`',
+		values: [{label: 'Called with:', formatted: /\[\]/}]
+	});
+
+	failsWith(t, () => {
+		assertions.throws(() => {}, {instanceOf: null});
+	}, {
+		assertion: 'throws',
+		message: 'The `instanceOf` property of the second argument to `t.throws()` must be a function',
+		values: [{label: 'Called with:', formatted: /instanceOf: null/}]
+	});
+
+	failsWith(t, () => {
+		assertions.throws(() => {}, {message: null});
+	}, {
+		assertion: 'throws',
+		message: 'The `message` property of the second argument to `t.throws()` must be a string or regular expression',
+		values: [{label: 'Called with:', formatted: /message: null/}]
+	});
+
+	failsWith(t, () => {
+		assertions.throws(() => {}, {name: null});
+	}, {
+		assertion: 'throws',
+		message: 'The `name` property of the second argument to `t.throws()` must be a string',
+		values: [{label: 'Called with:', formatted: /name: null/}]
+	});
+
+	failsWith(t, () => {
+		assertions.throws(() => {}, {is: {}, message: '', name: '', of() {}, foo: null});
+	}, {
+		assertion: 'throws',
+		message: 'The second argument to `t.throws()` contains unexpected properties',
+		values: [{label: 'Called with:', formatted: /foo: null/}]
+	});
+
 	t.end();
 });