feat(queryconfig): Allows configuring a different element query mechanism

MatthiasKainer · MatthiasKainer · commit fe05919d3e3c · 2021-10-13T20:25:01.000+02:00
Commit opens the possibility to configure the api to use more sophisticated queries on elements, for instance enabling shadow dom specific queries via libraries like https://github.com/Georgegriff/query-selector-shadow-dom
diff --git a/src/__node_tests__/index.js b/src/__node_tests__/index.js
@@ -1,3 +1,4 @@
+import {configure} from '../config'
 import {JSDOM} from 'jsdom'
 import * as dtl from '../'
 
@@ -77,6 +78,52 @@ test('works without a browser context on a dom node (JSDOM Fragment)', () => {
   `)
 })
 
+test('works with a custom configured element query', () => {
+  const container = JSDOM.fragment(`
+    <html>
+      <body>
+        <form id="login-form">
+          <label for="username">Username</label>
+          <input id="username" />
+          <label for="password">Password</label>
+          <input id="password" type="password" />
+          <button type="submit">Submit</button>
+          <div id="data-container"></div>
+        </form>
+        <form id="other">
+          <label for="user_other">Username</label>
+          <input id="user_other" />
+          <label for="pass_other">Password</label>
+          <input id="pass_other" type="password" />
+          <button type="submit">Submit</button>
+          <div id="data-container"></div>
+        </form>
+      </body>
+    </html>
+  `)
+
+  configure({
+    queryAllElements: (element, query) =>
+      element.querySelectorAll(`#other ${query}`),
+  })
+
+  expect(dtl.getByLabelText(container, /username/i)).toMatchInlineSnapshot(`
+    <input
+      id=user_other
+    />
+  `)
+  expect(dtl.getByLabelText(container, /password/i)).toMatchInlineSnapshot(`
+    <input
+      id=pass_other
+      type=password
+    />
+  `)
+  // reset back to original config
+  configure({
+    queryAllElements: (element, query) => element.querySelectorAll(query),
+  })
+})
+
 test('byRole works without a global DOM', () => {
   const {
     window: {
diff --git a/src/config.ts b/src/config.ts
@@ -1,9 +1,27 @@
-import {Config, ConfigFn} from '../types/config'
+import {Config, ConfigFn, QueryAllElements, QueryElement} from '../types/config'
 import {prettyDOM} from './pretty-dom'
 
 type Callback<T> = () => T
+
+const queryElement: QueryElement = <T extends Element>(
+  element: T,
+  selector: string,
+) => element.querySelector(selector)
+const queryElementAll: QueryAllElements = <T extends Element>(
+  element: T,
+  selector: string,
+) => element.querySelectorAll(selector)
+
 interface InternalConfig extends Config {
   _disableExpensiveErrorDiagnostics: boolean
+  /**
+   * Returns the first element that is a descendant of node that matches selectors.
+   */
+  queryElement: QueryElement
+  /**
+   * Returns all element descendants of node that match selectors.
+   */
+  queryAllElements: QueryAllElements
 }
 
 // It would be cleaner for this to live inside './queries', but
@@ -46,6 +64,8 @@ let config: InternalConfig = {
   },
   _disableExpensiveErrorDiagnostics: false,
   computedStyleSupportsPseudoElements: false,
+  queryElement,
+  queryAllElements: queryElementAll,
 }
 
 export function runWithExpensiveErrorDiagnosticsDisabled<T>(
diff --git a/src/label-helpers.ts b/src/label-helpers.ts
@@ -1,5 +1,7 @@
 import {TEXT_NODE} from './helpers'
 
+import {getConfig} from './config'
+
 const labelledNodeNames = [
   'button',
   'meter',
@@ -43,7 +45,7 @@ function getRealLabels(element: Element) {
 
   if (!isLabelable(element)) return []
 
-  const labels = element.ownerDocument.querySelectorAll('label')
+  const labels = getConfig().queryAllElements(element.ownerDocument, 'label')
   return Array.from(labels).filter(label => label.control === element)
 }
 
@@ -63,7 +65,8 @@ function getLabels(
   const labelsId = ariaLabelledBy ? ariaLabelledBy.split(' ') : []
   return labelsId.length
     ? labelsId.map(labelId => {
-        const labellingElement = container.querySelector<HTMLElement>(
+        const labellingElement = getConfig().queryElement(
+          container,
           `[id="${labelId}"]`,
         )
         return labellingElement
@@ -75,7 +78,10 @@ function getLabels(
         const formControlSelector =
           'button, input, meter, output, progress, select, textarea'
         const labelledFormControl = Array.from(
-          label.querySelectorAll<HTMLElement>(formControlSelector),
+          getConfig().queryAllElements<Element, HTMLElement>(
+            label,
+            formControlSelector,
+          ),
         ).filter(formControlElement => formControlElement.matches(selector))[0]
         return {content: textToMatch, formControl: labelledFormControl}
       })
diff --git a/src/queries/display-value.ts b/src/queries/display-value.ts
@@ -12,6 +12,7 @@ import {
   fuzzyMatches,
   makeNormalizer,
   buildQueries,
+  getConfig,
 } from './all-utils'
 
 const queryAllByDisplayValue: AllByBoundAttribute = (
@@ -23,7 +24,10 @@ const queryAllByDisplayValue: AllByBoundAttribute = (
   const matcher = exact ? matches : fuzzyMatches
   const matchNormalizer = makeNormalizer({collapseWhitespace, trim, normalizer})
   return Array.from(
-    container.querySelectorAll<HTMLElement>(`input,textarea,select`),
+    getConfig().queryAllElements<HTMLElement, HTMLElement>(
+      container,
+      `input,textarea,select`,
+    ),
   ).filter(node => {
     if (node.tagName === 'SELECT') {
       const selectedOptions = Array.from(
diff --git a/src/queries/label-text.ts b/src/queries/label-text.ts
@@ -1,4 +1,3 @@
-import {getConfig} from '../config'
 import {checkContainerType} from '../helpers'
 import {getLabels, getRealLabels, getLabelContent} from '../label-helpers'
 import {
@@ -17,12 +16,18 @@ import {
   makeSingleQuery,
   wrapAllByQueryWithSuggestion,
   wrapSingleQueryWithSuggestion,
+  getConfig,
 } from './all-utils'
 
 function queryAllLabels(
   container: HTMLElement,
 ): {textToMatch: string | null; node: HTMLElement}[] {
-  return Array.from(container.querySelectorAll<HTMLElement>('label,input'))
+  return Array.from(
+    getConfig().queryAllElements<HTMLElement, HTMLElement>(
+      container,
+      'label,input',
+    ),
+  )
     .map(node => {
       return {node, textToMatch: getLabelContent(node)}
     })
@@ -56,7 +61,7 @@ const queryAllByLabelText: AllByText = (
   const matcher = exact ? matches : fuzzyMatches
   const matchNormalizer = makeNormalizer({collapseWhitespace, trim, normalizer})
   const matchingLabelledElements = Array.from(
-    container.querySelectorAll<HTMLElement>('*'),
+    getConfig().queryAllElements<HTMLElement, HTMLElement>(container, '*'),
   )
     .filter(element => {
       return (
@@ -169,7 +174,7 @@ function getTagNameOfElementAssociatedWithLabelViaFor(
     return null
   }
 
-  const element = container.querySelector(`[id="${htmlFor}"]`)
+  const element = getConfig().queryElement(container, `[id="${htmlFor}"]`)
   return element ? element.tagName.toLowerCase() : null
 }
 
diff --git a/src/queries/role.js b/src/queries/role.js
@@ -100,7 +100,8 @@ function queryAllByRole(
   }
 
   return Array.from(
-    container.querySelectorAll(
+    getConfig().queryAllElements(
+      container,
       // Only query elements that can be matched by the following filters
       makeRoleSelector(role, exact, normalizer ? matchNormalizer : undefined),
     ),
diff --git a/src/queries/text.ts b/src/queries/text.ts
@@ -5,6 +5,7 @@ import {AllByText, GetErrorFunction} from '../../types'
 import {
   fuzzyMatches,
   matches,
+  getConfig,
   makeNormalizer,
   getNodeText,
   buildQueries,
@@ -32,7 +33,12 @@ const queryAllByText: AllByText = (
   return (
     [
       ...baseArray,
-      ...Array.from(container.querySelectorAll<HTMLElement>(selector)),
+      ...Array.from(
+        getConfig().queryAllElements<HTMLElement, HTMLElement>(
+          container,
+          selector,
+        ),
+      ),
     ]
       // TODO: `matches` according lib.dom.d.ts can get only `string` but according our code it can handle also boolean :)
       .filter(node => !ignore || !node.matches(ignore as string))
diff --git a/src/queries/title.ts b/src/queries/title.ts
@@ -9,6 +9,7 @@ import {
 import {
   fuzzyMatches,
   matches,
+  getConfig,
   makeNormalizer,
   getNodeText,
   buildQueries,
@@ -27,7 +28,10 @@ const queryAllByTitle: AllByBoundAttribute = (
   const matcher = exact ? matches : fuzzyMatches
   const matchNormalizer = makeNormalizer({collapseWhitespace, trim, normalizer})
   return Array.from(
-    container.querySelectorAll<HTMLElement>('[title], svg > title'),
+    getConfig().queryAllElements<HTMLElement, HTMLElement>(
+      container,
+      '[title], svg > title',
+    ),
   ).filter(
     node =>
       matcher(node.getAttribute('title'), node, text, matchNormalizer) ||
diff --git a/src/query-helpers.ts b/src/query-helpers.ts
@@ -35,7 +35,10 @@ function queryAllByAttribute(
   const matcher = exact ? matches : fuzzyMatches
   const matchNormalizer = makeNormalizer({collapseWhitespace, trim, normalizer})
   return Array.from(
-    container.querySelectorAll<HTMLElement>(`[${attribute}]`),
+    getConfig().queryAllElements<HTMLElement, HTMLElement>(
+      container,
+      `[${attribute}]`,
+    ),
   ).filter(node =>
     matcher(node.getAttribute(attribute), node, text, matchNormalizer),
   )
diff --git a/types/__tests__/type-tests.ts b/types/__tests__/type-tests.ts
@@ -40,14 +40,14 @@ export async function testQueries() {
 
   // screen queries
   screen.getByText('foo')
-  screen.getByText<HTMLDivElement>('foo')
+  screen.getByText('foo')
   screen.queryByText('foo')
   await screen.findByText('foo')
   await screen.findByText('foo', undefined, {timeout: 10})
   screen.debug(screen.getAllByText('bar'))
   screen.queryAllByText('bar')
   await screen.findAllByText('bar')
-  await screen.findAllByRole<HTMLButtonElement>('button', {name: 'submit'})
+  await screen.findAllByRole('button', {name: 'submit'})
   await screen.findAllByText('bar', undefined, {timeout: 10})
 }
 
@@ -249,11 +249,11 @@ export async function testWithin() {
   container.queryAllByLabelText('Some label')
 
   container.getByText('Click me')
-  container.getByText<HTMLButtonElement>('Click me')
-  container.getAllByText<HTMLButtonElement>('Click me')
+  container.getByText('Click me')
+  container.getAllByText('Click me')
 
   await container.findByRole('button', {name: /click me/i})
-  container.getByRole<HTMLButtonElement>('button', {name: /click me/i})
+  container.getByRole('button', {name: /click me/i})
 }
 
 /*
diff --git a/types/config.d.ts b/types/config.d.ts
@@ -1,3 +1,27 @@
+export type QueryElement = {
+  <T, K extends keyof HTMLElementTagNameMap>(container: T, selectors: K):
+    | HTMLElementTagNameMap[K]
+    | null
+  <T, K extends keyof SVGElementTagNameMap>(container: T, selectors: K):
+    | SVGElementTagNameMap[K]
+    | null
+  <T, E extends Element = Element>(container: T, selectors: string): E | null
+}
+export type QueryAllElements = {
+  <T, K extends keyof HTMLElementTagNameMap>(
+    container: T,
+    selectors: K,
+  ): NodeListOf<HTMLElementTagNameMap[K]>
+  <T, K extends keyof SVGElementTagNameMap>(
+    container: T,
+    selectors: K,
+  ): NodeListOf<SVGElementTagNameMap[K]>
+  <T, E extends Element = Element>(
+    container: T,
+    selectors: string,
+  ): NodeListOf<E>
+}
+
 export interface Config {
   testIdAttribute: string
   /**
@@ -14,6 +38,14 @@ export interface Config {
   defaultHidden: boolean
   showOriginalStackTrace: boolean
   throwSuggestions: boolean
+  /**
+   * Returns the first element that is a descendant of node that matches selectors.
+   */
+  queryElement?: QueryElement
+  /**
+   * Returns all element descendants of node that match selectors.
+   */
+  queryAllElements?: QueryAllElements
   getElementError: (message: string | null, container: Element) => Error
 }
 

Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,8 @@ function queryAllByRole(`
`100`	`100`	`}`
`101`	`101`
`102`	`102`	`return Array.from(`
`103`		`- container.querySelectorAll(`
	`103`	`+ getConfig().queryAllElements(`
	`104`	`+ container,`
`104`	`105`	`// Only query elements that can be matched by the following filters`
`105`	`106`	`makeRoleSelector(role, exact, normalizer ? matchNormalizer : undefined),`
`106`	`107`	`),`