feat: toBeInTheDocument and toContainElement accept element to be null (#47)

In both cases, `null` is not considered to be contained in the provided context (the container or document) so these matchers will pass or not accordingly. And in the case of toCointainElement, the container is still required not to be null or undefined.

Author: smacpherson64

README.md

@@ -136,11 +136,13 @@ import 'jest-dom/extend-expect'
 
 // const htmlElement = document.querySelector('[data-testid="html-element"]')
 // const svgElement = document.querySelector('[data-testid="svg-element"]')
+// const nonExistantElement = document.querySelector('does-not-exist')
 // const detachedElement = document.createElement('div')
 
 expect(htmlElement).toBeInTheDocument()
 expect(svgElement).toBeInTheDocument()
 expect(detacthedElement).not.toBeInTheDocument()
+expect(nonExistantElement).not.toBeInTheDocument()
 // ...
 ```
 
@@ -149,7 +151,7 @@ expect(detacthedElement).not.toBeInTheDocument()
 ### `toContainElement`
 
 ```typescript
-toContainElement(element: HTMLElement | SVGElement)
+toContainElement(element: HTMLElement | SVGElement | null)
 ```
 
 This allows you to assert whether an element contains another element as a descendant or not.
@@ -162,9 +164,11 @@ import 'jest-dom/extend-expect'
 // <span data-testid="ancestor"><span data-testid="descendant"></span></span>
 const ancestor = queryByTestId(container, 'ancestor')
 const descendant = queryByTestId(container, 'descendant')
+const nonExistantElement = queryByTestId(container, 'does-not-exist')
 
 expect(ancestor).toContainElement(descendant)
 expect(descendant).not.toContainElement(ancestor)
+expect(ancestor).not.toContainElement(nonExistantElement)
 // ...
 ```
 

extend-expect.d.ts

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

src/__tests__/to-be-in-the-document.js

@@ -13,6 +13,7 @@ test('.toBeInTheDocument', () => {
   expect(htmlElement).toBeInTheDocument()
   expect(svgElement).toBeInTheDocument()
   expect(detachedElement).not.toBeInTheDocument()
+  expect(nullElement).not.toBeInTheDocument()
 
   // negative test cases wrapped in throwError assertions for coverage.
   expect(() => expect(htmlElement).not.toBeInTheDocument()).toThrowError()

src/__tests__/to-contain-element.js

@@ -1,22 +1,22 @@
 import {render} from './helpers/test-utils'
 
-test('.toContainElement', () => {
-  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 {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 svgElement = queryByTestId('svg-element')
-  const nonExistantElement = queryByTestId('not-exists')
-  const fakeElement = {thisIsNot: 'an html element'}
+const grandparent = queryByTestId('grandparent')
+const parent = queryByTestId('parent')
+const child = queryByTestId('child')
+const svgElement = queryByTestId('svg-element')
+const nonExistantElement = queryByTestId('not-exists')
+const fakeElement = {thisIsNot: 'an html element'}
 
+test('.toContainElement positive test cases', () => {
   expect(grandparent).toContainElement(parent)
   expect(grandparent).toContainElement(child)
   expect(grandparent).toContainElement(svgElement)
@@ -26,8 +26,10 @@ test('.toContainElement', () => {
   expect(child).not.toContainElement(parent)
   expect(child).not.toContainElement(grandparent)
   expect(child).not.toContainElement(svgElement)
+  expect(grandparent).not.toContainElement(nonExistantElement)
+})
 
-  // negative test cases wrapped in throwError assertions for coverage.
+test('.toContainElement negative test cases', () => {
   expect(() =>
     expect(nonExistantElement).not.toContainElement(child),
   ).toThrowError()
@@ -55,6 +57,9 @@ test('.toContainElement', () => {
   expect(() => expect(fakeElement).toContainElement(fakeElement)).toThrowError()
   expect(() => expect(grandparent).not.toContainElement(child)).toThrowError()
   expect(() =>
-    expect(grandparent).not.toContainElement(svgElement),
+    expect(grandparent).not.toContainElement(svgElement)
+  ).toThrowError()
+  expect(() =>
+      expect(grandparent).not.toContainElement(undefined)
   ).toThrowError()
 })

src/to-be-in-the-document.js

@@ -1,8 +1,15 @@
-import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {
+  matcherHint,
+  stringify,
+  RECEIVED_COLOR as receivedColor,
+} from 'jest-matcher-utils'
 import {checkHtmlElement, checkDocumentKey} from './utils'
 
 export function toBeInTheDocument(element) {
-  checkHtmlElement(element, toBeInTheDocument, this)
+  if (element !== null) {
+    checkHtmlElement(element, toBeInTheDocument, this)
+  }
+
   checkDocumentKey(global.document, 'documentElement', toBeInTheDocument)
 
   return {
@@ -15,10 +22,12 @@ export function toBeInTheDocument(element) {
           '',
         ),
         '',
-        'Received:',
-        `  ${printReceived(
-          element.hasChildNodes() ? element.cloneNode(false) : element,
-        )}`,
+        receivedColor(`${stringify(
+          document.documentElement.cloneNode(false),
+        )} ${this.isNot ? 'contains:' : 'does not contain:'} ${stringify(
+          element ? element.cloneNode(false) : element,
+        )}
+        `),
       ].join('\n')
     },
   }

src/to-contain-element.js

@@ -1,9 +1,16 @@
-import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {
+  matcherHint,
+  stringify,
+  RECEIVED_COLOR as receivedColor,
+} from 'jest-matcher-utils'
 import {checkHtmlElement} from './utils'
 
 export function toContainElement(container, element) {
   checkHtmlElement(container, toContainElement, this)
-  checkHtmlElement(element, toContainElement, this)
+
+  if (element !== null) {
+    checkHtmlElement(element, toContainElement, this)
+  }
 
   return {
     pass: container.contains(element),
@@ -12,11 +19,13 @@ export function toContainElement(container, element) {
         matcherHint(
           `${this.isNot ? '.not' : ''}.toContainElement`,
           'element',
-          '',
+          'element',
         ),
         '',
-        'Received:',
-        `  ${printReceived(container.cloneNode(false))}`,
+        receivedColor(`${stringify(container.cloneNode(false))} ${
+          this.isNot ? 'contains:' : 'does not contain:'
+        } ${stringify(element ? element.cloneNode(false) : element)}
+        `),
       ].join('\n')
     },
   }