refactor: add toBeEmptyElement assertion (#111)

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(<View testID="empty" />);
 
-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

extend-expect.d.ts

@@ -6,11 +6,14 @@ declare global {
     interface Matchers<R, T> {
       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;
     }
   }
 }

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(
+    <View testID="not-empty">
+      <View testID="empty" />
+    </View>,
+  );
+
+  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();
+});

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,

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);
+}

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,