diff --git a/docs/dom-testing-library/api-async.mdx b/docs/dom-testing-library/api-async.mdx index c5ea3ce4d..156b44725 100644 --- a/docs/dom-testing-library/api-async.mdx +++ b/docs/dom-testing-library/api-async.mdx @@ -55,7 +55,8 @@ await waitFor(() => expect(mockAPI).toHaveBeenCalledTimes(1)) // ... ``` -`waitFor` may run the callback a variable number of times. +`waitFor` may run the callback a number of times until the timeout is reached. +Note that the number of calls is constrained by the `timeout` and `interval` options. This can be useful if you have a unit test that mocks API calls and you need to wait for your mock promises to all resolve. @@ -71,8 +72,7 @@ wait for are descendants of `container`. The default `interval` is `50ms`. However it will run your callback immediately before starting the intervals. -The default `timeout` is `1000ms` which will keep you under -[Jest's default timeout of `5000ms`](https://jestjs.io/docs/en/jest-object.html#jestsettimeouttimeout). +The default `timeout` is `1000ms`. The default `onTimeout` takes the error and appends the `container`'s printed state to the error message which should hopefully make it easier to track down @@ -141,164 +141,3 @@ waitForElementToBeRemoved(() => getByText(/not here/i)).catch((err) => ``` The options object is forwarded to `waitFor`. - -## Deprecated Methods - -`wait`, `waitForDomChange`, and `waitForElement` have been combined into the -`waitFor` method. - -
- -
- -Deprecated Methods - -### `wait` - -> (DEPRECATED, use `waitFor` instead) - -```typescript -function wait( - callback: () => void, - options?: { - container?: HTMLElement - timeout?: number - interval?: number - mutationObserverOptions?: MutationObserverInit - } -): Promise -``` - -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) - -```typescript -function waitForDomChange(options?: { - container?: HTMLElement - timeout?: number - mutationObserverOptions?: MutationObserverInit -}): Promise -``` - -When in need to wait for the DOM to change you can use `waitForDomChange`. The -`waitForDomChange` function is a small wrapper around the -[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver). - -Here is an example where the promise will be resolved because the container is -changed: - -```javascript -const container = document.createElement('div') -waitForDomChange({ container }) - .then(() => console.log('DOM changed!')) - .catch((err) => console.log(`Error you need to deal with: ${err}`)) -container.append(document.createElement('p')) -// if 👆 was the only code affecting the container and it was not run, -// waitForDomChange would throw an error -``` - -The promise will resolve with a -[`mutationsList`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/MutationObserver) -which you can use to determine what kind of a change (or changes) affected the -container - -```javascript -const container = document.createElement('div') -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}` - ) -}) -container.setAttribute('data-cool', 'false') -/* - logs: - was cool: true - currently cool: false -*/ -``` - -The default `container` is the global `document`. Make sure the elements you -wait for are descendants of `container`. - -The default `timeout` is `1000ms` which will keep you under -[Jest's default timeout of `5000ms`](https://jestjs.io/docs/en/jest-object.html#jestsettimeouttimeout). - -The default `mutationObserverOptions` is -`{subtree: true, childList: true, attributes: true, characterData: true}` which -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 -function waitForElement( - callback: () => T, - options?: { - container?: HTMLElement - timeout?: number - mutationObserverOptions?: MutationObserverInit - } -): Promise -``` - -When in need to wait for DOM elements to appear, disappear, or change you can -use `waitForElement`. The `waitForElement` function is a small wrapper around -the -[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver). - -Here's a simple example: - -```javascript -// ... -// Wait until the callback does not throw an error and returns a truthy value. In this case, that means -// it'll wait until we can get a form control with a label that matches "username". -// Previously, the difference from `wait` is that rather than running your callback on -// an interval, it's run as soon as there are DOM changes in the container -// and returns the value returned by the callback. -const usernameElement = await waitForElement( - () => getByLabelText(container, 'username'), - { container } -) -usernameElement.value = 'chucknorris' -// ... -``` - -You can also wait for multiple elements at once: - -```javascript -const [usernameElement, passwordElement] = await waitForElement( - () => [ - getByLabelText(container, 'username'), - getByLabelText(container, 'password'), - ], - { container } -) -``` - -The default `container` is the global `document`. Make sure the elements you -wait for will be attached to it, or set a different `container`. - -The default `timeout` is `4500ms` which will keep you under -[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout). - -The default `mutationObserverOptions` is -`{subtree: true, childList: true, attributes: true, characterData: true}` which -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. - -
diff --git a/docs/dom-testing-library/api-debugging.mdx b/docs/dom-testing-library/api-debugging.mdx index b68e5c1bb..d06fde88c 100644 --- a/docs/dom-testing-library/api-debugging.mdx +++ b/docs/dom-testing-library/api-debugging.mdx @@ -50,6 +50,10 @@ tree of a node. This can be helpful for instance when debugging tests. It is defined as: ```typescript +interface Options extends prettyFormat.OptionsReceived { + filterNode?: (node: Node) => boolean; +} + function prettyDOM( node: HTMLElement, maxLength?: number, @@ -59,10 +63,13 @@ function prettyDOM( It receives the root node to print out, an optional extra parameter to limit the size of the resulting string, for cases when it becomes too large. It has a last -parameter which allows you to configure your formatting as defined in the -[options](https://github.com/facebook/jest/tree/master/packages/pretty-format#usage-with-options) +parameter which allows you to configure your formatting. +In addition to the options listed you can also pass the [options](https://github.com/facebook/jest/tree/master/packages/pretty-format#usage-with-options) of `pretty-format`. +By default, `