Skip to content

Commit

Permalink
doc(queryconfig): Allows configuring a different element query mechanism
Browse files Browse the repository at this point in the history
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
  • Loading branch information
MatthiasKainer committed Nov 16, 2021
1 parent f9729ff commit 34d4a80
Showing 1 changed file with 36 additions and 0 deletions.
36 changes: 36 additions & 0 deletions docs/dom-testing-library/api-configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -116,3 +116,39 @@ message and container object as arguments.

The global timeout value in milliseconds used by `waitFor` utilities. Defaults
to 1000ms.

### `queryElement` & `queryAllElements`

If your application requires a specific way to query elements on the page, you
can define a custom strategy used by the testing library.

For that register your strategy once:

```js
configure({
queryElement: (element, query) => element.querySelector(query),
queryAllElements: (element, query) => element.querySelectorAll(query),
})
```

The interface of the functions will take two arguments, `element` and `query`,
which the wrapper can use. The expected return value is a single element (for
queryElement) or a list of elements (for queryAllElements).

This can be used to allow to extend queries to reach into the shadow dom or
iframes. An example using the
[query-selector-shadow-dom](https://github.com/Georgegriff/query-selector-shadow-dom)
library would look like the following:

```js
import {
querySelectorAllDeep,
querySelectorDeep,
} from 'query-selector-shadow-dom'
configure({
queryElement: querySelectorDeep,
queryAllElements: querySelectorAllDeep,
})
```

Default to `element.querySelector` and `element.querySelectorAll`.

0 comments on commit 34d4a80

Please sign in to comment.