diff --git a/.changeset/spotty-plums-thank.md b/.changeset/spotty-plums-thank.md new file mode 100644 index 00000000..f62b6f60 --- /dev/null +++ b/.changeset/spotty-plums-thank.md @@ -0,0 +1,5 @@ +--- +'jest-extended': minor +--- + +Introduce new matcher `toBeEmptyArray` diff --git a/src/matchers/index.ts b/src/matchers/index.ts index 064008b2..d0872570 100644 --- a/src/matchers/index.ts +++ b/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'; diff --git a/src/matchers/toBeEmptyArray.ts b/src/matchers/toBeEmptyArray.ts new file mode 100644 index 00000000..2a54b455 --- /dev/null +++ b/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)}`, + }; +} diff --git a/test/matchers/__snapshots__/toBeEmptyArray.test.ts.snap b/test/matchers/__snapshots__/toBeEmptyArray.test.ts.snap new file mode 100644 index 00000000..ff63568f --- /dev/null +++ b/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`] = ` +"expect(received).not.toBeEmptyArray() + +Expected value to not be an empty array, received: + []" +`; + +exports[`.toBeEmptyArray fails when given type of () => { } which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + [Function anonymous]" +`; + +exports[`.toBeEmptyArray fails when given type of {} which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + {}" +`; + +exports[`.toBeEmptyArray fails when given type of 0 which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + 0" +`; + +exports[`.toBeEmptyArray fails when given type of NaN which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + NaN" +`; + +exports[`.toBeEmptyArray fails when given type of false which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + false" +`; + +exports[`.toBeEmptyArray fails when given type of null which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + null" +`; + +exports[`.toBeEmptyArray fails when given type of true which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + true" +`; + +exports[`.toBeEmptyArray fails when given type of undefined which is not an array 1`] = ` +"expect(received).toBeEmptyArray() + +Expected value to be an empty array, received: + undefined" +`; diff --git a/test/matchers/toBeEmptyArray.test.ts b/test/matchers/toBeEmptyArray.test.ts new file mode 100644 index 00000000..88568047 --- /dev/null +++ b/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(); + }); + } +}); diff --git a/types/index.d.ts b/types/index.d.ts index e4c4c49c..cd44234f 100644 --- a/types/index.d.ts +++ b/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 diff --git a/website/docs/matchers/array.mdx b/website/docs/matchers/array.mdx index 8242c587..5f89764d 100644 --- a/website/docs/matchers/array.mdx +++ b/website/docs/matchers/array.mdx @@ -14,6 +14,17 @@ Use `.toBeArray` when checking if a value is an `Array`. });`} +### .toBeEmptyArray() + +Use `.toBeEmptyArray` when checking if a value is an empty `Array`. + + + {`test('passes when value is an empty array', () => { + expect([]).toBeEmptyArray(); + expect(['hello']).not.toBeEmptyArray(); +});`} + + ### .toBeArrayOfSize() Use `.toBeArrayOfSize` when checking if a value is an `Array` of size x. diff --git a/website/docs/matchers/index.md b/website/docs/matchers/index.md index f5c95166..b8e85ca3 100644 --- a/website/docs/matchers/index.md +++ b/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)