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(