feat: Deprecate toBeEmpty in favour of toBeEmptyDomElement (#216) (#254)

In order to prevent name clashes with jest-extended, the toBeEmpty will
have from now on a more specific name.

Co-authored-by: Daniela Valero <daniela.valero@publicissapient.com>

README.md

@@ -52,6 +52,7 @@ clear to read and to maintain.
   - [`toBeDisabled`](#tobedisabled)
   - [`toBeEnabled`](#tobeenabled)
   - [`toBeEmpty`](#tobeempty)
+  - [`toBeEmptyDOMElement`](#tobeemptydomelement)
   - [`toBeInTheDocument`](#tobeinthedocument)
   - [`toBeInvalid`](#tobeinvalid)
   - [`toBeRequired`](#toberequired)
@@ -207,6 +208,31 @@ expect(getByTestId('empty')).toBeEmpty()
 expect(getByTestId('not-empty')).not.toBeEmpty()
 ```
 
+> Note: This matcher is being deprecated due to a name clash with
+> `jest-extended`. See more info in #216. In the future, please use only:
+> [`toBeEmptyDOMElement`](#toBeEmptyDOMElement)
+
+<hr />
+
+### `toBeEmptyDOMElement`
+
+```typescript
+toBeEmptyDOMElement()
+```
+
+This allows you to assert whether an element has content or not.
+
+#### Examples
+
+```html
+<span data-testid="not-empty"><span data-testid="empty"></span></span>
+```
+
+```javascript
+expect(getByTestId('empty')).toBeEmptyDOMElement()
+expect(getByTestId('not-empty')).not.toBeEmptyDOMElement()
+```
+
 <hr />
 
 ### `toBeInTheDocument`
@@ -1135,6 +1161,7 @@ Thanks goes to these people ([emoji key][emojis]):
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.

src/__tests__/to-be-empty-dom-element.js

@@ -0,0 +1,32 @@
+import {render} from './helpers/test-utils'
+
+test('.toBeEmptyDOMElement', () => {
+  const {queryByTestId} = render(`
+    <span data-testid="not-empty">
+        <span data-testid="empty"></span>
+        <svg data-testid="svg-empty"></svg>
+    </span>`)
+
+  const empty = queryByTestId('empty')
+  const notEmpty = queryByTestId('not-empty')
+  const svgEmpty = queryByTestId('svg-empty')
+  const nonExistantElement = queryByTestId('not-exists')
+  const fakeElement = {thisIsNot: 'an html element'}
+
+  expect(empty).toBeEmptyDOMElement()
+  expect(svgEmpty).toBeEmptyDOMElement()
+  expect(notEmpty).not.toBeEmptyDOMElement()
+
+  // negative test cases wrapped in throwError assertions for coverage.
+  expect(() => expect(empty).not.toBeEmptyDOMElement()).toThrowError()
+
+  expect(() => expect(svgEmpty).not.toBeEmptyDOMElement()).toThrowError()
+
+  expect(() => expect(notEmpty).toBeEmptyDOMElement()).toThrowError()
+
+  expect(() => expect(fakeElement).toBeEmptyDOMElement()).toThrowError()
+
+  expect(() => {
+    expect(nonExistantElement).toBeEmptyDOMElement()
+  }).toThrowError()
+})

src/__tests__/to-be-empty.js

@@ -1,6 +1,8 @@
 import {render} from './helpers/test-utils'
 
 test('.toBeEmpty', () => {
+  // @deprecated intentionally hiding warnings for test clarity
+  const spy = jest.spyOn(console, 'warn').mockImplementation(() => {})
   const {queryByTestId} = render(`
     <span data-testid="not-empty">
         <span data-testid="empty"></span>
@@ -29,4 +31,5 @@ test('.toBeEmpty', () => {
   expect(() => {
     expect(nonExistantElement).toBeEmpty()
   }).toThrowError()
+  spy.mockRestore()
 })

src/matchers.js

@@ -1,6 +1,7 @@
 import {toBeInTheDOM} from './to-be-in-the-dom'
 import {toBeInTheDocument} from './to-be-in-the-document'
 import {toBeEmpty} from './to-be-empty'
+import {toBeEmptyDOMElement} from './to-be-empty-dom-element'
 import {toContainElement} from './to-contain-element'
 import {toContainHTML} from './to-contain-html'
 import {toHaveTextContent} from './to-have-text-content'
@@ -23,6 +24,7 @@ export {
   toBeInTheDOM,
   toBeInTheDocument,
   toBeEmpty,
+  toBeEmptyDOMElement,
   toContainElement,
   toContainHTML,
   toHaveTextContent,

src/to-be-empty-dom-element.js

@@ -0,0 +1,22 @@
+import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {checkHtmlElement} from './utils'
+
+export function toBeEmptyDOMElement(element) {
+  checkHtmlElement(element, toBeEmptyDOMElement, this)
+
+  return {
+    pass: element.innerHTML === '',
+    message: () => {
+      return [
+        matcherHint(
+          `${this.isNot ? '.not' : ''}.toBeEmptyDOMElement`,
+          'element',
+          '',
+        ),
+        '',
+        'Received:',
+        `  ${printReceived(element.innerHTML)}`,
+      ].join('\n')
+    },
+  }
+}

src/to-be-empty.js

@@ -1,7 +1,11 @@
 import {matcherHint, printReceived} from 'jest-matcher-utils'
-import {checkHtmlElement} from './utils'
+import {checkHtmlElement, deprecate} from './utils'
 
 export function toBeEmpty(element) {
+  deprecate(
+    'toBeEmpty',
+    'Please use instead toBeEmptyDOMElement for finding empty nodes in the DOM.',
+  )
   checkHtmlElement(element, toBeEmpty, this)
 
   return {