document within/custom queries

Author: alexkrolick

docs/api-helpers.md

@@ -50,6 +50,12 @@ module.exports = {
 }
 ```
 
+> **Note**
+>
+> Custom queries can be added to `react-testing-library`'s `render` method by
+> adding `queries` to the options config object. See the render
+> [options](/docs/react-testing-library/api#render-options).
+
 ### Using other assertion libraries
 
 If you're not using jest, you may be able to find a similar set of custom
@@ -105,13 +111,37 @@ in use in `react-testing-library` and `vue-testing-library`.
 Example: To get the text 'hello' only within a section called 'messages', you
 could do:
 
-```javascript
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--Native-->
+
+```js
 import { within } from 'dom-testing-library'
 
 const { getByText } = within(document.getElementById('messages'))
 const helloMessage = getByText('hello')
 ```
 
+<!--React-->
+
+```js
+import { render, within } from 'react-testing-library'
+
+const { getByLabelText } = render(<MyComponent />)
+const signinModal = getByLabelText('Sign In')
+within(signinModal).getByPlaceholderText('Username')
+```
+
+<!--Cypress-->
+
+```js
+cy.get('form').within(() => {
+  cy.getByText('Button Text').should('be.disabled')
+})
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
 ## Debugging
 
 When you use any `get` calls in your test cases, the current state of the

docs/react-testing-library/api.md

@@ -92,6 +92,27 @@ Pass a React Component as the `wrapper` option to have it rendered around the
 inner element. This is most useful for creating reusable custom render functions
 for common data providers. See [setup](setup.md#custom-render) for examples.
 
+### `queries`
+
+Queries to bind. Overrides the default set from `dom-testing-library` unless
+merged.
+
+```js
+// Example, a function to traverse table contents
+import * as tableQueries from 'my-table-query-libary'
+import queries from 'react-testing-library'
+
+const { getByRowColumn, getByText } = render(<MyTable />, {
+  queries: { ...queries, ...tableQueries },
+})
+```
+
+See [helpers](../api-helpers.md) for guidance on using utility functions to
+create custom queries.
+
+Custom queries can also be added globally by following the
+[custom render guide](./setup#custom-render).
+
 ## `render` Result
 
 The `render` method returns an object that has a few properties: