feat: Add toBeEmpty (#26)

* #8: Added test for toBeEmpty matcher

* #8: Added toBeEmpty matcher

* #8: Added documentation for toBeEmpty matcher

* #8: Updated types for toBeEmpty matcher

* Added user as contributor

Author: smacpherson64

.all-contributorsrc

@@ -147,6 +147,17 @@
         "bug",
         "code"
       ]
+    },
+    {
+      "login": "smacpherson64",
+      "name": "smacpherson64",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/1659099?v=4",
+      "profile": "https://github.com/smacpherson64",
+      "contributions": [
+        "code",
+        "doc",
+        "test"
+      ]
     }
   ]
 }

README.md

@@ -16,7 +16,7 @@
 [![downloads][downloads-badge]][npmtrends]
 [![MIT License][license-badge]][license]
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-15-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs]
 [![Code of Conduct][coc-badge]][coc]
 
@@ -112,6 +112,21 @@ expect(queryByTestId(container, 'count-value1')).not.toBeInTheDOM()
 > (like `queryByTestId`) rather than a get function (like `getByTestId`).
 > Otherwise the `get*` function could throw an error before your assertion.
 
+### `toBeEmpty`
+
+This allows you to assert whether an element has content or not.
+
+```javascript
+// add the custom expect matchers once
+import 'jest-dom/extend-expect'
+
+// ...
+// <span data-testid="not-empty"><span data-testid="empty"></span></span>
+expect(queryByTestId(container, 'empty')).toBeEmpty()
+expect(queryByTestId(container, 'not-empty')).not.toBeEmpty()
+// ...
+```
+
 ### `toHaveTextContent`
 
 This API allows you to check whether the given element has a text content or not.
