Allow throws / throwsAsync to work with any value, not just errors

Fixes #2517. Co-authored-by: Mark Wubben <mark@novemberborn.net>

Author: adiSuper94

docs/03-assertions.md

@@ -172,10 +172,11 @@ 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. If the assertion fails then `undefined` is returned.
+Assert that an error is thrown. `fn` must be a function which should throw. By default, the thrown value *must* be an error. It is returned so you can run more assertions against it. If the assertion fails then `undefined` is returned.
 
 `expectation` can be an object with one or more of the following properties:
 
+* `any`: a boolean only available in AVA 6, if `true` then the thrown value does not need to be an error. Defaults to `false`
 * `instanceOf`: a constructor, the thrown error must be an instance of
 * `is`: the thrown error must be strictly equal to `expectation.is`
 * `message`: the following types are valid:
@@ -207,10 +208,11 @@ test('throws', t => {
 
 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. If the assertion fails then `undefined` is returned.
+By default, the thrown value *must* be an error. It is returned so you can run more assertions against it. If the assertion fails then `undefined` is returned.
 
 `expectation` can be an object with one or more of the following properties:
 
+* `any`: a boolean only available in AVA 6, if `true` then the thrown value does not need to be an error. Defaults to `false`
 * `instanceOf`: a constructor, the thrown error must be an instance of
 * `is`: the thrown error must be strictly equal to `expectation.is`
 * `message`: the following types are valid:

docs/08-common-pitfalls.md

@@ -14,7 +14,12 @@ Note that the following is not a native error:
 const error = Object.create(Error.prototype);
 ```
 
-This can be surprising, since `error instanceof Error` returns `true`.
+This can be surprising, since `error instanceof Error` returns `true`. You can set `any: true` in the expectations to handle these values:
+
+```js
+const error = Object.create(Error.prototype);
+t.throws(() => { throw error }, {any: true});
+```
 
 ## AVA in Docker
 

lib/assert.js

@@ -127,13 +127,21 @@ function validateExpectations(assertion, expectations, numberArgs) { // eslint-d
 });
 }
 
+if (Object.hasOwn(expectations, 'any') && typeof expectations.any !== 'boolean') {
+throw new AssertionError(`The \`any\` property of the second argument to \`${assertion}\` must be a boolean`, {
+assertion,
+formattedDetails: [formatWithLabel('Called with:', expectations)],
+});
+}
+
 for (const key of Object.keys(expectations)) {
 switch (key) {
 case 'instanceOf':
 case 'is':
 case 'message':
 case 'name':
-case 'code': {
+case 'code':
+case 'any': {
 continue;
 }
 
@@ -153,7 +161,8 @@ function validateExpectations(assertion, expectations, numberArgs) { // eslint-d
 // Note: this function *must* throw exceptions, since it can be used
 // as part of a pending assertion for promises.
 function assertExpectations({actual, expectations, message, prefix, assertion, assertionStack}) {
-if (!isNativeError(actual)) {
+const allowThrowAnything = Object.hasOwn(expectations, 'any') && expectations.any;
+if (!isNativeError(actual) && !allowThrowAnything) {
 throw new AssertionError(message, {
 assertion,
 assertionStack,

test-tap/assert.js

@@ -822,6 +822,11 @@ test('.throws()', gather(t => {
 throw new Error('foo');
 }));
 
+// Passes when string is thrown, only when any is set to true.
+passes(t, () => assertions.throws(() => {
+throw 'foo'; // eslint-disable-line no-throw-literal
+}, {any: true}));
+
 // Passes because the correct error is thrown.
 passes(t, () => {
 const error = new Error('foo');
@@ -1023,9 +1028,19 @@ test('.throwsAsync()', gather(t => {
 formattedDetails: [{label: 'Returned promise resolved with:', formatted: /'foo'/}],
 });
 
+// Fails because the function returned a promise that rejected, but not with an error.
+throwsAsyncFails(t, () => assertions.throwsAsync(() => Promise.reject('foo')), { // eslint-disable-line prefer-promise-reject-errors
+assertion: 't.throwsAsync()',
+message: '',
+formattedDetails: [{label: 'Returned promise rejected with exception that is not an error:', formatted: /'foo'/}],
+});
+
 // Passes because the promise was rejected with an error.
 throwsAsyncPasses(t, () => assertions.throwsAsync(Promise.reject(new Error())));
 
+// Passes because the promise was rejected with an with an non-error exception, & set `any` to true in expectation.
+throwsAsyncPasses(t, () => assertions.throwsAsync(Promise.reject('foo'), {any: true})); // eslint-disable-line prefer-promise-reject-errors
+
 // Passes because the function returned a promise rejected with an error.
 throwsAsyncPasses(t, () => assertions.throwsAsync(() => Promise.reject(new Error())));
 
@@ -1134,6 +1149,12 @@ test('.throws() fails if passed a bad expectation', t => {
 formattedDetails: [{label: 'Called with:', formatted: /\[]/}],
 });
 
+failsWith(t, () => assertions.throws(() => {}, {any: {}}), {
+assertion: 't.throws()',
+message: 'The `any` property of the second argument to `t.throws()` must be a boolean',
+formattedDetails: [{label: 'Called with:', formatted: /any: {}/}],
+});
+
 failsWith(t, () => assertions.throws(() => {}, {code: {}}), {
 assertion: 't.throws()',
 message: 'The `code` property of the second argument to `t.throws()` must be a string or number',
@@ -1204,6 +1225,12 @@ test('.throwsAsync() fails if passed a bad expectation', t => {
 formattedDetails: [{label: 'Called with:', formatted: /\[]/}],
 }, {expectBoolean: false});
 
+failsWith(t, () => assertions.throwsAsync(() => {}, {any: {}}), {
+assertion: 't.throwsAsync()',
+message: 'The `any` property of the second argument to `t.throwsAsync()` must be a boolean',
+formattedDetails: [{label: 'Called with:', formatted: /any: {}/}],
+}, {expectBoolean: false});
+
 failsWith(t, () => assertions.throwsAsync(() => {}, {code: {}}), {
 assertion: 't.throwsAsync()',
 message: 'The `code` property of the second argument to `t.throwsAsync()` must be a string or number',

test-tap/reporters/tap.failfast.v16.log

@@ -5,7 +5,7 @@ not ok 1 - a › fails
  name: AssertionError
  assertion: t.fail()
  message: Test failed via `t.fail()`
- at: 'ExecutionContext.fail (/lib/assert.js:285:9)'
+ at: 'ExecutionContext.fail (/lib/assert.js:294:9)'
  ...
 ---tty-stream-chunk-separator
 

test-tap/reporters/tap.failfast.v18.log

@@ -5,7 +5,7 @@ not ok 1 - a › fails
  name: AssertionError
  assertion: t.fail()
  message: Test failed via `t.fail()`
- at: 'ExecutionContext.fail (/lib/assert.js:285:9)'
+ at: 'ExecutionContext.fail (/lib/assert.js:294:9)'
  ...
 ---tty-stream-chunk-separator
 

test-tap/reporters/tap.failfast.v20.log

@@ -5,7 +5,7 @@ not ok 1 - a › fails
  name: AssertionError
  assertion: t.fail()
  message: Test failed via `t.fail()`
- at: 'ExecutionContext.fail (/lib/assert.js:285:9)'
+ at: 'ExecutionContext.fail (/lib/assert.js:294:9)'
  ...
 ---tty-stream-chunk-separator
 

test-tap/reporters/tap.failfast2.v16.log

@@ -5,7 +5,7 @@ not ok 1 - a › fails
  name: AssertionError
  assertion: t.fail()
  message: Test failed via `t.fail()`
- at: 'ExecutionContext.fail (/lib/assert.js:285:9)'
+ at: 'ExecutionContext.fail (/lib/assert.js:294:9)'
  ...
 ---tty-stream-chunk-separator
 # 1 test remaining in a.cjs

test-tap/reporters/tap.failfast2.v18.log

@@ -5,7 +5,7 @@ not ok 1 - a › fails
  name: AssertionError
  assertion: t.fail()
  message: Test failed via `t.fail()`
- at: 'ExecutionContext.fail (/lib/assert.js:285:9)'
+ at: 'ExecutionContext.fail (/lib/assert.js:294:9)'
  ...
 ---tty-stream-chunk-separator
 # 1 test remaining in a.cjs

test-tap/reporters/tap.failfast2.v20.log

@@ -5,7 +5,7 @@ not ok 1 - a › fails
  name: AssertionError
  assertion: t.fail()
  message: Test failed via `t.fail()`
- at: 'ExecutionContext.fail (/lib/assert.js:285:9)'
+ at: 'ExecutionContext.fail (/lib/assert.js:294:9)'
  ...
 ---tty-stream-chunk-separator
 # 1 test remaining in a.cjs