feat: Depreciate toBeInTheDOM with replacement

extend-expect.d.ts

@@ -1,6 +1,10 @@
 declare namespace jest {
   interface Matchers<R> {
+    /**
+     * @deprecated
+     */
     toBeInTheDOM(container?: HTMLElement | SVGElement): R
+    toBeInTheDocument(): R
     toBeVisible(): R
     toBeEmpty(): R
     toBeDisabled(): R

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

@@ -0,0 +1,20 @@
+test('.toBeInTheDocument', () => {
+  document.body.innerHTML = `
+    <span data-testid="html-element"><span>Html Element</span></span>
+    <svg data-testid="svg-element"></svg>`
+
+  const htmlElement = document.querySelector('[data-testid="html-element"]')
+  const svgElement = document.querySelector('[data-testid="html-element"]')
+  const detachedElement = document.createElement('div')
+  const fakeElement = {thisIsNot: 'an html element'}
+
+  expect(htmlElement).toBeInTheDocument()
+  expect(svgElement).toBeInTheDocument()
+  expect(detachedElement).not.toBeInTheDocument()
+
+  // negative test cases wrapped in throwError assertions for coverage.
+  expect(() => expect(htmlElement).not.toBeInTheDocument()).toThrowError()
+  expect(() => expect(svgElement).not.toBeInTheDocument()).toThrowError()
+  expect(() => expect(detachedElement).toBeInTheDocument()).toThrowError()
+  expect(() => expect(fakeElement).toBeInTheDocument()).toThrowError()
+})

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

@@ -1,6 +1,9 @@
 import {render} from './helpers/test-utils'
 
 test('.toBeInTheDOM', () => {
+  // @deprecated intentionally hiding warnings for test clarity
+  const spy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+
   const {queryByTestId} = render(`
     <span data-testid="count-container">
       <span data-testid="count-value"></span>
@@ -51,4 +54,6 @@ test('.toBeInTheDOM', () => {
   expect(() => {
     expect(valueElement).toBeInTheDOM(fakeElement)
   }).toThrowError()
+
+  spy.mockRestore()
 })

src/__tests__/utils.js

@@ -0,0 +1,15 @@
+import {deprecate, getDepreciationMessage} from '../utils'
+
+test('deprecate', () => {
+  const spy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+
+  const messageWithReplacement = getDepreciationMessage('test', 'test')
+  deprecate('test', 'test')
+  expect(spy).toHaveBeenCalledWith(messageWithReplacement)
+
+  const messageWithoutReplacement = getDepreciationMessage('test')
+  deprecate('test')
+  expect(spy).toHaveBeenCalledWith(messageWithoutReplacement)
+
+  spy.mockRestore()
+})

src/index.js

@@ -1,4 +1,5 @@
 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 {toHaveTextContent} from './to-have-text-content'
@@ -11,6 +12,7 @@ import {toBeDisabled} from './to-be-disabled'
 
 export {
   toBeInTheDOM,
+  toBeInTheDocument,
   toBeEmpty,
   toContainElement,
   toHaveTextContent,

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

@@ -0,0 +1,24 @@
+import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {checkHtmlElement} from './utils'
+
+export function toBeInTheDocument(element) {
+  checkHtmlElement(element, toBeInTheDocument, this)
+
+  return {
+    pass: document.documentElement.contains(element),
+    message: () => {
+      return [
+        matcherHint(
+          `${this.isNot ? '.not' : ''}.toBeInTheDocument`,
+          'element',
+          '',
+        ),
+        '',
+        'Received:',
+        `  ${printReceived(
+          element.hasChildNodes() ? element.cloneNode(false) : element,
+        )}`,
+      ].join('\n')
+    },
+  }
+}

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

@@ -1,7 +1,12 @@
 import {matcherHint, printReceived} from 'jest-matcher-utils'
-import {checkHtmlElement} from './utils'
+import {checkHtmlElement, deprecate} from './utils'
 
 export function toBeInTheDOM(element, container) {
+  deprecate(
+    'toBeInTheDOM',
+    'Please use toBeInTheDocument for searching the entire document and toContainElement for searching a specific container.',
+  )
+
   if (element) {
     checkHtmlElement(element, toBeInTheDOM, this)
   }

src/utils.js

@@ -66,4 +66,29 @@ function matches(textToMatch, node, matcher) {
   }
 }
 
-export {checkHtmlElement, getMessage, matches}
+function deprecate(name, replacementText) {
+  const message = getDepreciationMessage(name, replacementText)
+
+  // Notify user that they are using deprecated functionality.
+  // eslint-disable-next-line no-console
+  console.warn(message)
+}
+
+function getDepreciationMessage(name, replacementText) {
+  return [
+    'Warning:',
+    name,
+    'has been deprecated and will be removed in future updates.',
+    replacementText,
+  ]
+    .join(' ')
+    .trim()
+}
+
+export {
+  checkHtmlElement,
+  getMessage,
+  matches,
+  deprecate,
+  getDepreciationMessage,
+}