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,