feat(queryByValue): add get/query by value (#35)

* get/query by value

* updated test

README.md

@@ -77,6 +77,7 @@ when a real user uses it.
   * [`getByText`](#getbytext)
   * [`getByAltText`](#getbyalttext)
   * [`getByTitle`](#getbytitle)
+  * [`getByValue`](#getbyvalue)
   * [`getByTestId`](#getbytestid)
   * [`wait`](#wait)
   * [`waitForElement`](#waitforelement)
@@ -320,6 +321,26 @@ Returns the element that has the matching `title` attribute.
 const deleteElement = getByTitle(container, 'Delete')
 ```
 
+### `getByValue`
+
+```typescript
+getByValue(
+  container: HTMLElement,
+  value: TextMatch,
+  options?: {
+    exact?: boolean = true,
+    collapseWhitespace?: boolean = false,
+    trim?: boolean = true,
+  }): HTMLElement
+```
+
+Returns the element that has the matching value.
+
+```javascript
+// <input type="text" id="lastName" defaultValue="Norris" />
+const lastNameInput = getByValue('Norris')
+```
+
 ### `getByTestId`
 
 ```typescript

src/__tests__/__snapshots__/element-queries.js.snap

@@ -48,6 +48,14 @@ exports[`get throws a useful error message 6`] = `
 </div>"
 `;
 
+exports[`get throws a useful error message 7`] = `
+"Unable to find an element with the value: LucyRicardo. 
+
+<div>
+  <div />
+</div>"
+`;
+
 exports[`label with no form control 1`] = `
 "Found a label with the text of: /alone/, however no form control was found associated to that label. Make sure you're using the \\"for\\" attribute or \\"aria-labelledby\\" attribute correctly. 
 

src/__tests__/element-queries.js

@@ -24,6 +24,7 @@ test('get throws a useful error message', () => {
     getByTestId,
     getByAltText,
     getByTitle,
+    getByValue,
   } = render('<div />')
   expect(() => getByLabelText('LucyRicardo')).toThrowErrorMatchingSnapshot()
   expect(() =>
@@ -33,6 +34,7 @@ test('get throws a useful error message', () => {
   expect(() => getByTestId('LucyRicardo')).toThrowErrorMatchingSnapshot()
   expect(() => getByAltText('LucyRicardo')).toThrowErrorMatchingSnapshot()
   expect(() => getByTitle('LucyRicardo')).toThrowErrorMatchingSnapshot()
+  expect(() => getByValue('LucyRicardo')).toThrowErrorMatchingSnapshot()
 })
 
 test('can get elements by matching their text content', () => {
@@ -132,6 +134,19 @@ test('query/get element by its title', () => {
   expect(queryByTitle('Delete').id).toEqual('2')
 })
 
+test('query/get element by its value', () => {
+  const {getByValue, queryByValue} = render(`
+  <div>
+    <input placeholder="name" type="text"/>
+    <input placeholder="lastname" type="text" value="Norris"/>
+    <input placeholder="email" type="text"/>
+  </div>
+  `)
+
+  expect(queryByValue('Norris').placeholder).toEqual('lastname')
+  expect(getByValue('Norris').placeholder).toEqual('lastname')
+})
+
 test('can get elements by data-testid attribute', () => {
   const {queryByTestId} = render(`<div data-testid="firstName"></div>`)
   expect(queryByTestId('firstName')).toBeInTheDOM()

src/queries.js

@@ -112,6 +112,8 @@ const queryByTestId = queryByAttribute.bind(null, 'data-testid')
 const queryAllByTestId = queryAllByAttribute.bind(null, 'data-testid')
 const queryByTitle = queryByAttribute.bind(null, 'title')
 const queryAllByTitle = queryAllByAttribute.bind(null, 'title')
+const queryByValue = queryByAttribute.bind(null, 'value')
+const queryAllByValue = queryAllByAttribute.bind(null, 'value')
 
 function queryAllByAltText(
   container,
@@ -166,6 +168,22 @@ function getByTitle(...args) {
   return firstResultOrNull(getAllByTitle, ...args)
 }
 
+function getAllByValue(container, value, ...rest) {
+  const els = queryAllByValue(container, value, ...rest)
+  if (!els.length) {
+    throw new Error(
+      `Unable to find an element with the value: ${value}. \n\n${debugDOM(
+        container,
+      )}`,
+    )
+  }
+  return els
+}
+
+function getByValue(...args) {
+  return firstResultOrNull(getAllByValue, ...args)
+}
+
 function getAllByPlaceholderText(container, text, ...rest) {
   const els = queryAllByPlaceholderText(container, text, ...rest)
   if (!els.length) {
@@ -264,6 +282,10 @@ export {
   queryAllByTitle,
   getByTitle,
   getAllByTitle,
+  queryByValue,
+  queryAllByValue,
+  getByValue,
+  getAllByValue,
 }
 
 /* eslint complexity:["error", 14] */