diff --git a/README.md b/README.md
index d617a07e..fd10183f 100644
--- a/README.md
+++ b/README.md
@@ -473,22 +473,37 @@ fireEvent.click(getElementByText('Submit'), rightClick)
Several APIs accept a `TextMatch` which can be a `string`, `regex` or a
`function` which returns `true` for a match and `false` for a mismatch.
-Here's an example
+See [dom-testing-library#textmatch][dom-testing-lib-textmatch] for options.
+
+Examples:
```javascript
-//
Hello World
-// all of the following will find the div
-getByText('Hello World') // full match
-getByText('llo worl') // substring match
-getByText('hello world') // strings ignore case
-getByText(/Hello W?oRlD/i) // regex
-getByText((content, element) => content.startsWith('Hello')) // function
-
-// all of the following will NOT find the div
-getByText('Goodbye World') // non-string match
-getByText(/hello world/) // case-sensitive regex with different case
-// function looking for a span when it's actually a div
-getByText((content, element) => {
+//
+// Hello World
+//
+
+// WILL find the div:
+
+// Matching a string:
+getByText(container, 'Hello World') // full string match
+getByText(container, 'llo Worl'), {exact: false} // substring match
+getByText(container, 'hello world', {exact: false}) // ignore case
+
+// Matching a regex:
+getByText(container, /World/) // substring match
+getByText(container, /world/i) // substring match, ignore case
+getByText(container, /^hello world$/i) // full string match, ignore case
+getByText(container, /Hello W?oRlD/i) // advanced regex
+
+// Matching with a custom function:
+getByText(container, (content, element) => content.startsWith('Hello'))
+
+// WILL NOT find the div:
+
+getByText(container, 'Goodbye World') // full string does not match
+getByText(container, /hello world/) // case-sensitive regex with different case
+// function looking for a span when it's actually a div:
+getByText(container, (content, element) => {
return element.tagName.toLowerCase() === 'span' && content.startsWith('Hello')
})
```
@@ -863,6 +878,7 @@ Links:
[set-immediate]: https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate
[guiding-principle]: https://twitter.com/kentcdodds/status/977018512689455106
[data-testid-blog-post]: https://blog.kentcdodds.com/making-your-ui-tests-resilient-to-change-d37a6ee37269
+[dom-testing-lib-textmatch]: https://github.com/kentcdodds/dom-testing-library#textmatch
[bugs]: https://github.com/kentcdodds/react-testing-library/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc
[requests]: https://github.com/kentcdodds/react-testing-library/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen
[good-first-issue]: https://github.com/kentcdodds/react-testing-library/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+
diff --git a/typings/index.d.ts b/typings/index.d.ts
index eec3f135..04897981 100644
--- a/typings/index.d.ts
+++ b/typings/index.d.ts
@@ -2,22 +2,44 @@ import {Simulate as ReactSimulate} from 'react-dom/test-utils'
type TextMatchFunction = (content: string, element: HTMLElement) => boolean
type TextMatch = string | RegExp | TextMatchFunction
-type ExactTextMatch = string | RegExp | TextMatchFunction
+type TextMatchOptions = {
+ exact?: boolean = false
+ trim?: boolean = true
+ collapseWhitespace?: boolean = true
+}
interface RenderResult {
container: HTMLDivElement
rerender: (ui: React.ReactElement) => void
unmount: VoidFunction
- queryByTestId: (id: ExactTextMatch) => HTMLElement | null
- getByTestId: (id: ExactTextMatch) => HTMLElement
- queryByText: (id: TextMatch) => HTMLElement | null
- getByText: (text: TextMatch) => HTMLElement
- queryByPlaceholderText: (id: TextMatch) => HTMLElement | null
- getByPlaceholderText: (text: TextMatch) => HTMLElement
- queryByLabelText: (text: TextMatch) => HTMLElement | null
- getByLabelText: (id: TextMatch, options?: {selector: string}) => HTMLElement
- queryByAltText: (text: TextMatch) => HTMLElement | null
- getByAltText: (text: TextMatch) => HTMLElement
+ queryByTestId: (
+ id: TextMatch,
+ options?: TextMatchOptions,
+ ) => HTMLElement | null
+ getByTestId: (id: TextMatch, options?: TextMatchOptions) => HTMLElement
+ queryByText: (id: TextMatch, options?: TextMatchOptions) => HTMLElement | null
+ getByText: (text: TextMatch, options?: TextMatchOptions) => HTMLElement
+ queryByPlaceholderText: (
+ id: TextMatch,
+ options?: TextMatchOptions,
+ ) => HTMLElement | null
+ getByPlaceholderText: (
+ text: TextMatch,
+ options?: TextMatchOptions,
+ ) => HTMLElement
+ queryByLabelText: (
+ text: TextMatch,
+ options?: TextMatchOptions,
+ ) => HTMLElement | null
+ getByLabelText: (
+ id: TextMatch,
+ options?: {selector?: string} & TextMatchOptions,
+ ) => HTMLElement
+ queryByAltText: (
+ text: TextMatch,
+ options?: TextMatchOptions,
+ ) => HTMLElement | null
+ getByAltText: (text: TextMatch, options?: TextMatchOptions) => HTMLElement
}
export function render(