dom-testing-library - npm Package Compare versions

Comparing version 3.9.0 to 3.10.0

dist/index.js

@@ -44,2 +44,14 @@ 'use strict';
 
+var _waitForDomChange = require('./wait-for-dom-change');
+
+Object.keys(_waitForDomChange).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _waitForDomChange[key];
+    }
+  });
+});
+
 var _matches = require('./matches');
@@ -46,0 +58,0 @@

dist/wait-for-element.js

@@ -10,5 +10,3 @@ 'use strict';
 
-function waitForElement() {
-  var callback = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : undefined;
-
+function waitForElement(callback) {
   var _ref = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
@@ -28,6 +26,9 @@ _ref$container = _ref.container,
   return new Promise(function (resolve, reject) {
-    // Disabling eslint prefer-const below: either prefer-const or no-use-before-define triggers.
-    var lastError = void 0,
-        observer = void 0,
-        timer = void 0; // eslint-disable-line prefer-const
+    if (typeof callback !== 'function') {
+      reject('waitForElement requires a callback as the first parameter');
+    }
+    var lastError = void 0;
+    var timer = setTimeout(onTimeout, timeout);
+    var observer = new window.MutationObserver(onMutation);
+    observer.observe(container, mutationObserverOptions);
     function onDone(error, result) {
@@ -45,6 +46,2 @@ clearTimeout(timer);
     function onMutation() {
-      if (callback === undefined) {
-        onDone(null, undefined);
-        return;
-      }
       try {
@@ -65,8 +62,3 @@ var result = callback();
     }
-    timer = setTimeout(onTimeout, timeout);
-    observer = new window.MutationObserver(onMutation);
-    observer.observe(container, mutationObserverOptions);
-    if (callback !== undefined) {
-      onMutation();
-    }
+    onMutation();
   });
@@ -73,0 +65,0 @@ }

package.json

 {
   "name": "dom-testing-library",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "Simple and complete DOM testing utilities that encourage good testing practices.",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

README.md

@@ -19,3 +19,3 @@ <div align="center">
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-33-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-35-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs]
@@ -86,3 +86,5 @@ [![Code of Conduct][coc-badge]][coc]
   - [`waitForElement`](#waitforelement)
+  - [`waitForDomChange`](#waitfordomchange)
   - [`fireEvent`](#fireevent)
+  - [`getNodeText`](#getnodetext)
 - [Custom Jest Matchers](#custom-jest-matchers)
@@ -317,3 +319,3 @@ - [Using other assertion libraries](#using-other-assertion-libraries)
 // <a href="/about">About ℹ️</a>
-const aboutAnchorNode = getByText(container, 'about')
+const aboutAnchorNode = getByText(container, /about/i)
 ```
@@ -498,3 +500,3 @@
 function waitForElement<T>(
-  callback?: () => T | null | undefined,
+  callback: () => T,
   options?: {
@@ -509,5 +511,4 @@ container?: HTMLElement
 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).
+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:
@@ -544,5 +545,59 @@
 
-The default `callback` is a no-op function (used like `await waitForElement()`). This can
-be helpful if you only need to wait for the next DOM change (see [`mutationObserverOptions`](#mutationobserveroptions) to learn which changes are detected).
+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).
+
+<a name="mutationobserveroptions"></a>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.
+
+### `waitForDomChange`
+
+```typescript
+function waitForDomChange<T>(options?: {
+  container?: HTMLElement
+  timeout?: number
+  mutationObserverOptions?: MutationObserverInit
+}): Promise<T>
+```
+
+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
+*/
+```
+
+Using [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) is more efficient than polling the DOM at regular intervals with `wait`. This library sets up a [`'mutationobserver-shim'`](https://github.com/megawac/MutationObserver.js) on the global `window` object for cross-platform compatibility with older browsers and the [`jsdom`](https://github.com/jsdom/jsdom/issues/639) that is usually used in Node-based tests.
+
 The default `container` is the global `document`. Make sure the elements you wait for will be attached to it, or set a different `container`.
@@ -612,3 +667,3 @@
 
-#### `getNodeText`
+### `getNodeText`
 
@@ -1010,3 +1065,3 @@ ```typescript
 | [<img src="https://avatars2.githubusercontent.com/u/21689428?v=4" width="100px;"/><br /><sub><b>Jonathan Stoye</b></sub>](http://jonathanstoye.de)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=JonathanStoye "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/4126644?v=4" width="100px;"/><br /><sub><b>Sanghyeon Lee</b></sub>](https://github.com/yongdamsh)<br />[💡](#example-yongdamsh "Examples") | [<img src="https://avatars3.githubusercontent.com/u/8015514?v=4" width="100px;"/><br /><sub><b>Justice Mba </b></sub>](https://github.com/Dajust)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=Dajust "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=Dajust "Documentation") [🤔](#ideas-Dajust "Ideas, Planning, & Feedback") | [<img src="https://avatars3.githubusercontent.com/u/340761?v=4" width="100px;"/><br /><sub><b>Wayne Crouch</b></sub>](https://github.com/wgcrouch)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=wgcrouch "Code") | [<img src="https://avatars1.githubusercontent.com/u/4996462?v=4" width="100px;"/><br /><sub><b>Ben Elliott</b></sub>](http://benjaminelliott.co.uk)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=benelliott "Code") | [<img src="https://avatars3.githubusercontent.com/u/577921?v=4" width="100px;"/><br /><sub><b>Ruben Costa</b></sub>](http://nuances.co)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=rubencosta "Code") | [<img src="https://avatars2.githubusercontent.com/u/4982001?v=4" width="100px;"/><br /><sub><b>Robert Smith</b></sub>](http://rbrtsmith.com/)<br />[🐛](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Arbrtsmith "Bug reports") [🤔](#ideas-rbrtsmith "Ideas, Planning, & Feedback") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=rbrtsmith "Documentation") |
-| [<img src="https://avatars3.githubusercontent.com/u/881986?v=4" width="100px;"/><br /><sub><b>dadamssg</b></sub>](https://github.com/dadamssg)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=dadamssg "Code") | [<img src="https://avatars1.githubusercontent.com/u/186971?v=4" width="100px;"/><br /><sub><b>Neil Kistner</b></sub>](https://neilkistner.com/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=wyze "Code") | [<img src="https://avatars3.githubusercontent.com/u/1448597?v=4" width="100px;"/><br /><sub><b>Ben Chauvette</b></sub>](http://bdchauvette.net/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=bdchauvette "Code") | [<img src="https://avatars2.githubusercontent.com/u/777527?v=4" width="100px;"/><br /><sub><b>Jeff Baumgardt</b></sub>](https://github.com/JeffBaumgardt)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=JeffBaumgardt "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=JeffBaumgardt "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/4658208?v=4" width="100px;"/><br /><sub><b>Matan Kushner</b></sub>](http://matchai.me)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Documentation") [🤔](#ideas-matchai "Ideas, Planning, & Feedback") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Tests") |
+| [<img src="https://avatars3.githubusercontent.com/u/881986?v=4" width="100px;"/><br /><sub><b>dadamssg</b></sub>](https://github.com/dadamssg)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=dadamssg "Code") | [<img src="https://avatars1.githubusercontent.com/u/186971?v=4" width="100px;"/><br /><sub><b>Neil Kistner</b></sub>](https://neilkistner.com/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=wyze "Code") | [<img src="https://avatars3.githubusercontent.com/u/1448597?v=4" width="100px;"/><br /><sub><b>Ben Chauvette</b></sub>](http://bdchauvette.net/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=bdchauvette "Code") | [<img src="https://avatars2.githubusercontent.com/u/777527?v=4" width="100px;"/><br /><sub><b>Jeff Baumgardt</b></sub>](https://github.com/JeffBaumgardt)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=JeffBaumgardt "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=JeffBaumgardt "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/4658208?v=4" width="100px;"/><br /><sub><b>Matan Kushner</b></sub>](http://matchai.me)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Documentation") [🤔](#ideas-matchai "Ideas, Planning, & Feedback") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Tests") | [<img src="https://avatars2.githubusercontent.com/u/5779538?v=4" width="100px;"/><br /><sub><b>Alex Wendte</b></sub>](http://www.wendtedesigns.com/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=themostcolm "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=themostcolm "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=themostcolm "Tests") | [<img src="https://avatars0.githubusercontent.com/u/2196208?v=4" width="100px;"/><br /><sub><b>Tamas Fodor</b></sub>](https://github.com/ruffle1986)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=ruffle1986 "Documentation") |
 
@@ -1013,0 +1068,0 @@ <!-- ALL-CONTRIBUTORS-LIST:END -->

typings/wait-for-element.d.ts

 export function waitForElement<T>(
-  callback?: () => T,
+  callback: () => T,
   options?: {
@@ -8,2 +8,2 @@ container?: HTMLElement
   },
-): Promise<T | undefined>
+): Promise<T>

No alert changes

Improved metrics

Total package byte prevSize

457327

increased by1.6%

Number of package files

30

increased by7.14%

Lines of code

5111

increased by1.51%

Number of lines in readme file

1098

increased by5.27%

No dependency changes