Skip to content

docs: expanded filter documentation and examples #681

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 11, 2020
Merged

docs: expanded filter documentation and examples #681

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 75 additions & 3 deletions docs/dom-testing-library/api-queries.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ id: api-queries
title: Queries
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

## Variants

Expand Down Expand Up @@ -169,6 +169,7 @@ The example below will find the input node for the following DOM structures:
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -178,6 +179,7 @@ const inputNode = screen.getByLabelText('Username')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -189,13 +191,15 @@ const inputNode = screen.getByLabelText('username')
</TabItem>
<TabItem value="cypress">


```js
cy.findByLabelText('username').should('exist')
```

</TabItem>
</Tabs>


It will NOT find the input node for label text broken up by elements. You can
use `getByRole('textbox', { name: 'Username' })` instead which is robust against
switching to `aria-label` or `aria-labelledby`.
Expand Down Expand Up @@ -263,6 +267,7 @@ matches the given [`TextMatch`](#textmatch).
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -272,6 +277,7 @@ const inputNode = screen.getByPlaceholderText('Username')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -282,13 +288,15 @@ const inputNode = screen.getByPlaceholderText('Username')
</TabItem>
<TabItem value="cypress">


```js
cy.findByPlaceholderText('Username').should('exist')
```

</TabItem>
</Tabs>


> **Note**
>
> A placeholder is not a good substitute for a label so you should generally use
Expand Down Expand Up @@ -322,6 +330,7 @@ matching the given [`TextMatch`](#textmatch).
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -331,6 +340,7 @@ const aboutAnchorNode = screen.getByText(/about/i)
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -341,13 +351,15 @@ const aboutAnchorNode = screen.getByText(/about/i)
</TabItem>
<TabItem value="cypress">


```js
cy.findByText(/about/i).should('exist')
```

</TabItem>
</Tabs>


It also works with `input`s whose `type` attribute is either `submit` or
`button`:

Expand Down Expand Up @@ -400,6 +412,7 @@ as it's deprecated).
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -409,6 +422,7 @@ const incrediblesPosterImg = screen.getByAltText(/incredibles.*? poster/i)
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -419,13 +433,15 @@ const incrediblesPosterImg = screen.getByAltText(/incredibles.*? poster/i)
</TabItem>
<TabItem value="cypress">


```js
cy.findByAltText(/incredibles.*? poster/i).should('exist')
```

</TabItem>
</Tabs>


### `ByTitle`

> getByTitle, queryByTitle, getAllByTitle, queryAllByTitle, findByTitle,
Expand Down Expand Up @@ -457,6 +473,7 @@ Will also find a `title` element within an SVG.
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -467,6 +484,7 @@ const closeElement = screen.getByTitle('Close')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -478,6 +496,7 @@ const closeElement = screen.getByTitle('Close')
</TabItem>
<TabItem value="cypress">


```js
cy.findByTitle('Delete').should('exist')
cy.findByTitle('Close').should('exist')
Expand All @@ -486,6 +505,7 @@ cy.findByTitle('Close').should('exist')
</TabItem>
</Tabs>


### `ByDisplayValue`

> getByDisplayValue, queryByDisplayValue, getAllByDisplayValue,
Expand Down Expand Up @@ -518,6 +538,7 @@ document.getElementById('lastName').value = 'Norris'
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -527,6 +548,7 @@ const lastNameInput = screen.getByDisplayValue('Norris')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -537,13 +559,15 @@ const lastNameInput = screen.getByDisplayValue('Norris')
</TabItem>
<TabItem value="cypress">


```js
cy.findByDisplayValue('Norris').should('exist')
```

</TabItem>
</Tabs>


#### `textarea`

```html
Expand All @@ -558,6 +582,7 @@ document.getElementById('messageTextArea').value = 'Hello World'
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -567,6 +592,7 @@ const messageTextArea = screen.getByDisplayValue('Hello World')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -577,13 +603,15 @@ const messageTextArea = screen.getByDisplayValue('Hello World')
</TabItem>
<TabItem value="cypress">


```js
cy.findByDisplayValue('Hello World').should('exist')
```

</TabItem>
</Tabs>


#### `select`

In case of `select`, this will search for a `<select>` whose selected `<option>`
Expand All @@ -602,6 +630,7 @@ matches the given [`TextMatch`](#textmatch).
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -611,6 +640,7 @@ const selectElement = screen.getByDisplayValue('Alaska')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -621,13 +651,15 @@ const selectElement = screen.getByDisplayValue('Alaska')
</TabItem>
<TabItem value="cypress">


```js
cy.findByDisplayValue('Alaska').should('exist')
```

</TabItem>
</Tabs>


### `ByRole`

> getByRole, queryByRole, getAllByRole, queryAllByRole, findByRole,
Expand All @@ -645,6 +677,7 @@ getByRole(
selected?: boolean,
checked?: boolean,
pressed?: boolean,
expanded?: boolean,
queryFallbacks?: boolean,
level?: number,
}): HTMLElement
Expand Down Expand Up @@ -778,6 +811,37 @@ you can get the "👍" button by calling `getByRole('button', { pressed: true })
To learn more about the pressed state see
[ARIA `aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).

#### `expanded`

You can filter the returned elements by their expanded state by setting
`expanded: true` or `expanded: false`.

For example in

```html
<body>
<nav>
<ul>
<li>
<a aria-expanded="false" aria-haspopup="true" href="..."
>Expandable Menu Item</a
>
<ul>
<li><a href="#">Submenu Item 1</a></li>
<li><a href="#">Submenu Item 1</a></li>
</ul>
</li>
<li><a href="#">Regular Menu Item</a></li>
</ul>
</nav>
</body>
```

you can get the "Expandable Menu Item" link by calling
`getByRole('link', { expanded: false })`. To learn more about the checked state
and which elements can have this state see
[ARIA `aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded).

```html
<div role="dialog">...</div>
```
Expand All @@ -786,6 +850,7 @@ To learn more about the pressed state see
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -795,6 +860,7 @@ const dialogContainer = screen.getByRole('dialog')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -805,13 +871,15 @@ const dialogContainer = screen.getByRole('dialog')
</TabItem>
<TabItem value="cypress">


```js
cy.findByRole('dialog').should('exist')
```

</TabItem>
</Tabs>


#### `queryFallbacks`

By default, it's assumed that the first role of each element is supported, so
Expand Down Expand Up @@ -903,6 +971,7 @@ also accepts a [`TextMatch`](#textmatch)).
label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
<TabItem value="native">


```js
import { screen } from '@testing-library/dom'

Expand All @@ -912,6 +981,7 @@ const element = screen.getByTestId('custom-element')
</TabItem>
<TabItem value="react">


```jsx
import { render, screen } from '@testing-library/react'

Expand All @@ -922,13 +992,15 @@ const element = screen.getByTestId('custom-element')
</TabItem>
<TabItem value="cypress">


```js
cy.findByTestId('custom-element').should('exist')
```

</TabItem>
</Tabs>


> In the spirit of [the guiding principles](guiding-principles.mdx), it is
> recommended to use this only after the other queries don't work for your use
> case. Using data-testid attributes do not resemble how your software is used
Expand Down Expand Up @@ -1006,7 +1078,7 @@ To override normalization to remove some Unicode characters whilst keeping some

```javascript
screen.getByText('text', {
normalizer: str =>
normalizer: (str) =>
getDefaultNormalizer({ trim: false })(str).replace(/[\u200E-\u200F]*/g, ''),
})
```
Expand Down