diff --git a/README.md b/README.md
index 59650138..ca84035d 100644
--- a/README.md
+++ b/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
+//
+const lastNameInput = getByValue('Norris')
+```
+
### `getByTestId`
```typescript
diff --git a/src/__tests__/__snapshots__/element-queries.js.snap b/src/__tests__/__snapshots__/element-queries.js.snap
index 825e4813..d2953868 100644
--- a/src/__tests__/__snapshots__/element-queries.js.snap
+++ b/src/__tests__/__snapshots__/element-queries.js.snap
@@ -48,6 +48,14 @@ exports[`get throws a useful error message 6`] = `
[36m[39m"
`;
+exports[`get throws a useful error message 7`] = `
+"Unable to find an element with the value: LucyRicardo.
+
+[36m
[39m
+ [36m[39m
+[36m
[39m"
+`;
+
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.
diff --git a/src/__tests__/element-queries.js b/src/__tests__/element-queries.js
index 9d30029d..d2fea09d 100644
--- a/src/__tests__/element-queries.js
+++ b/src/__tests__/element-queries.js
@@ -24,6 +24,7 @@ test('get throws a useful error message', () => {
getByTestId,
getByAltText,
getByTitle,
+ getByValue,
} = render('')
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(`
+
+
+
+
+
+ `)
+
+ expect(queryByValue('Norris').placeholder).toEqual('lastname')
+ expect(getByValue('Norris').placeholder).toEqual('lastname')
+})
+
test('can get elements by data-testid attribute', () => {
const {queryByTestId} = render(``)
expect(queryByTestId('firstName')).toBeInTheDOM()
diff --git a/src/queries.js b/src/queries.js
index f7b8e806..9f648b73 100644
--- a/src/queries.js
+++ b/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] */