feat(expect): support toBeNullable expect function to check provided value is nullish (#8294)

Shinyaigeek · sheremet-va · web-flow · commit eeec501de47c · 2025-07-14T11:00:21.000+02:00
Co-authored-by: Vladimir &lt;sleuths.slews0s@icloud.com&gt;
diff --git a/docs/api/expect.md b/docs/api/expect.md
@@ -299,6 +299,32 @@ test('we don\'t have apples', () => {
 })
 ```
 
+## toBeNullable
+
+- **Type:** `() => Awaitable<void>`
+
+`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<void>`
diff --git 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
@@ -338,6 +338,14 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, 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
@@ -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()
