diff --git a/README.md b/README.md
index 7cc3ba59..23487979 100644
--- a/README.md
+++ b/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)
+
+
+
+### `toBeEmptyDOMElement`
+
+```typescript
+toBeEmptyDOMElement()
+```
+
+This allows you to assert whether an element has content or not.
+
+#### Examples
+
+```html
+
+```
+
+```javascript
+expect(getByTestId('empty')).toBeEmptyDOMElement()
+expect(getByTestId('not-empty')).not.toBeEmptyDOMElement()
+```
+
### `toBeInTheDocument`
@@ -1135,6 +1161,7 @@ Thanks goes to these people ([emoji key][emojis]):
+
This project follows the [all-contributors][all-contributors] specification.
diff --git a/src/__tests__/to-be-empty-dom-element.js b/src/__tests__/to-be-empty-dom-element.js
new file mode 100644
index 00000000..f0ff2877
--- /dev/null
+++ b/src/__tests__/to-be-empty-dom-element.js
@@ -0,0 +1,32 @@
+import {render} from './helpers/test-utils'
+
+test('.toBeEmptyDOMElement', () => {
+ const {queryByTestId} = render(`
+
+
+
+ `)
+
+ 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()
+})
diff --git a/src/__tests__/to-be-empty.js b/src/__tests__/to-be-empty.js
index 74960ca6..d0096164 100644
--- a/src/__tests__/to-be-empty.js
+++ b/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(`
@@ -29,4 +31,5 @@ test('.toBeEmpty', () => {
expect(() => {
expect(nonExistantElement).toBeEmpty()
}).toThrowError()
+ spy.mockRestore()
})
diff --git a/src/matchers.js b/src/matchers.js
index b9b500d3..36896d07 100644
--- a/src/matchers.js
+++ b/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,
diff --git a/src/to-be-empty-dom-element.js b/src/to-be-empty-dom-element.js
new file mode 100644
index 00000000..7743cdfa
--- /dev/null
+++ b/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')
+ },
+ }
+}
diff --git a/src/to-be-empty.js b/src/to-be-empty.js
index 6a033592..9985376d 100644
--- a/src/to-be-empty.js
+++ b/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 {