diff --git a/README.md b/README.md index 9c1098c..348a105 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ - [Matchers](#matchers) - [`toBeDisabled`](#tobedisabled) - [`toBeEnabled`](#tobeenabled) - - [`toBeEmpty`](#tobeempty) + - [`toBeEmptyElement`](#tobeemptyelement) - [`toContainElement`](#tocontainelement) - [`toHaveProp`](#tohaveprop) - [`toHaveTextContent`](#tohavetextcontent) @@ -98,9 +98,9 @@ Alternatively, you can selectively import only the matchers you intend to use, a `expect` yourself: ```javascript -import { toBeEmpty, toHaveTextContent } from '@testing-library/jest-native'; +import { toBeEmptyElement, toHaveTextContent } from '@testing-library/jest-native'; -expect.extend({ toBeEmpty, toHaveTextContent }); +expect.extend({ toBeEmptyElement, toHaveTextContent }); ``` ## Matchers @@ -160,10 +160,10 @@ expect(getByTestId('button')).toBeEnabled(); expect(getByTestId('input')).toBeEnabled(); ``` -### `toBeEmpty` +### `toBeEmptyElement` ```javascript -toBeEmpty(); +toBeEmptyElement(); ``` Check that the given element has no content. @@ -173,9 +173,19 @@ Check that the given element has no content. ```javascript const { getByTestId } = render(); -expect(getByTestId('empty')).toBeEmpty(); +expect(getByTestId('empty')).toBeEmptyElement(); ``` +--- + +**NOTE** + +`toBeEmptyElement()` matcher has been renamed from `toBeEmpty()` because of the naming conflict with +Jest Extended export with the +[same name](https://github.com/jest-community/jest-extended#tobeempty). + +--- + ### `toContainElement` ```typescript diff --git a/extend-expect.d.ts b/extend-expect.d.ts index 0ae99d2..48731b0 100644 --- a/extend-expect.d.ts +++ b/extend-expect.d.ts @@ -6,11 +6,14 @@ declare global { interface Matchers { toBeDisabled(): R; toContainElement(element: ReactTestInstance | null): R; - toBeEmpty(): R; + toBeEmptyElement(): R; toHaveProp(attr: string, value?: any): R; toHaveTextContent(text: string | RegExp, options?: { normalizeWhitespace: boolean }): R; toBeEnabled(): R; toHaveStyle(style: object[] | object): R; + + /** @deprecated This function has been renamed to `toBeEmptyElement`. */ + toBeEmpty(): R; } } } diff --git a/src/__tests__/to-be-empty-element.js b/src/__tests__/to-be-empty-element.js new file mode 100644 index 0000000..036534d --- /dev/null +++ b/src/__tests__/to-be-empty-element.js @@ -0,0 +1,30 @@ +import React from 'react'; +import { View } from 'react-native'; +import { render } from '@testing-library/react-native'; + +test('.toBeEmptyElement', () => { + const { queryByTestId } = render( + + + , + ); + + const empty = queryByTestId('empty'); + const notEmpty = queryByTestId('not-empty'); + const nonExistantElement = queryByTestId('not-exists'); + const fakeElement = { thisIsNot: 'an html element' }; + + expect(empty).toBeEmptyElement(); + expect(notEmpty).not.toBeEmptyElement(); + + // negative test cases wrapped in throwError assertions for coverage. + expect(() => expect(empty).not.toBeEmptyElement()).toThrow(); + + expect(() => expect(notEmpty).toBeEmptyElement()).toThrow(); + + expect(() => expect(fakeElement).toBeEmptyElement()).toThrow(); + + expect(() => { + expect(nonExistantElement).toBeEmptyElement(); + }).toThrow(); +}); diff --git a/src/index.js b/src/index.js index e66f7d9..a9b96f1 100644 --- a/src/index.js +++ b/src/index.js @@ -1,5 +1,5 @@ import { toBeDisabled, toBeEnabled } from './to-be-disabled'; -import { toBeEmpty } from './to-be-empty'; +import { toBeEmptyElement, toBeEmpty } from './to-be-empty-element'; import { toHaveProp } from './to-have-prop'; import { toHaveTextContent } from './to-have-text-content'; import { toContainElement } from './to-contain-element'; @@ -8,7 +8,8 @@ import { toHaveStyle } from './to-have-style'; export { toBeDisabled, toContainElement, - toBeEmpty, + toBeEmptyElement, + toBeEmpty, // Deprecated toHaveProp, toHaveTextContent, toBeEnabled, diff --git a/src/to-be-empty-element.js b/src/to-be-empty-element.js new file mode 100644 index 0000000..024e14d --- /dev/null +++ b/src/to-be-empty-element.js @@ -0,0 +1,30 @@ +import { matcherHint } from 'jest-matcher-utils'; +import { checkReactElement, isEmpty, printDeprecationWarning, printElement } from './utils'; + +export function toBeEmptyElement(element) { + checkReactElement(element, toBeEmptyElement, this); + + return { + pass: isEmpty(element?.props?.children), + message: () => { + return [ + matcherHint(`${this.isNot ? '.not' : ''}.toBeEmpty`, 'element', ''), + '', + 'Received:', + printElement(element), + ].join('\n'); + }, + }; +} + +/** + * @deprecated This function has been renamed to `toBeEmptyElement`. + * + * */ +export function toBeEmpty(element) { + printDeprecationWarning( + 'toBeEmpty', + `"toBeEmpty()" matcher has been renamed to "toBeEmptyElement()". Old name will be deleted in future versions of @testing-library/jest-native.`, + ); + return toBeEmptyElement(element); +} diff --git a/src/to-be-empty.js b/src/to-be-empty.js deleted file mode 100644 index 773edf9..0000000 --- a/src/to-be-empty.js +++ /dev/null @@ -1,18 +0,0 @@ -import { matcherHint } from 'jest-matcher-utils'; -import { checkReactElement, isEmpty, printElement } from './utils'; - -export function toBeEmpty(element) { - checkReactElement(element, toBeEmpty, this); - - return { - pass: isEmpty(element?.props?.children), - message: () => { - return [ - matcherHint(`${this.isNot ? '.not' : ''}.toBeEmpty`, 'element', ''), - '', - 'Received:', - printElement(element), - ].join('\n'); - }, - }; -} diff --git a/src/utils.js b/src/utils.js index d2c9b8e..b8eb459 100644 --- a/src/utils.js +++ b/src/utils.js @@ -109,6 +109,18 @@ function isEmpty(value) { return false; } +const warned = {}; + +export function printDeprecationWarning(functionName, message) { + if (warned[functionName]) { + return; + } + + // eslint-disable-next-line no-console + console.warn(`Deprecation Warning:\n${message}`); + warned[functionName] = true; +} + export { ReactElementTypeError, checkReactElement,