Skip to content

Commit 34d4a80

Browse files
doc(queryconfig): Allows configuring a different element query mechanism
Provides the ability to specify a different element query mechanism other than querySelector and querySelectorAll. An example of the usage with Georgegriff/query-selector-shadow-dom looks like this: import { querySelectorAllDeep, querySelectorDeep } from 'query-selector-shadow-dom'; configure({ queryElement: querySelectorDeep, queryAllElements: querySelectorAllDeep, }) After this line, a query will also drill into the shadow dom of elements on the page Why: In our project, we are using a design system build with web components (via stenciljs), and different projects in different frameworks (lit, react, vue) want to use this library. The corresponding pr can be found here: testing-library/dom-testing-library#1054
1 parent f9729ff commit 34d4a80

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

docs/dom-testing-library/api-configuration.mdx

+36
Original file line numberDiff line numberDiff line change
@@ -116,3 +116,39 @@ message and container object as arguments.
116116

117117
The global timeout value in milliseconds used by `waitFor` utilities. Defaults
118118
to 1000ms.
119+
120+
### `queryElement` & `queryAllElements`
121+
122+
If your application requires a specific way to query elements on the page, you
123+
can define a custom strategy used by the testing library.
124+
125+
For that register your strategy once:
126+
127+
```js
128+
configure({
129+
queryElement: (element, query) => element.querySelector(query),
130+
queryAllElements: (element, query) => element.querySelectorAll(query),
131+
})
132+
```
133+
134+
The interface of the functions will take two arguments, `element` and `query`,
135+
which the wrapper can use. The expected return value is a single element (for
136+
queryElement) or a list of elements (for queryAllElements).
137+
138+
This can be used to allow to extend queries to reach into the shadow dom or
139+
iframes. An example using the
140+
[query-selector-shadow-dom](https://github.com/Georgegriff/query-selector-shadow-dom)
141+
library would look like the following:
142+
143+
```js
144+
import {
145+
querySelectorAllDeep,
146+
querySelectorDeep,
147+
} from 'query-selector-shadow-dom'
148+
configure({
149+
queryElement: querySelectorDeep,
150+
queryAllElements: querySelectorAllDeep,
151+
})
152+
```
153+
154+
Default to `element.querySelector` and `element.querySelectorAll`.

0 commit comments

Comments
 (0)