diff --git a/docs/03-assertions.md b/docs/03-assertions.md index 2e719ec85..a739a8cdd 100644 --- a/docs/03-assertions.md +++ b/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. If the assertion fails then `null` is returned. +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. `expectation` can be an object with one or more of the following properties: @@ -261,7 +261,7 @@ 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 `null` is returned. +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: diff --git a/lib/assert.js b/lib/assert.js index ff69b46b9..26cac59c8 100644 --- a/lib/assert.js +++ b/lib/assert.js @@ -469,7 +469,7 @@ export class Assertions { let [fn, expectations, message] = args; if (!checkMessage('throws', message)) { - return null; + return; } 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 null; + return; } try { expectations = validateExpectations('throws', expectations, args.length, experiments); } catch (error) { fail(error); - return null; + return; } let retval; @@ -501,7 +501,7 @@ export class Assertions { message, values: [formatWithLabel('Function returned a promise. Use `t.throwsAsync()` instead:', retval)] })); - return null; + return; } } catch (error) { actual = error; @@ -513,7 +513,7 @@ export class Assertions { message, values: [formatWithLabel('Function returned:', retval)] })); - return null; + return; } try { @@ -535,7 +535,7 @@ export class Assertions { let [thrower, expectations, message] = args; if (!checkMessage('throwsAsync', message)) { - return null; + return; } 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 null; + return; } try { expectations = validateExpectations('throwsAsync', expectations, args.length, experiments); } catch (error) { fail(error); - return null; + return; } const handlePromise = async (promise, wasReturned) => { @@ -583,7 +583,6 @@ export class Assertions { return await intermediate; } catch { // Don't reject the returned promise, even if the assertion fails. - return null; } }; @@ -606,7 +605,7 @@ export class Assertions { actualStack: actual.stack, values: [formatWithLabel('Function threw synchronously. Use `t.throws()` instead:', actual)] })); - return null; + return; } if (isPromise(retval)) { @@ -618,7 +617,6 @@ export class Assertions { message, values: [formatWithLabel('Function returned:', retval)] })); - return null; }); this.notThrows = withSkip((fn, message) => { diff --git a/test-d/throws.ts b/test-d/throws.ts index ea25e1305..2b7b2c145 100644 --- a/test-d/throws.ts +++ b/test-d/throws.ts @@ -12,15 +12,15 @@ class CustomError extends Error { } test('throws', t => { - expectType(t.throws(() => {})); - const error2: CustomError | null = t.throws(() => {}); - expectType(error2); - expectType(t.throws(() => {})); + expectType(t.throws(() => {})); + const error2: CustomError | undefined = t.throws(() => {}); + expectType(error2); + expectType(t.throws(() => {})); }); test('throwsAsync', async t => { - expectType(await t.throwsAsync(async () => {})); - expectType(await t.throwsAsync(async () => {})); - expectType(await t.throwsAsync(Promise.reject())); - expectType(await t.throwsAsync(Promise.reject())); + expectType(await t.throwsAsync(async () => {})); + expectType(await t.throwsAsync(async () => {})); + expectType(await t.throwsAsync(Promise.reject())); + expectType(await t.throwsAsync(Promise.reject())); }); diff --git a/test-tap/assert.js b/test-tap/assert.js index 4891b52ce..86e1e6613 100644 --- a/test-tap/assert.js +++ b/test-tap/assert.js @@ -115,7 +115,7 @@ function throwsAsyncFails(t, fn, subset) { return add(() => { lastFailure = null; return fn().then(retval => { - t.equal(retval, null); + t.equal(retval, undefined); assertFailure(t, subset); }); }); diff --git a/types/assertions.d.ts b/types/assertions.d.ts index 005c0197c..404f720ec 100644 --- a/types/assertions.d.ts +++ b/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. Returns null when the assertion fails. + * The error must satisfy all expectations. Returns undefined when the assertion fails. */ - (fn: () => any, expectations?: ThrowsExpectation, message?: string): ThrownError | null; + (fn: () => any, expectations?: ThrowsExpectation, message?: string): ThrownError | undefined; /** Skip this assertion. */ skip(fn: () => any, expectations?: any, message?: string): void; @@ -290,16 +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. Returns null when the assertion fails. You must await the result. The error must satisfy all expectations. + * value. Returns undefined when the assertion fails. You must await the result. The error must satisfy all expectations. */ - (fn: () => PromiseLike, expectations?: ThrowsExpectation, message?: string): Promise; + (fn: () => PromiseLike, expectations?: ThrowsExpectation, message?: string): Promise; /** * Assert that the promise rejects with [an error](https://www.npmjs.com/package/is-error). If so, returns the - * rejection reason. Returns null when the assertion fails. You must await the result. The error must satisfy all + * rejection reason. Returns undefined when the assertion fails. You must await the result. The error must satisfy all * expectations. */ - (promise: PromiseLike, expectations?: ThrowsExpectation, message?: string): Promise; // eslint-disable-line @typescript-eslint/unified-signatures + (promise: PromiseLike, expectations?: ThrowsExpectation, message?: string): Promise; // eslint-disable-line @typescript-eslint/unified-signatures /** Skip this assertion. */ skip(thrower: any, expectations?: any, message?: string): void;