feat: add new matcher toContainHTML (#42)

Author: 6ewis

.all-contributorsrc

@@ -179,6 +179,15 @@
         "doc",
         "test"
       ]
+    },
+    {
+      "login": "6ewis",
+      "name": "Lewis",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/840609?v=4",
+      "profile": "https://github.com/6ewis",
+      "contributions": [
+        "code"
+      ]
     }
   ]
 }

README.md

@@ -16,7 +16,7 @@
 [![downloads][downloads-badge]][npmtrends]
 [![MIT License][license-badge]][license]
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-17-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-18-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs]
 [![Code of Conduct][coc-badge]][coc]
 
@@ -48,6 +48,7 @@ to maintain.
   - [`toBeEmpty`](#tobeempty)
   - [`toBeInTheDocument`](#tobeinthedocument)
   - [`toContainElement`](#tocontainelement)
+  - [`toContainHTML`](#tocontainhtml)
   - [`toHaveTextContent`](#tohavetextcontent)
   - [`toHaveAttribute`](#tohaveattribute)
   - [`toHaveClass`](#tohaveclass)
@@ -167,6 +168,31 @@ expect(descendant).not.toContainElement(ancestor)
 // ...
 ```
 
+### `toContainHTML`
+
+```typescript
+toContainHTML(htmlText: string)
+```
+
+Assert whether a string representing a HTML element is contained in another element:
+
+```javascript
+// add the custom expect matchers once
+import 'jest-dom/extend-expect'
+
+// ...
+// <span data-testid="parent"><span data-testid="child"></span></span>
+const parent = queryByTestId('parent')
+expect(parentElement).toContainHTML('<span data-testid="child"></span>')
+// ...
+```
+
+> Chances are you probably do not need to use this matcher. We encourage testing from the perspective of how the user perceives the app in a browser. That's why testing against a specific DOM structure is not advised.
+>
+> It could be useful in situations where the code being tested renders html that was obtained from an external source, and you want to validate that that html code was used as intended.
+>
+> It should not be used to check DOM structure that you control. Please use [`toContainElement`](#tocontainelement) instead.
+
 ### `toHaveTextContent`
 
 ```typescript
@@ -401,7 +427,7 @@ value is indeed an `HTMLElement` you can always use some of
 
 ```js
 expect(document.querySelector('.ok-button')).toBeInstanceOf(HTMLElement)
-expect(document.querySelector('.cancel-button')).toBeThruthy();
+expect(document.querySelector('.cancel-button')).toBeThruthy()
 ```
 
 > Note: The differences between `toBeInTheDOM` and `toBeInTheDocument` are
@@ -448,7 +474,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") | [<img src="https://avatars2.githubusercontent.com/u/132233?v=4" width="100px;"/><br /><sub><b>John Gozde</b></sub>](https://github.com/jgoz)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Ajgoz "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=jgoz "Code") | [<img src="https://avatars2.githubusercontent.com/u/7830590?v=4" width="100px;"/><br /><sub><b>Iwona</b></sub>](https://github.com/callada)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=callada "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=callada "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=callada "Tests") |
+| [<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") | [<img src="https://avatars2.githubusercontent.com/u/132233?v=4" width="100px;"/><br /><sub><b>John Gozde</b></sub>](https://github.com/jgoz)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Ajgoz "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=jgoz "Code") | [<img src="https://avatars2.githubusercontent.com/u/7830590?v=4" width="100px;"/><br /><sub><b>Iwona</b></sub>](https://github.com/callada)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=callada "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=callada "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=callada "Tests") | [<img src="https://avatars0.githubusercontent.com/u/840609?v=4" width="100px;"/><br /><sub><b>Lewis</b></sub>](https://github.com/6ewis)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=6ewis "Code") |
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 

extend-expect.d.ts

@@ -9,6 +9,7 @@ declare namespace jest {
     toBeEmpty(): R
     toBeDisabled(): R
     toContainElement(element: HTMLElement | SVGElement): R
+    toContainHTML(htmlText: string): R
     toHaveAttribute(attr: string, value?: string): R
     toHaveClass(...classNames: string[]): R
     toHaveStyle(css: string): R

src/__tests__/to-contain-html.js

@@ -0,0 +1,79 @@
+import {render} from './helpers/test-utils'
+
+/* eslint-disable max-statements */
+test('.toContainHTML', () => {
+  const {queryByTestId} = render(`
+    <span data-testid="grandparent">
+      <span data-testid="parent">
+        <span data-testid="child"></span>
+      </span>
+      <svg data-testid="svg-element"></svg>
+    </span>
+    `)
+
+  const grandparent = queryByTestId('grandparent')
+  const parent = queryByTestId('parent')
+  const child = queryByTestId('child')
+  const nonExistantElement = queryByTestId('not-exists')
+  const fakeElement = {thisIsNot: 'an html element'}
+  const stringChildElement = '<span data-testid="child"></span>'
+  const incorrectStringHtml = '<span data-testid="child"></div>'
+  const nonExistantString = '<span> Does not exists </span>'
+  const svgElement = queryByTestId('svg-element')
+
+  expect(grandparent).toContainHTML(stringChildElement)
+  expect(parent).toContainHTML(stringChildElement)
+  expect(child).toContainHTML(stringChildElement)
+  expect(grandparent).not.toContainHTML(nonExistantString)
+  expect(parent).not.toContainHTML(nonExistantString)
+  expect(child).not.toContainHTML(nonExistantString)
+  expect(child).not.toContainHTML(nonExistantString)
+  expect(grandparent).not.toContainHTML(incorrectStringHtml)
+  expect(parent).not.toContainHTML(incorrectStringHtml)
+  expect(child).not.toContainHTML(incorrectStringHtml)
+  expect(child).not.toContainHTML(incorrectStringHtml)
+
+  // negative test cases wrapped in throwError assertions for coverage.
+  expect(() =>
+    expect(nonExistantElement).not.toContainHTML(stringChildElement),
+  ).toThrowError()
+  expect(() =>
+    expect(nonExistantElement).not.toContainHTML(nonExistantElement),
+  ).toThrowError()
+  expect(() =>
+    expect(stringChildElement).not.toContainHTML(fakeElement),
+  ).toThrowError()
+  expect(() =>
+    expect(svgElement).toContainHTML(stringChildElement),
+  ).toThrowError()
+  expect(() =>
+    expect(grandparent).not.toContainHTML(stringChildElement),
+  ).toThrowError()
+  expect(() =>
+    expect(parent).not.toContainHTML(stringChildElement),
+  ).toThrowError()
+  expect(() =>
+    expect(child).not.toContainHTML(stringChildElement),
+  ).toThrowError()
+  expect(() =>
+    expect(child).not.toContainHTML(stringChildElement),
+  ).toThrowError()
+  expect(() => expect(child).toContainHTML(nonExistantString)).toThrowError()
+  expect(() => expect(parent).toContainHTML(nonExistantString)).toThrowError()
+  expect(() =>
+    expect(grandparent).toContainHTML(nonExistantString),
+  ).toThrowError()
+  expect(() => expect(child).toContainHTML(nonExistantElement)).toThrowError()
+  expect(() => expect(parent).toContainHTML(nonExistantElement)).toThrowError()
+  expect(() =>
+    expect(grandparent).toContainHTML(nonExistantElement),
+  ).toThrowError()
+  expect(() =>
+    expect(nonExistantElement).toContainHTML(incorrectStringHtml),
+  ).toThrowError()
+  expect(() =>
+    expect(grandparent).toContainHTML(incorrectStringHtml),
+  ).toThrowError()
+  expect(() => expect(child).toContainHTML(incorrectStringHtml)).toThrowError()
+  expect(() => expect(parent).toContainHTML(incorrectStringHtml)).toThrowError()
+})

src/index.js

@@ -2,6 +2,7 @@ import {toBeInTheDOM} from './to-be-in-the-dom'
 import {toBeInTheDocument} from './to-be-in-the-document'
 import {toBeEmpty} from './to-be-empty'
 import {toContainElement} from './to-contain-element'
+import {toContainHTML} from './to-contain-html'
 import {toHaveTextContent} from './to-have-text-content'
 import {toHaveAttribute} from './to-have-attribute'
 import {toHaveClass} from './to-have-class'
@@ -15,6 +16,7 @@ export {
   toBeInTheDocument,
   toBeEmpty,
   toContainElement,
+  toContainHTML,
   toHaveTextContent,
   toHaveAttribute,
   toHaveClass,

src/to-contain-html.js

@@ -0,0 +1,27 @@
+import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {checkHtmlElement} from './utils'
+
+function checkHtmlText(htmlText, ...args) {
+  const htmlElement =
+    typeof htmlText === 'string'
+      ? new DOMParser().parseFromString(htmlText, 'text/html').body.firstChild
+      : null
+  checkHtmlElement(htmlElement, ...args)
+}
+
+export function toContainHTML(container, htmlText) {
+  checkHtmlElement(container, toContainHTML, this)
+  checkHtmlText(htmlText, toContainHTML, this)
+
+  return {
+    pass: container.outerHTML.includes(htmlText),
+    message: () => {
+      return [
+        matcherHint(`${this.isNot ? '.not' : ''}.toContainHTML`, 'element', ''),
+        '',
+        'Received:',
+        `  ${printReceived(container.cloneNode(false))}`,
+      ].join('\n')
+    },
+  }
+}