feat: add isInstanceOfElement helper

src/__tests__/helpers.js

@@ -3,7 +3,9 @@ import {
  getWindowFromNode,
  checkContainerType,
  runWithRealTimers,
+ isInstanceOfElement,
 } from '../helpers'
+import {render} from './helpers/test-utils'
 
 const globalObj = typeof window === 'undefined' ? global : window
 
@@ -53,6 +55,90 @@ describe('query container validation throws when validation fails', () => {
  })
 })
 
+describe('check element type per isInstanceOfElement', () => {
+ let defaultViewDescriptor, spanDescriptor
+ beforeAll(() => {
+ defaultViewDescriptor = Object.getOwnPropertyDescriptor(
+ Object.getPrototypeOf(global.document),
+ 'defaultView',
+ )
+ spanDescriptor = Object.getOwnPropertyDescriptor(
+ global.window,
+ 'HTMLSpanElement',
+ )
+ })
+ afterEach(() => {
+ Object.defineProperty(
+ Object.getPrototypeOf(global.document),
+ 'defaultView',
+ defaultViewDescriptor,
+ )
+ Object.defineProperty(global.window, 'HTMLSpanElement', spanDescriptor)
+ })
+
+ test('check in regular jest environment', () => {
+ const {container} = render(`<span></span>`)
+
+ expect(container.firstChild.ownerDocument.defaultView).toEqual(
+ expect.objectContaining({
+ HTMLSpanElement: expect.any(Function),
+ }),
+ )
+
+ expect(isInstanceOfElement(container.firstChild, 'HTMLSpanElement')).toBe(
+ true,
+ )
+ expect(isInstanceOfElement(container.firstChild, 'HTMLDivElement')).toBe(
+ false,
+ )
+ })
+
+ test('check in detached document', () => {
+ const {container} = render(`<span></span>`)
+
+ Object.defineProperty(
+ Object.getPrototypeOf(container.ownerDocument),
+ 'defaultView',
+ {value: null},
+ )
+
+ expect(container.firstChild.ownerDocument.defaultView).toBe(null)
+
+ expect(isInstanceOfElement(container.firstChild, 'HTMLSpanElement')).toBe(
+ true,
+ )
+ expect(isInstanceOfElement(container.firstChild, 'HTMLDivElement')).toBe(
+ false,
+ )
+ })
+
+ test('check in environment not providing constructors on window', () => {
+ const {container} = render(`<span></span>`)
+
+ delete global.window.HTMLSpanElement
+
+ expect(container.firstChild.ownerDocument.defaultView.HTMLSpanElement).toBe(
+ undefined,
+ )
+
+ expect(isInstanceOfElement(container.firstChild, 'HTMLSpanElement')).toBe(
+ true,
+ )
+ expect(isInstanceOfElement(container.firstChild, 'HTMLDivElement')).toBe(
+ false,
+ )
+ })
+
+ test('throw error if element is not created by HTML*Element constructor', () => {
+ const doc = new Document()
+
+ // constructor is global.Element
+ const element = doc.createElement('span')
+
+ expect(() => isInstanceOfElement(element, 'HTMLSpanElement')).toThrow()
+ })
+})
+
 test('should always use realTimers before using callback when timers are faked with useFakeTimers', () => {
  const originalSetTimeout = globalObj.setTimeout
 

src/helpers.js

@@ -100,6 +100,36 @@ function getWindowFromNode(node) {
  }
 }
 
+/**
+ * Check if an element is of a given type.
+ *
+ * @param Element The element to test
+ * @param string Constructor name. E.g. 'HTMLSelectElement'
+ */
+function isInstanceOfElement(element, elementType) {
+ try {
+ const window = getWindowFromNode(element)
+ // Window usually has the element constructors as properties but is not required to do so per specs
+ if (typeof window[elementType] === 'function') {
+ return element instanceof window[elementType]
+ }
+ } catch (e) {
+ // The document might not be associated with a window
+ }
+
+ // Fall back to the constructor name as workaround for test environments that
+ // a) not associate the document with a window
+ // b) not provide the constructor as property of window
+ if (/^HTML(\w+)Element$/.test(element.constructor.name)) {
+ return element.constructor.name === elementType
+ }
+
+ // The user passed some node that is not created in a browser-like environment
+ throw new Error(
+ `Unable to verify if element is instance of ${elementType}. Please file an issue describing your test environment: https:/testing-library/dom-testing-library/issues/new`,
+ )
+}
+
 function checkContainerType(container) {
  if (
  !container ||
@@ -131,4 +161,5 @@ export {
  checkContainerType,
  jestFakeTimersAreEnabled,
  TEXT_NODE,
+ isInstanceOfElement,
 }