From b07bf6bf942e040d73f7984de018651ceacc1192 Mon Sep 17 00:00:00 2001
From: Alex Krolick <alexkrolick@users.noreply.github.com>
Date: Tue, 6 Nov 2018 14:20:30 -0800
Subject: [PATCH] docs: add custom query example (#146)

- show the much-asked-for data-test-id override as the default example
- use commonjs module syntax due to a babel 6 issue with overwriting named exports (not present in v7)

<!--
Thanks for your interest in the project. Bugs filed and PRs submitted are appreciated!

Please make sure that you are familiar with and follow the Code of Conduct for
this project (found in the CODE_OF_CONDUCT.md file).

Also, please make sure you're familiar with and follow the instructions in the
contributing guidelines (found in the CONTRIBUTING.md file).

If you're new to contributing to open source projects, you might find this free
video course helpful: http://kcd.im/pull-request

Please fill out the information below to expedite the review and (hopefully)
merge of your pull request!
-->

<!-- What changes are being made? (What feature/bug is being fixed here?) -->

**What**:

<!-- Why are these changes necessary? -->

**Why**:

<!-- How were these changes implemented? -->

**How**:

<!-- Have you done all of these things?  -->

**Checklist**:

<!-- add "N/A" to the end of each line that's irrelevant to your changes -->

<!-- to check an item, place an "x" in the box like so: "- [x] Documentation" -->

- [ ] Documentation
- [ ] Tests
- [x] Ready to be merged <!-- In your opinion, is this ready to be merged as soon as it's reviewed? -->
- [ ] Added myself to contributors table <!-- this is optional, see the contributing guidelines for instructions -->

<!-- feel free to add additional comments -->
---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/README.md b/README.md
index a61eae93..4339e125 100644
--- a/README.md
+++ b/README.md
@@ -710,6 +710,49 @@ expect(queryByTestId(container, 'greetings')).not.toHaveTextContent('Bye bye')
 Check out [jest-dom's documentation](https://github.com/gnapse/jest-dom#readme)
 for a full list of available matchers.
 
+## Custom Queries
+
+`dom-testing-library` exposes many of the helper functions that are used to implement the default queries. You can use the helpers to build custom queries. For example, the code below shows a way to override the default `testId` queries to use a different data-attribute. (Note: test files would import `test-utils.js` instead of using `dom-testing-library` directly).
+
+```js
+// test-utils.js
+const domTestingLib = require('dom-testing-library')
+const {queryHelpers} = domTestingLib
+
+export const queryByTestId = queryHelpers.queryByAttribute.bind(
+  null,
+  'data-test-id',
+)
+export const queryAllByTestId = queryHelpers.queryAllByAttribute.bind(
+  null,
+  'data-test-id',
+)
+
+export function getAllByTestId(container, id, ...rest) {
+  const els = queryAllByTestId(container, id, ...rest)
+  if (!els.length) {
+    throw queryHelpers.getElementError(
+      `Unable to find an element by: [data-test-id="${id}"]`,
+      container,
+    )
+  }
+  return els
+}
+
+export function getByTestId(...args) {
+  return queryHelpers.firstResultOrNull(getAllByTestId, ...args)
+}
+
+// re-export with overrides
+module.exports = {
+  ...domTestingLib,
+  getByTestId,
+  getAllByTestId,
+  queryByTestId,
+  queryAllByTestId,
+}
+```
+
 ### Using other assertion libraries
 
 If you're not using jest, you may be able to find a similar set of custom