From dbc3bb548ffc22b8499255c217b9a3444cdc47e6 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Tue, 12 Feb 2019 22:00:21 -0800 Subject: [PATCH 1/2] reorganize query documentation --- docs/api-helpers.md | 17 ++++++++++++ docs/api-queries.md | 63 +++++++++++++++++++++++++-------------------- 2 files changed, 52 insertions(+), 28 deletions(-) diff --git a/docs/api-helpers.md b/docs/api-helpers.md index ac118eb26..37f20509b 100644 --- a/docs/api-helpers.md +++ b/docs/api-helpers.md @@ -95,6 +95,23 @@ const buttonText = getNodeText(container.querySelector('input[type=button]')) // These elements use the attribute `value` and display its value to the user. ``` +## `within` and `getQueriesForElement` APIs + +`within` (an alias to `getQueriesForElement`) takes a DOM element and binds it +to the raw query functions, allowing them to be used without specifying a +container. It is the recommended approach for libraries built on this API and is +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 +import { within } from 'dom-testing-library' + +const { getByText } = within(document.getElementById('messages')) +const helloMessage = getByText('hello') +``` + ## Debugging When you use any `get` calls in your test cases, the current state of the diff --git a/docs/api-queries.md b/docs/api-queries.md index 5b01f5171..15d9e2c33 100644 --- a/docs/api-queries.md +++ b/docs/api-queries.md @@ -3,17 +3,41 @@ id: api-queries title: Queries --- -## Queries +## Variants -> **Note** -> -> - Each of the `get` APIs below have a matching -> [`getAll`](#queryall-and-getall-apis) API that returns all elements instead -> of just the first one, and -> [`query`](#query-apis)/[`queryAll`](#queryall-and-getall-apis) that return -> `null`/`[]` instead of throwing an error. -> - See [TextMatch](#textmatch) for details on the `exact`, `trim`, and -> `collapseWhitespace` options. +> `getBy` queries are shwon by default in the [query documentation](#queries) +> below because returning a single element or throwing a debuggable error is the +> most common case. + +### getBy + +[`getBy*`](#queries) queries returns the first matching node for a query, and +throw an error if no elements match. + +### getAllBy + +[`getAllBy*`](#queryall-and-getall-apis) queries return an array of all matching +nodes for a query, and throw an error if no elements match. + +### queryBy + +[`queryBy*`](#query-apis) queries returns the first matching node for a query, +and return `null` if no elements match. + +### queryAllBy + +[`queryAllBy*`](#queryall-and-getall-apis) queries return an array of all +matching nodes for a query, and return an empty array (`[]`) if no elements +match. + +## Options + +The argument to a query can be a _string_, _regular expression_, or _function_. +There are also options to adjust how node text is parsed. + +See [TextMatch](#textmatch) for documentation on what can be passed to a query. + +## Queries ### `getByLabelText` @@ -391,7 +415,7 @@ getByText(container, (content, element) => { ## `query` APIs -Each of the `get` APIs listed in [the 'Usage'](#usage) section above have a +Each of the `get` APIs listed in the [queries](#queries) section above have a complimentary `query` API. The `get` APIs will throw errors if a proper node cannot be found. This is normally the desired effect. However, if you want to make an assertion that an element is _not_ present in the DOM, then you can use @@ -415,20 +439,3 @@ const submitButtons = queryAllByText(container, 'submit') expect(submitButtons).toHaveLength(3) // expect 3 elements expect(submitButtons[0]).toBeTruthy() ``` - -## `within` and `getQueriesForElement` APIs - -`within` (an alias to `getQueriesForElement`) takes a DOM element and binds it -to the raw query functions, allowing them to be used without specifying a -container. It is the recommended approach for libraries built on this API and is -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 -import { within } from 'dom-testing-library' - -const { getByText } = within(document.getElementById('messages')) -const helloMessage = getByText('hello') -``` From febfb1939daee2e6679738e5f8dfde84a6db8374 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Tue, 12 Feb 2019 23:45:31 -0800 Subject: [PATCH 2/2] Add searchable text for each query variant --- docs/api-queries.md | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/docs/api-queries.md b/docs/api-queries.md index 15d9e2c33..21b28a400 100644 --- a/docs/api-queries.md +++ b/docs/api-queries.md @@ -5,13 +5,12 @@ title: Queries ## Variants -> `getBy` queries are shwon by default in the [query documentation](#queries) -> below because returning a single element or throwing a debuggable error is the -> most common case. +> `getBy` queries are shown by default in the [query documentation](#queries) +> below. ### getBy -[`getBy*`](#queries) queries returns the first matching node for a query, and +[`getBy*`](#query-apis) queries returns the first matching node for a query, and throw an error if no elements match. ### getAllBy @@ -39,7 +38,9 @@ See [TextMatch](#textmatch) for documentation on what can be passed to a query. ## Queries -### `getByLabelText` +### `ByLabelText` + +> getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText ```typescript getByLabelText( @@ -93,7 +94,10 @@ const inputNode = getByLabelText(container, 'username', { selector: 'input' }) > this behavior (for example you wish to assert that it doesn't exist), then use > `queryByLabelText` instead. -### `getByPlaceholderText` +### `ByPlaceholderText` + +> getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText, +> queryAllByPlaceholderText ```typescript getByPlaceholderText( @@ -118,7 +122,9 @@ const inputNode = getByPlaceholderText(container, 'Username') > A placeholder is not a good substitute for a label so you should generally use > `getByLabelText` instead. -### `getByText` +### `ByText` + +> getByText, queryByText, getAllByText, queryAllByText ```typescript getByText( @@ -161,7 +167,9 @@ content is in an inline script file, then the script tag could be returned. If you'd rather disable this behavior, set `ignore` to `false`. -### `getByAltText` +### `ByAltText` + +> getByAltText, queryByAltText, getAllByAltText, queryAllByAltText ```typescript getByAltText( @@ -187,7 +195,9 @@ as it's deprecated). const incrediblesPosterImg = getByAltText(container, /incredibles.*poster$/i) ``` -### `getByTitle` +### `ByTitle` + +> getByTitle, queryByTitle, getAllByTitle, queryAllByTitle ```typescript getByTitle( @@ -213,7 +223,10 @@ Will also find a `title` element within an SVG. const closeElement = getByTitle(container, 'Close') ``` -### `getByDisplayValue` +### `ByDisplayValue` + +> getByDisplayValue, queryByDisplayValue, getAllByDisplayValue, +> queryAllByDisplayValue ```typescript getByDisplayValue( @@ -262,7 +275,9 @@ const selectElement = getByDisplayName(container, 'Alaska') In case of `select`, this will search for a `