diff --git a/docs/api/expect.md b/docs/api/expect.md index f8ecd2ace..73b496745 100644 --- a/docs/api/expect.md +++ b/docs/api/expect.md @@ -299,6 +299,32 @@ test('we don\'t have apples', () => { }) ``` +## toBeNullable + +- **Type:** `() => Awaitable` + +`toBeNullable` simply asserts if something is nullable (`null` or `undefined`). + +```ts +import { expect, test } from 'vitest' + +function apples() { + return null +} + +function bananas() { + return null +} + +test('we don\'t have apples', () => { + expect(apples()).toBeNullable() +}) + +test('we don\'t have bananas', () => { + expect(bananas()).toBeNullable() +}) +``` + ## toBeNaN - **Type:** `() => Awaitable` diff --git a/packages/expect/src/jest-expect.ts b/packages/expect/src/jest-expect.ts index 62ec29bea..1cb00b2d9 100644 --- a/packages/expect/src/jest-expect.ts +++ b/packages/expect/src/jest-expect.ts @@ -405,6 +405,16 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => { obj, ) }) + def('toBeNullable', function () { + const obj = utils.flag(this, 'object') + this.assert( + obj == null, + 'expected #{this} to be nullish', + 'expected #{this} not to be nullish', + null, + obj, + ) + }) def('toBeDefined', function () { const obj = utils.flag(this, 'object') this.assert( diff --git a/packages/expect/src/types.ts b/packages/expect/src/types.ts index ae97e2e91..6c9e53a8c 100644 --- a/packages/expect/src/types.ts +++ b/packages/expect/src/types.ts @@ -338,6 +338,14 @@ export interface JestAssertion extends jest.Matchers, CustomMa */ toBeNull: () => void + /** + * Used to check that a variable is nullable (null or undefined). + * + * @example + * expect(value).toBeNullable(); + */ + toBeNullable: () => void + /** * Ensure that a variable is not undefined. * diff --git a/test/core/test/jest-expect.test.ts b/test/core/test/jest-expect.test.ts index ca5b4cfd8..0d6b039c4 100644 --- a/test/core/test/jest-expect.test.ts +++ b/test/core/test/jest-expect.test.ts @@ -34,6 +34,9 @@ describe('jest-expect', () => { expect(1).toBe(1) expect(null).toBeNull() expect(1).not.toBeNull() + expect(null).toBeNullable() + expect(undefined).toBeNullable() + expect(0).not.toBeNullable() expect(null).toBeDefined() expect(undefined).not.toBeDefined() expect(undefined).toBeUndefined()