From 5174511e1807acb09d30702e90497069f6ea3ccb Mon Sep 17 00:00:00 2001 From: eps1lon Date: Sun, 20 Jun 2021 10:00:46 +0200 Subject: [PATCH 1/3] docs(dom): Document breaking changes of v8 --- docs/dom-testing-library/api-async.mdx | 167 +-------------------- docs/dom-testing-library/api-debugging.mdx | 4 + 2 files changed, 7 insertions(+), 164 deletions(-) diff --git a/docs/dom-testing-library/api-async.mdx b/docs/dom-testing-library/api-async.mdx index c5ea3ce4d..4115ff5e4 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 constraint 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..781461683 100644 --- a/docs/dom-testing-library/api-debugging.mdx +++ b/docs/dom-testing-library/api-debugging.mdx @@ -51,6 +51,7 @@ It is defined as: ```typescript function prettyDOM( + filterNode?: (node: Node) => boolean, node: HTMLElement, maxLength?: number, options?: Options @@ -63,6 +64,9 @@ 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) of `pretty-format`. +By default, `