Skip to content
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

Jump to bottom

Update waitForElementToBeRemoved docs #500

Merged
merged 1 commit into from
Jun 20, 2020
Merged

Update waitForElementToBeRemoved docs #500

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
46 changes: 27 additions & 19 deletions docs/dom-testing-library/api-async.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ function waitFor<T>(
): Promise<T>
```

When in need to wait for any period of time you can use `waitFor`, to wait for your
expectations to pass. Here's a simple example:
When in need to wait for any period of time you can use `waitFor`, to wait for
your expectations to pass. Here's a simple example:

```javascript
// ...
Expand Down Expand Up @@ -63,24 +63,24 @@ function waitForElementToBeRemoved<T>(
interval?: number
mutationObserverOptions?: MutationObserverInit
}
): Promise<T>
): Promise<void>
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Intended change here!

```

To wait for the removal of element(s) from the DOM you can use
`waitForElementToBeRemoved`. The `waitForElementToBeRemoved` function is a small
wrapper around the `wait` utility.
wrapper around the `waitFor` utility.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

And here!


The first argument must be an element, array of elements, or a callback which returns
an element or array of elements.
The first argument must be an element, array of elements, or a callback which
returns an element or array of elements.

Here is an example where the promise resolves with `true` because the element is
removed:
Here is an example where the promise resolves because the element is removed:
Copy link
Contributor Author

Choose a reason for hiding this comment

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

And here (that's it!)


```javascript
const el = document.querySelector('div.getOuttaHere')

waitForElementToBeRemoved(document.querySelector('div.getOuttaHere'))
.then(() => console.log('Element no longer in DOM'))
waitForElementToBeRemoved(document.querySelector('div.getOuttaHere')).then(() =>
console.log('Element no longer in DOM')
)

el.setAttribute('data-neat', true)
// other mutations are ignored...
Expand All @@ -94,9 +94,15 @@ or an empty array:

```javascript
waitForElementToBeRemoved(null).catch(err => console.log(err))
waitForElementToBeRemoved(queryByText(/not here/i)).catch(err => console.log(err))
waitForElementToBeRemoved(queryAllByText(/not here/i)).catch(err => console.log(err))
waitForElementToBeRemoved(() => getByText(/not here/i)).catch(err => console.log(err))
waitForElementToBeRemoved(queryByText(/not here/i)).catch(err =>
console.log(err)
)
waitForElementToBeRemoved(queryAllByText(/not here/i)).catch(err =>
console.log(err)
)
waitForElementToBeRemoved(() => getByText(/not here/i)).catch(err =>
console.log(err)
)

// Error: The element(s) given to waitForElementToBeRemoved are already removed. waitForElementToBeRemoved requires that the element(s) exist(s) before waiting for removal.
```
Expand All @@ -116,9 +122,14 @@ function wait<T>(
}
): Promise<T>
```
Previously, wait was a wrapper around wait-for-expect and used polling instead of a MutationObserver to look for changes. It is now an alias to waitFor and will be removed in a future release.

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.
Previously, wait was a wrapper around wait-for-expect and used polling instead
of a MutationObserver to look for changes. It is now an alias to waitFor and
will be removed in a future release.

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)

Expand Down Expand Up @@ -158,9 +169,7 @@ container.setAttribute('data-cool', 'true')
waitForDomChange({ container }).then(mutationsList => {
const mutation = mutationsList[0]
console.log(
`was cool: ${mutation.oldValue}\ncurrently cool: ${
mutation.target.dataset.cool
}`
`was cool: ${mutation.oldValue}\ncurrently cool: ${mutation.target.dataset.cool}`
)
})
container.setAttribute('data-cool', 'false')
Expand All @@ -183,7 +192,6 @@ 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`)

```typescript
Expand Down