Skip to content

docs: reorganize query docs #735

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 6 commits into from
Jan 13, 2021
Merged

docs: reorganize query docs #735

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dcf41db
docs: reorganize query docs
alexkrolick Jan 13, 2021
a344901
Update docs/dom-testing-library/api-async.mdx
alexkrolick Jan 13, 2021
b95c6e1
Update docs/dom-testing-library/api-async.mdx
alexkrolick Jan 13, 2021
bc4fbc0
Update docs/dom-testing-library/api-async.mdx
alexkrolick Jan 13, 2021
85d5a99
reorganize event docs
alexkrolick Jan 13, 2021
38eaa78
fix links
alexkrolick Jan 13, 2021
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
29 changes: 0 additions & 29 deletions docs/contributing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,35 +40,6 @@ Links:

<!-- prettier-ignore-start -->

[npm]: https://www.npmjs.com/
[node]: https://nodejs.org
[build-badge]: https://img.shields.io/travis/kentcdodds/react-testing-library.svg?style=flat-square
[build]: https://travis-ci.org/kentcdodds/react-testing-library
[coverage-badge]: https://img.shields.io/codecov/c/github/kentcdodds/react-testing-library.svg?style=flat-square
[coverage]: https://codecov.io/github/kentcdodds/react-testing-library
[version-badge]: https://img.shields.io/npm/v/react-testing-library.svg?style=flat-square
[package]: https://www.npmjs.com/package/react-testing-library
[downloads-badge]: https://img.shields.io/npm/dm/react-testing-library.svg?style=flat-square
[npmtrends]: http://www.npmtrends.com/react-testing-library
[license-badge]: https://img.shields.io/npm/l/react-testing-library.svg?style=flat-square
[license]: https://github.com/testing-library/react-testing-library/blob/master/LICENSE
[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[prs]: http://makeapullrequest.com
[donate-badge]: https://img.shields.io/badge/$-support-green.svg?style=flat-square
[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
[coc]: https://github.com/testing-library/react-testing-library/blob/master/CODE_OF_CONDUCT.md
[github-watch-badge]: https://img.shields.io/github/watchers/kentcdodds/react-testing-library.svg?style=social
[github-watch]: https://github.com/testing-library/react-testing-library/watchers
[github-star-badge]: https://img.shields.io/github/stars/kentcdodds/react-testing-library.svg?style=social
[github-star]: https://github.com/testing-library/react-testing-library/stargazers
[twitter]: https://twitter.com/intent/tweet?text=Check%20out%20react-testing-library%20by%20%40kentcdodds%20https%3A%2F%2Fgithub.com%2Fkentcdodds%2Freact-testing-library%20%F0%9F%91%8D
[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/testing-library/react-testing-library.svg?style=social
[emojis]: https://github.com/kentcdodds/all-contributors#emoji-key
[all-contributors]: https://github.com/kentcdodds/all-contributors
[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/testing-library/dom-testing-library#textmatch
[bugs]: https://github.com/testing-library/react-testing-library/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc
[requests]: https://github.com/testing-library/react-testing-library/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen
[good-first-issue]: https://github.com/testing-library/react-testing-library/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+
Expand Down
53 changes: 46 additions & 7 deletions docs/dom-testing-library/api-async.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,33 @@
---
id: api-async
title: Async Utilities
title: Async Methods
---

Several utilities are provided for dealing with asynchronous code. These can be
useful to wait for an element to appear or disappear in response to an action.
(See the [guide to testing disappearance](guide-disappearance.mdx).)
useful to wait for an element to appear or disappear in response to an event,
user action, timeout, or Promise. (See the
[guide to testing disappearance](guide-disappearance.mdx).)

All the async utils are built on top of `waitFor`.
The async methods return Promises, so be sure to use `await` or `.then` when
calling them.

## `findBy` Queries

`findBy` methods are a combination of `getBy`
[queries](queries/about.mdx#types-of-queries) and [`waitFor`](#waitfor). They
accept the waitFor options as the last argument (i.e.
`await screen.findByText('text', queryOptions, waitForOptions)`).

`findBy` queries work when you expect an element to appear but the change to the
DOM might not happen immediately.

```js
const button = screen.getByRole('button', { name: 'Click Me' })
fireEvent.click(button)
await screen.findByText('Clicked once')
fireEvent.click(button)
await screen.findByText('Clicked twice')
```

## `waitFor`

Expand Down Expand Up @@ -122,7 +142,20 @@ waitForElementToBeRemoved(() => getByText(/not here/i)).catch((err) =>

The options object is forwarded to `waitFor`.

## `wait` (DEPRECATED, use waitFor instead)
## Deprecated Methods

`wait`, `waitForDomChange`, and `waitForElement` have been combined into the
`waitFor` method

<details>

<br />

<summary>Deprecated Methods</summary>

### `wait`

> (DEPRECATED, use waitFor instead)

```typescript
function wait<T>(
Expand All @@ -144,7 +177,9 @@ Unlike wait, the callback parameter is mandatory in waitFor. Although you can
migrate an existing `wait()` call to `waitFor( () => {} )`, it is considered bad
practice to use an empty callback because it will make the tests more fragile.

## `waitForDomChange` (DEPRECATED, use waitFor instead)
### `waitForDomChange`

> (DEPRECATED, use waitFor instead)

```typescript
function waitForDomChange<T>(options?: {
Expand Down Expand Up @@ -205,7 +240,9 @@ will detect additions and removals of child elements (including text nodes) in
the `container` and any of its descendants. It will also detect attribute
changes.

## `waitForElement` (DEPRECATED, use `find*` queries or `waitFor`)
### `waitForElement`

> (DEPRECATED, use `find*` queries or `waitFor`)

```typescript
function waitForElement<T>(
Expand Down Expand Up @@ -263,3 +300,5 @@ The default `mutationObserverOptions` is
will detect additions and removals of child elements (including text nodes) in
the `container` and any of its descendants. It will also detect attribute
changes.

</details>
55 changes: 31 additions & 24 deletions docs/dom-testing-library/api-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,31 +61,35 @@ configure({ testIdAttribute: 'data-my-test-id' })
## Configuration options:

### `computedStyleSupportsPseudoElements`
Set to `true` if `window.getComputedStyle` supports pseudo-elements i.e. a second argument. If
you're using testing-library in a browser you almost always want to set this to
`true`. Only very old browser don't support this property (such as IE 8 and
earlier). However, `jsdom` does not support the second argument currently. This
includes versions of `jsdom` prior to `16.4.0` and any version that logs a
`not implemented` warning when calling `getComputedStyle` with a second argument
e.g. `window.getComputedStyle(document.createElement('div'), '::after')`.
Defaults to `false`

Set to `true` if `window.getComputedStyle` supports pseudo-elements i.e. a
second argument. If you're using testing-library in a browser you almost always
want to set this to `true`. Only very old browser don't support this property
(such as IE 8 and earlier). However, `jsdom` does not support the second
argument currently. This includes versions of `jsdom` prior to `16.4.0` and any
version that logs a `not implemented` warning when calling `getComputedStyle`
with a second argument e.g.
`window.getComputedStyle(document.createElement('div'), '::after')`. Defaults to
`false`

### `defaultHidden`

The default value for the `hidden` option used by
[`getByRole`](api-queries.mdx#byrole). Defaults to `false`.

### `showOriginalStackTrace`
By default, `waitFor` will ensure that the stack trace
for errors thrown by Testing Library is cleaned up and shortened so it's easier
for you to identify the part of your code that resulted in the error (async
stack traces are hard to debug). If you want to disable this, then
set`showOriginalStackTrace` to `false`. You can also disable this for a specific
call in the options you pass to `waitFor`.

By default, `waitFor` will ensure that the stack trace for errors thrown by
Testing Library is cleaned up and shortened so it's easier for you to identify
the part of your code that resulted in the error (async stack traces are hard to
debug). If you want to disable this, then set`showOriginalStackTrace` to
`false`. You can also disable this for a specific call in the options you pass
to `waitFor`.

### `throwSuggestions` (experimental)
When enabled, if [better queries](https://testing-library.com/docs/guide-which-query) are
available the test will fail and provide a suggested query to use instead.
Default to `false`.

When enabled, if [better queries](queries/about.mdx#priority) are available the
test will fail and provide a suggested query to use instead. Default to `false`.

To disable a suggestion for a single query just add `{suggest:false}` as an
option.
Expand All @@ -95,14 +99,17 @@ screen.getByTestId('foo', { suggest: false }) // will not throw a suggestion
```

### `testIdAttribute`
The attribute used by [`getByTestId`](api-queries.mdx#bytestid) and related queries. Defaults to
`data-testid`.

The attribute used by [`getByTestId`](api-queries.mdx#bytestid) and related
queries. Defaults to `data-testid`.

### `getElementError`
A function that returns the error used when
[`getBy*`](api-queries.mdx#getby) or [`getAllBy*`](api-queries.mdx#getallby)
fail. Takes the error message and container object as arguments.

A function that returns the error used when [`getBy*`](api-queries.mdx#getby) or
[`getAllBy*`](api-queries.mdx#getallby) fail. Takes the error message and
container object as arguments.

### `asyncUtilTimeout`
The global timeout value in milliseconds used by `waitFor`
utilities. Defaults to 1000ms.

The global timeout value in milliseconds used by `waitFor` utilities. Defaults
to 1000ms.
10 changes: 6 additions & 4 deletions docs/dom-testing-library/api-helpers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,8 @@ could do:
```js
import { within } from '@testing-library/dom'

const { getByText } = within(document.getElementById('messages'))
const helloMessage = getByText('hello')
const messages = document.getElementById('messages')
const helloMessage = within(messages).getByText('hello')
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

way more clear 👌

```

</TabItem>
Expand All @@ -167,7 +167,9 @@ cy.get('form').within(() => {
</TabItem>
</Tabs>

## `getRoles`
## Accessibility

### `getRoles`

This function allows iteration over the implicit ARIA roles represented in a
given tree of DOM nodes.
Expand Down Expand Up @@ -197,7 +199,7 @@ console.log(getRoles(nav))
// }
```

## `isInaccessible`
### `isInaccessible`

This function will compute if the given element should be excluded from the
accessibility API by the browser. It implements every **MUST** criteria from the
Expand Down
Loading