@@ -265,7 +280,7 @@ Thanks goes to these people ([emoji key][emojis]):
 | [<img src="https://avatars.githubusercontent.com/u/1500684?v=3" width="100px;"/><br /><sub><b>Kent C. Dodds</b></sub>](https://kentcdodds.com)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=kentcdodds "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=kentcdodds "Documentation") [🚇](#infra-kentcdodds "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/gnapse/jest-dom/commits?author=kentcdodds "Tests") | [<img src="https://avatars1.githubusercontent.com/u/2430381?v=4" width="100px;"/><br /><sub><b>Ryan Castner</b></sub>](http://audiolion.github.io)<br />[📖](https://github.com/gnapse/jest-dom/commits?author=audiolion "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/8008023?v=4" width="100px;"/><br /><sub><b>Daniel Sandiego</b></sub>](https://www.dnlsandiego.com)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=dnlsandiego "Code") | [<img src="https://avatars2.githubusercontent.com/u/12592677?v=4" width="100px;"/><br /><sub><b>Paweł Mikołajczyk</b></sub>](https://github.com/Miklet)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=Miklet "Code") | [<img src="https://avatars3.githubusercontent.com/u/464978?v=4" width="100px;"/><br /><sub><b>Alejandro Ñáñez Ortiz</b></sub>](http://co.linkedin.com/in/alejandronanez/)<br />[📖](https://github.com/gnapse/jest-dom/commits?author=alejandronanez "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/1402095?v=4" width="100px;"/><br /><sub><b>Matt Parrish</b></sub>](https://github.com/pbomb)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Apbomb "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=pbomb "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=pbomb "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=pbomb "Tests") | [<img src="https://avatars1.githubusercontent.com/u/1288694?v=4" width="100px;"/><br /><sub><b>Justin Hall</b></sub>](https://github.com/wKovacs64)<br />[📦](#platform-wKovacs64 "Packaging/porting to new platform") |
 | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
 | [<img src="https://avatars1.githubusercontent.com/u/1241511?s=460&v=4" width="100px;"/><br /><sub><b>Anto Aravinth</b></sub>](https://github.com/antoaravinth)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=antoaravinth "Code") [⚠️](https://github.com/gnapse/jest-dom/commits?author=antoaravinth "Tests") [📖](https://github.com/gnapse/jest-dom/commits?author=antoaravinth "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/3462296?v=4" width="100px;"/><br /><sub><b>Jonah Moses</b></sub>](https://github.com/JonahMoses)<br />[📖](https://github.com/gnapse/jest-dom/commits?author=JonahMoses "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/4002543?v=4" width="100px;"/><br /><sub><b>Łukasz Gandecki</b></sub>](http://team.thebrain.pro)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=lgandecki "Code") [⚠️](https://github.com/gnapse/jest-dom/commits?author=lgandecki "Tests") [📖](https://github.com/gnapse/jest-dom/commits?author=lgandecki "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/498274?v=4" width="100px;"/><br /><sub><b>Ivan Babak</b></sub>](https://sompylasar.github.io)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Asompylasar "Bug reports") [🤔](#ideas-sompylasar "Ideas, Planning, & Feedback") | [<img src="https://avatars3.githubusercontent.com/u/4439618?v=4" width="100px;"/><br /><sub><b>Jesse Day</b></sub>](https://github.com/jday3)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=jday3 "Code") | [<img src="https://avatars0.githubusercontent.com/u/15199?v=4" width="100px;"/><br /><sub><b>Ernesto García</b></sub>](http://gnapse.github.io)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=gnapse "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=gnapse "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=gnapse "Tests") | [<img src="https://avatars0.githubusercontent.com/u/79312?v=4" width="100px;"/><br /><sub><b>Mark Volkmann</b></sub>](http://ociweb.com/mark/)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Amvolkmann "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=mvolkmann "Code") |
-
+| [<img src="https://avatars1.githubusercontent.com/u/1659099?v=4" width="100px;"/><br /><sub><b>smacpherson64</b></sub>](https://github.com/smacpherson64)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Tests") |
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.

extend-expect.d.ts

@@ -5,6 +5,7 @@ declare namespace jest {
     toHaveClass: (className: string) => R
     toBeInTheDOM: () => R
     toBeVisible: () => R
+    toBeEmpty: () => R
     toHaveStyle: (css: string) => R
   }
 }

src/__tests__/index.js

@@ -22,6 +22,32 @@ test('.toBeInTheDOM', () => {
   ).toThrowError()
 })
 
+test('.toBeEmpty', () => {
+  const {queryByTestId} = render(`
+    <span data-testid="not-empty">
+        <span data-testid="empty"></span>
+    </span>`)
+
+  const empty = queryByTestId('empty')
+  const notEmpty = queryByTestId('not-empty')
+  const nonExistantElement = queryByTestId('not-exists')
+  const fakeElement = {thisIsNot: 'an html element'}
+
+  expect(empty).toBeEmpty()
+  expect(notEmpty).not.toBeEmpty()
+
+  // negative test cases wrapped in throwError assertions for coverage.
+  expect(() => expect(empty).not.toBeEmpty()).toThrowError()
+
+  expect(() => expect(notEmpty).toBeEmpty()).toThrowError()
+
+  expect(() => expect(fakeElement).toBeEmpty()).toThrowError()
+
+  expect(() => {
+    expect(nonExistantElement).toBeEmpty()
+  }).toThrowError()
+})
+
 test('.toHaveTextContent', () => {
   const {queryByTestId} = render(`<span data-testid="count-value">2</span>`)
 

src/index.js

@@ -1,4 +1,5 @@
 import {toBeInTheDOM} from './to-be-in-the-dom'
+import {toBeEmpty} from './to-be-empty'
 import {toHaveTextContent} from './to-have-text-content'
 import {toHaveAttribute} from './to-have-attribute'
 import {toHaveClass} from './to-have-class'
@@ -7,6 +8,7 @@ import {toBeVisible} from './to-be-visible'
 
 export {
   toBeInTheDOM,
+  toBeEmpty,
   toHaveTextContent,
   toHaveAttribute,
   toHaveClass,

src/to-be-empty.js

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