feat(matchers): add toBeEmptyArray

.changeset/spotty-plums-thank.md

@@ -0,0 +1,5 @@
+---
+'jest-extended': minor
+---
+
+Introduce new matcher `toBeEmptyArray`

src/matchers/index.ts

@@ -12,6 +12,7 @@ export { toBeBoolean } from './toBeBoolean';
 export { toBeDate } from './toBeDate';
 export { toBeDateString } from './toBeDateString';
 export { toBeEmpty } from './toBeEmpty';
+export { toBeEmptyArray } from './toBeEmptyArray';
 export { toBeEmptyObject } from './toBeEmptyObject';
 export { toBeEven } from './toBeEven';
 export { toBeExtensible } from './toBeExtensible';

src/matchers/toBeEmptyArray.ts

@@ -0,0 +1,20 @@
+export function toBeEmptyArray(actual: unknown) {
+  // @ts-expect-error OK to have implicit any for this.utils
+  const { printReceived, matcherHint } = this.utils;
+
+  const pass = Array.isArray(actual) && actual.length === 0;
+
+  return {
+    pass,
+    message: () =>
+      pass
+        ? matcherHint('.not.toBeEmptyArray', 'received', '') +
+          '\n\n' +
+          'Expected value to not be an empty array, received:\n' +
+          `  ${printReceived(actual)}`
+        : matcherHint('.toBeEmptyArray', 'received', '') +
+          '\n\n' +
+          'Expected value to be an empty array, received:\n' +
+          `  ${printReceived(actual)}`,
+  };
+}

test/matchers/__snapshots__/toBeEmptyArray.test.ts.snap

@@ -0,0 +1,64 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toBeEmptyArray fails when given an empty array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toBeEmptyArray()</intensity>
+
+Expected value to not be an empty array, received:
+  <red>[]</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of () => { } which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>[Function anonymous]</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of {} which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>{}</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of 0 which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>0</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of NaN which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>NaN</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of false which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>false</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of null which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>null</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of true which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>true</color>"
+`;
+
+exports[`.toBeEmptyArray fails when given type of undefined which is not an array 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeEmptyArray()</intensity>
+
+Expected value to be an empty array, received:
+  <red>undefined</color>"
+`;

test/matchers/toBeEmptyArray.test.ts

@@ -0,0 +1,32 @@
+import * as matcher from 'src/matchers/toBeEmptyArray';
+
+expect.extend(matcher);
+
+describe('.toBeEmptyArray', () => {
+  {
+    test('passes when given an empty array', () => {
+      expect([]).toBeEmptyArray();
+    });
+  }
+
+  test.each([[false], [true], [0], [{}], [() => {}], [undefined], [null], [NaN]])(
+    'fails when given type of %s which is not an array',
+    given => {
+      expect(() => expect(given).toBeEmptyArray()).toThrowErrorMatchingSnapshot();
+    },
+  );
+});
+
+describe('.not.toBeEmptyArray', () => {
+  test.each([[false], [true], [0], [{}], [() => {}], [undefined], [null], [NaN]])(
+    'passes when not given an empty array: %s',
+    given => {
+      expect(given).not.toBeEmptyArray();
+    },
+  );
+  {
+    test('fails when given an empty array', () => {
+      expect(() => expect([]).not.toBeEmptyArray()).toThrowErrorMatchingSnapshot();
+    });
+  }
+});

types/index.d.ts

@@ -511,6 +511,11 @@ declare namespace jest {
      */
     toBeArray(): R;
 
+    /**
+     * Use `.toBeEmptyArray` when checking if a value is an empty `Array`.
+     */
+    toBeEmptyArray(): R;
+
     /**
      * Use `.toBeArrayOfSize` when checking if a value is an `Array` of size x.
      * @param {Number} x

website/docs/matchers/array.mdx

@@ -14,6 +14,17 @@ Use `.toBeArray` when checking if a value is an `Array`.
 });`}
 </TestFile>
 
+### .toBeEmptyArray()
+
+Use `.toBeEmptyArray` when checking if a value is an empty `Array`.
+
+<TestFile name="toBeEmptyArray">
+  {`test('passes when value is an empty array', () => {
+  expect([]).toBeEmptyArray();
+  expect(['hello']).not.toBeEmptyArray();
+});`}
+</TestFile>
+
 ### .toBeArrayOfSize()
 
 Use `.toBeArrayOfSize` when checking if a value is an `Array` of size x.

website/docs/matchers/index.md

@@ -14,6 +14,7 @@ sidebar_position: 1
 ## [Array](/docs/matchers/array)
 
 - [.toBeArray()](/docs/matchers/array/#tobearray)
+- [.toBeEmptyArray()](/docs/matchers/array/#tobeemptyarray)
 - [.toBeArrayOfSize()](/docs/matchers/array/#tobearrayofsize)
 - [.toIncludeAllMembers([members])](/docs/matchers/array/#toincludeallmembersmembers)
 - [.toIncludeAllPartialMembers([members])](/docs/matchers/array/#toincludeallpartialmembersmembers)