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`] = ` " `; +exports[`get throws a useful error message 7`] = ` +"Unable to find an element with the value: LucyRicardo. + +
 + 
 +
" +`; + 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] */