dom-testing-library - npm Package Compare versions

Comparing version 1.9.0 to 1.10.0

dist/queries.js

@@ -6,3 +6,3 @@ 'use strict';
 });
-exports.getByTestId = exports.queryByTestId = exports.getByAltText = exports.queryByAltText = exports.getByLabelText = exports.queryByLabelText = exports.getByText = exports.queryByText = exports.getByPlaceholderText = exports.queryByPlaceholderText = undefined;
+exports.getAllByTestId = exports.getByTestId = exports.queryAllByTestId = exports.queryByTestId = exports.getAllByAltText = exports.getByAltText = exports.queryAllByAltText = exports.queryByAltText = exports.getAllByLabelText = exports.getByLabelText = exports.queryAllByLabelText = exports.queryByLabelText = exports.getAllByText = exports.getByText = exports.queryAllByText = exports.queryByText = exports.getAllByPlaceholderText = exports.getByPlaceholderText = exports.queryAllByPlaceholderText = exports.queryByPlaceholderText = undefined;
 
@@ -23,9 +23,19 @@ var _matches = require('./matches');
 
-function queryLabelByText(container, text) {
-  return Array.from(container.querySelectorAll('label')).find(function (label) {
+function firstResultOrNull(queryFunction) {
+  for (var _len = arguments.length, args = Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+    args[_key - 1] = arguments[_key];
+  }
+
+  var result = queryFunction.apply(undefined, args);
+  if (result.length === 0) return null;
+  return result[0];
+}
+
+function queryAllLabelsByText(container, text) {
+  return Array.from(container.querySelectorAll('label')).filter(function (label) {
     return (0, _matches.matches)(label.textContent, label, text);
-  }) || null;
+  });
 }
 
-function queryByLabelText(container, text) {
+function queryAllByLabelText(container, text) {
   var _ref = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {},
@@ -35,28 +45,35 @@ _ref$selector = _ref.selector,
 
-  var label = queryLabelByText(container, text);
-  if (!label) {
-    return queryByAttribute('aria-label', container, text);
-  }
-  /* istanbul ignore if */
-  if (label.control) {
-    // appears to be unsupported in jsdom: https://github.com/jsdom/jsdom/issues/2175
-    // but this would be the proper way to do things
-    return label.control;
-  } else if (label.getAttribute('for')) {
-    // we're using this notation because with the # selector we would have to escape special characters e.g. user.name
-    // see https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#Escaping_special_characters
-    // <label for="someId">text</label><input id="someId" />
-    return container.querySelector(`[id="${label.getAttribute('for')}"]`);
-  } else if (label.getAttribute('id')) {
-    // <label id="someId">text</label><input aria-labelledby="someId" />
-    return container.querySelector(`[aria-labelledby="${label.getAttribute('id')}"]`);
-  } else if (label.childNodes.length) {
-    // <label>text: <input /></label>
-    return label.querySelector(selector);
-  } else {
-    return null;
-  }
+  var labels = queryAllLabelsByText(container, text);
+  var labelledElements = labels.map(function (label) {
+    /* istanbul ignore if */
+    if (label.control) {
+      // appears to be unsupported in jsdom: https://github.com/jsdom/jsdom/issues/2175
+      // but this would be the proper way to do things
+      return label.control;
+    } else if (label.getAttribute('for')) {
+      // we're using this notation because with the # selector we would have to escape special characters e.g. user.name
+      // see https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#Escaping_special_characters
+      // <label for="someId">text</label><input id="someId" />
+      return container.querySelector(`[id="${label.getAttribute('for')}"]`);
+    } else if (label.getAttribute('id')) {
+      // <label id="someId">text</label><input aria-labelledby="someId" />
+      return container.querySelector(`[aria-labelledby="${label.getAttribute('id')}"]`);
+    } else if (label.childNodes.length) {
+      // <label>text: <input /></label>
+      return label.querySelector(selector);
+    } else {
+      return null;
+    }
+  }).filter(function (label) {
+    return label !== null;
+  }).concat(queryAllByAttribute('aria-label', container, text));
+
+  return labelledElements;
 }
 
-function queryByText(container, text) {
+function queryByLabelText(container, text, opts) {
+  return firstResultOrNull(queryAllByLabelText, container, text, opts);
+}
+
+function queryAllByText(container, text) {
   var _ref2 = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {},
@@ -66,18 +83,40 @@ _ref2$selector = _ref2.selector,
 
-  return Array.from(container.querySelectorAll(selector)).find(function (node) {
+  return Array.from(container.querySelectorAll(selector)).filter(function (node) {
     return (0, _matches.matches)((0, _getNodeText.getNodeText)(node), node, text);
-  }) || null;
+  });
 }
 
+function queryByText(container, text, opts) {
+  return firstResultOrNull(queryAllByText, container, text, opts);
+}
+
 // this is just a utility and not an exposed query.
 // There are no plans to expose this.
-function queryByAttribute(attribute, container, text) {
-  return Array.from(container.querySelectorAll(`[${attribute}]`)).find(function (node) {
+function queryAllByAttribute(attribute, container, text) {
+  return Array.from(container.querySelectorAll(`[${attribute}]`)).filter(function (node) {
     return (0, _matches.matches)(node.getAttribute(attribute), node, text);
-  }) || null;
+  });
 }
 
+// this is just a utility and not an exposed query.
+// There are no plans to expose this.
+function queryByAttribute(attribute, container, text) {
+  return firstResultOrNull(queryAllByAttribute, attribute, container, text);
+}
+
 var queryByPlaceholderText = queryByAttribute.bind(null, 'placeholder');
+var queryAllByPlaceholderText = queryAllByAttribute.bind(null, 'placeholder');
 var queryByTestId = queryByAttribute.bind(null, 'data-testid');
+var queryAllByTestId = queryAllByAttribute.bind(null, 'data-testid');
 
+function queryAllByAltText(container, alt) {
+  return Array.from(container.querySelectorAll('img,input,area')).filter(function (node) {
+    return (0, _matches.matches)(node.getAttribute('alt'), node, alt);
+  });
+}
+
+function queryByAltText(container, alt) {
+  return firstResultOrNull(queryAllByAltText, container, alt);
+}
+
 // getters
@@ -88,35 +127,51 @@ // the reason we're not dynamically generating these functions that look so similar:
 
-function getByTestId(container, id) {
-  for (var _len = arguments.length, rest = Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) {
-    rest[_key - 2] = arguments[_key];
+function getAllByTestId(container, id) {
+  for (var _len2 = arguments.length, rest = Array(_len2 > 2 ? _len2 - 2 : 0), _key2 = 2; _key2 < _len2; _key2++) {
+    rest[_key2 - 2] = arguments[_key2];
   }
 
-  var el = queryByTestId.apply(undefined, [container, id].concat(rest));
-  if (!el) {
+  var els = queryAllByTestId.apply(undefined, [container, id].concat(rest));
+  if (!els.length) {
     throw new Error(`Unable to find an element by: [data-testid="${id}"] \n\n${debugDOM(container)}`);
   }
-  return el;
+  return els;
 }
 
-function getByPlaceholderText(container, text) {
-  for (var _len2 = arguments.length, rest = Array(_len2 > 2 ? _len2 - 2 : 0), _key2 = 2; _key2 < _len2; _key2++) {
-    rest[_key2 - 2] = arguments[_key2];
+function getByTestId() {
+  for (var _len3 = arguments.length, args = Array(_len3), _key3 = 0; _key3 < _len3; _key3++) {
+    args[_key3] = arguments[_key3];
   }
 
-  var el = queryByPlaceholderText.apply(undefined, [container, text].concat(rest));
-  if (!el) {
+  return firstResultOrNull.apply(undefined, [getAllByTestId].concat(args));
+}
+
+function getAllByPlaceholderText(container, text) {
+  for (var _len4 = arguments.length, rest = Array(_len4 > 2 ? _len4 - 2 : 0), _key4 = 2; _key4 < _len4; _key4++) {
+    rest[_key4 - 2] = arguments[_key4];
+  }
+
+  var els = queryAllByPlaceholderText.apply(undefined, [container, text].concat(rest));
+  if (!els.length) {
     throw new Error(`Unable to find an element with the placeholder text of: ${text} \n\n${debugDOM(container)}`);
   }
-  return el;
+  return els;
 }
 
-function getByLabelText(container, text) {
-  for (var _len3 = arguments.length, rest = Array(_len3 > 2 ? _len3 - 2 : 0), _key3 = 2; _key3 < _len3; _key3++) {
-    rest[_key3 - 2] = arguments[_key3];
+function getByPlaceholderText() {
+  for (var _len5 = arguments.length, args = Array(_len5), _key5 = 0; _key5 < _len5; _key5++) {
+    args[_key5] = arguments[_key5];
   }
 
-  var el = queryByLabelText.apply(undefined, [container, text].concat(rest));
-  if (!el) {
-    var label = queryLabelByText(container, text);
-    if (label) {
+  return firstResultOrNull.apply(undefined, [getAllByPlaceholderText].concat(args));
+}
+
+function getAllByLabelText(container, text) {
+  for (var _len6 = arguments.length, rest = Array(_len6 > 2 ? _len6 - 2 : 0), _key6 = 2; _key6 < _len6; _key6++) {
+    rest[_key6 - 2] = arguments[_key6];
+  }
+
+  var els = queryAllByLabelText.apply(undefined, [container, text].concat(rest));
+  if (!els.length) {
+    var labels = queryAllLabelsByText(container, text);
+    if (labels.length) {
       throw new Error(`Found a label with the text of: ${text}, however no form control was found associated to that label. Make sure you're using the "for" attribute or "aria-labelledby" attribute correctly. \n\n${debugDOM(container)}`);
@@ -127,42 +182,70 @@ } else {
   }
-  return el;
+  return els;
 }
 
-function getByText(container, text) {
-  for (var _len4 = arguments.length, rest = Array(_len4 > 2 ? _len4 - 2 : 0), _key4 = 2; _key4 < _len4; _key4++) {
-    rest[_key4 - 2] = arguments[_key4];
+function getByLabelText() {
+  for (var _len7 = arguments.length, args = Array(_len7), _key7 = 0; _key7 < _len7; _key7++) {
+    args[_key7] = arguments[_key7];
   }
 
-  var el = queryByText.apply(undefined, [container, text].concat(rest));
-  if (!el) {
+  return firstResultOrNull.apply(undefined, [getAllByLabelText].concat(args));
+}
+
+function getAllByText(container, text) {
+  for (var _len8 = arguments.length, rest = Array(_len8 > 2 ? _len8 - 2 : 0), _key8 = 2; _key8 < _len8; _key8++) {
+    rest[_key8 - 2] = arguments[_key8];
+  }
+
+  var els = queryAllByText.apply(undefined, [container, text].concat(rest));
+  if (!els.length) {
     throw new Error(`Unable to find an element with the text: ${text}. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible. \n\n${debugDOM(container)}`);
   }
-  return el;
+  return els;
 }
 
-function queryByAltText(container, alt) {
-  return Array.from(container.querySelectorAll('img,input,area')).find(function (node) {
-    return (0, _matches.matches)(node.getAttribute('alt'), node, alt);
-  }) || null;
+function getByText() {
+  for (var _len9 = arguments.length, args = Array(_len9), _key9 = 0; _key9 < _len9; _key9++) {
+    args[_key9] = arguments[_key9];
+  }
+
+  return firstResultOrNull.apply(undefined, [getAllByText].concat(args));
 }
 
-function getByAltText(container, alt) {
-  var el = queryByAltText(container, alt);
-  if (!el) {
+function getAllByAltText(container, alt) {
+  var els = queryAllByAltText(container, alt);
+  if (!els.length) {
     throw new Error(`Unable to find an element with the alt text: ${alt} \n\n${debugDOM(container)}`);
   }
-  return el;
+  return els;
 }
 
+function getByAltText() {
+  for (var _len10 = arguments.length, args = Array(_len10), _key10 = 0; _key10 < _len10; _key10++) {
+    args[_key10] = arguments[_key10];
+  }
+
+  return firstResultOrNull.apply(undefined, [getAllByAltText].concat(args));
+}
+
 exports.queryByPlaceholderText = queryByPlaceholderText;
+exports.queryAllByPlaceholderText = queryAllByPlaceholderText;
 exports.getByPlaceholderText = getByPlaceholderText;
+exports.getAllByPlaceholderText = getAllByPlaceholderText;
 exports.queryByText = queryByText;
+exports.queryAllByText = queryAllByText;
 exports.getByText = getByText;
+exports.getAllByText = getAllByText;
 exports.queryByLabelText = queryByLabelText;
+exports.queryAllByLabelText = queryAllByLabelText;
 exports.getByLabelText = getByLabelText;
+exports.getAllByLabelText = getAllByLabelText;
 exports.queryByAltText = queryByAltText;
+exports.queryAllByAltText = queryAllByAltText;
 exports.getByAltText = getByAltText;
+exports.getAllByAltText = getAllByAltText;
 exports.queryByTestId = queryByTestId;
+exports.queryAllByTestId = queryAllByTestId;
 exports.getByTestId = getByTestId;
+exports.getAllByTestId = getAllByTestId;
 
 /* eslint complexity:["error", 14] */

package.json

 {
   "name": "dom-testing-library",
-  "version": "1.9.0",
+  "version": "1.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-18-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-19-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs]
@@ -87,2 +87,3 @@ [![Code of Conduct][coc-badge]][coc]
 * [`query` APIs](#query-apis)
+* [`queryAll` and `getAll` APIs](#queryall-and-getall-apis)
 * [`bindElementToQueries`](#bindelementtoqueries)
@@ -111,2 +112,4 @@ * [Debugging](#debugging)
 
+Note: each of the `get` APIs below have a matching [`getAll`](#queryall-and-getall-apis) API that returns all elements instead of just the first one, and [`query`](#query-apis)/[`getAll`](#queryall-and-getall-apis) that return `null`/`[]` instead of throwing an error.
+
 ```javascript
@@ -495,2 +498,12 @@ // src/__tests__/example.js
 
+## `queryAll` and `getAll` APIs
+
+Each of the `query` APIs have a corresponsing `queryAll` version that always returns an Array of matching nodes. `getAll` is the same but throws when the array has a length of 0.
+
+```javascript
+const submitButtons = queryAllByText(container, 'submit')
+expect(submitButtons).toHaveLength(3) // expect 3 elements
+expect(submitButtons[0]).toBeInTheDOM()
+```
+
 ## `bindElementToQueries`
@@ -718,3 +731,3 @@
 | [<img src="https://avatars1.githubusercontent.com/u/1241511?s=460&v=4" width="100px;"/><br /><sub><b>Anto Aravinth</b></sub>](https://github.com/antoaravinth)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=antoaravinth "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=antoaravinth "Tests") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=antoaravinth "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/3462296?v=4" width="100px;"/><br /><sub><b>Jonah Moses</b></sub>](https://github.com/JonahMoses)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=JonahMoses "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/4002543?v=4" width="100px;"/><br /><sub><b>Łukasz Gandecki</b></sub>](http://team.thebrain.pro)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=lgandecki "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=lgandecki "Tests") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=lgandecki "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/498274?v=4" width="100px;"/><br /><sub><b>Ivan Babak</b></sub>](https://sompylasar.github.io)<br />[🐛](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Asompylasar "Bug reports") [🤔](#ideas-sompylasar "Ideas, Planning, & Feedback") [💻](https://github.com/kentcdodds/dom-testing-library/commits?author=sompylasar "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=sompylasar "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/4439618?v=4" width="100px;"/><br /><sub><b>Jesse Day</b></sub>](https://github.com/jday3)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=jday3 "Code") | [<img src="https://avatars0.githubusercontent.com/u/15199?v=4" width="100px;"/><br /><sub><b>Ernesto García</b></sub>](http://gnapse.github.io)<br />[💬](#question-gnapse "Answering Questions") [💻](https://github.com/kentcdodds/dom-testing-library/commits?author=gnapse "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=gnapse "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/2747424?v=4" width="100px;"/><br /><sub><b>Josef Maxx Blake</b></sub>](http://jomaxx.com)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=jomaxx "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=jomaxx "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=jomaxx "Tests") |
-| [<img src="https://avatars3.githubusercontent.com/u/725236?v=4" width="100px;"/><br /><sub><b>Alex Cook</b></sub>](https://github.com/alecook)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=alecook "Documentation") [💡](#example-alecook "Examples") | [<img src="https://avatars3.githubusercontent.com/u/10348212?v=4" width="100px;"/><br /><sub><b>Daniel Cook</b></sub>](https://github.com/dfcook)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Tests") | [<img src="https://avatars2.githubusercontent.com/u/21194045?s=400&v=4" width="100px;"/><br /><sub><b>Thomas Chia</b></sub>](https://github.com/thchia)<br />[🐛](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Athchia "Bug reports") [💻](https://github.com/kentcdodds/dom-testing-library/commits?author=thchia "Code") | [<img src="https://avatars1.githubusercontent.com/u/28659384?v=4" width="100px;"/><br /><sub><b>Tim Deschryver</b></sub>](https://github.com/tdeschryver)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=tdeschryver "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=tdeschryver "Tests") |
+| [<img src="https://avatars3.githubusercontent.com/u/725236?v=4" width="100px;"/><br /><sub><b>Alex Cook</b></sub>](https://github.com/alecook)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=alecook "Documentation") [💡](#example-alecook "Examples") | [<img src="https://avatars3.githubusercontent.com/u/10348212?v=4" width="100px;"/><br /><sub><b>Daniel Cook</b></sub>](https://github.com/dfcook)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Tests") | [<img src="https://avatars2.githubusercontent.com/u/21194045?s=400&v=4" width="100px;"/><br /><sub><b>Thomas Chia</b></sub>](https://github.com/thchia)<br />[🐛](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Athchia "Bug reports") [💻](https://github.com/kentcdodds/dom-testing-library/commits?author=thchia "Code") | [<img src="https://avatars1.githubusercontent.com/u/28659384?v=4" width="100px;"/><br /><sub><b>Tim Deschryver</b></sub>](https://github.com/tdeschryver)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=tdeschryver "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=tdeschryver "Tests") | [<img src="https://avatars3.githubusercontent.com/u/1571667?v=4" width="100px;"/><br /><sub><b>Alex Krolick</b></sub>](https://alexkrolick.com)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=alexkrolick "Code") |
 
@@ -721,0 +734,0 @@ <!-- ALL-CONTRIBUTORS-LIST:END -->

No alert changes

Improved metrics

Total package byte prevSize

66662

increased by6.81%

Lines of code

767

increased by9.57%

Number of lines in readme file

767

increased by1.72%

No dependency changes