From 34d4a805080226c8dedb1f5c06f2bdb74fd4e73a Mon Sep 17 00:00:00 2001
From: Matthias Kainer <mail@matthias-kainer.de>
Date: Tue, 16 Nov 2021 16:31:40 +0100
Subject: [PATCH 1/3] 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:
https://github.com/testing-library/dom-testing-library/pull/1054
---
 .../dom-testing-library/api-configuration.mdx | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/dom-testing-library/api-configuration.mdx b/docs/dom-testing-library/api-configuration.mdx
index 98eee3e70..cba87519a 100644
--- a/docs/dom-testing-library/api-configuration.mdx
+++ b/docs/dom-testing-library/api-configuration.mdx
@@ -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`.

From 0707a53bead6a0dea9131ff7328cc86743d04204 Mon Sep 17 00:00:00 2001
From: Matthias Kainer <mail@matthias-kainer.de>
Date: Tue, 23 Nov 2021 12:48:39 +0100
Subject: [PATCH 2/3] doc(queryconfig): Apply suggestions from review

Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com>
---
 docs/dom-testing-library/api-configuration.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/dom-testing-library/api-configuration.mdx b/docs/dom-testing-library/api-configuration.mdx
index cba87519a..059fbeaa5 100644
--- a/docs/dom-testing-library/api-configuration.mdx
+++ b/docs/dom-testing-library/api-configuration.mdx
@@ -133,12 +133,12 @@ configure({
 
 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).
+`queryElement`) or a list of elements (for `queryAllElements`).
 
-This can be used to allow to extend queries to reach into the shadow dom or
+This can be used 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:
+library looks like the following:
 
 ```js
 import {

From 011d3f298b2aa40827ef141814bd033d1a834bcb Mon Sep 17 00:00:00 2001
From: Matthias Kainer <mail@matthias-kainer.de>
Date: Tue, 23 Nov 2021 12:49:55 +0100
Subject: [PATCH 3/3] doc(queryconfig): Moved default values up to first
 snipped as proposed

Co-authored-by: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com>
---
 docs/dom-testing-library/api-configuration.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/dom-testing-library/api-configuration.mdx b/docs/dom-testing-library/api-configuration.mdx
index 059fbeaa5..ddf636923 100644
--- a/docs/dom-testing-library/api-configuration.mdx
+++ b/docs/dom-testing-library/api-configuration.mdx
@@ -131,12 +131,14 @@ configure({
 })
 ```
 
+Defaults to `element.querySelector` and `element.querySelectorAll`.
+
 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 extend queries to reach into the shadow dom or
-iframes. An example using the
+This can be used 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 looks like the following:
 
@@ -150,5 +152,3 @@ configure({
   queryAllElements: querySelectorAllDeep,
 })
 ```
-
-Default to `element.querySelector` and `element.querySelectorAll`.