feat: Add toHaveDisplayValue() matcher

README.md

@@ -66,6 +66,7 @@ clear to read and to maintain.
   - [`toHaveStyle`](#tohavestyle)
   - [`toHaveTextContent`](#tohavetextcontent)
   - [`toHaveValue`](#tohavevalue)
+  - [`toHaveDisplayValue`](#tohavedisplayvalue)
   - [`toBeChecked`](#tobechecked)
 - [Deprecated matchers](#deprecated-matchers)
   - [`toBeInTheDOM`](#tobeinthedom)
@@ -765,6 +766,47 @@ expect(selectInput).not.toHaveValue(['second', 'third'])
 
 <hr />
 
+### `toHaveDisplayValue`
+
+```typescript
+toHaveDisplayValue(value: string | string[])
+```
+
+This allows you to check whether the given `<select>` element has the specified
+value.
+
+#### Examples
+
+```html
+<label for="single-select-example">Fruit</label>
+<select id="single-select-example">
+  <option value="">Select a fruit...</option>
+  <option value="banana">Banana</option>
+  <option value="ananas">Ananas</option>
+  <option value="avocado">Avocado</option>
+</select>
+
+<label for="mutiple-select-example">Fruits</label>
+<select id="multiple-select-example">
+  <option value="">Select a fruit...</option>
+  <option value="banana" selected>Banana</option>
+  <option value="ananas">Ananas</option>
+  <option value="avocado" selected>Avocado</option>
+</select>
+```
+
+##### Using DOM Testing Library
+
+```javascript
+const inputSelect = screen.getByLabelText('Fruit')
+const inputMultiple = screen.getByLabelText('Fruits')
+
+expect(inputSelect).toHaveDisplayValue('Select a fruit...')
+expect(inputMultiple).toHaveDisplayValue(['Banana', 'Avocado'])
+```
+
+<hr />
+
 ### `toBeChecked`
 
 ```typescript
@@ -940,6 +982,7 @@ Thanks goes to these people ([emoji key][emojis]):
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.

src/__tests__/to-have-display-value.js

@@ -0,0 +1,62 @@
+import {render} from './helpers/test-utils'
+
+test('it should work as expected', () => {
+  const {queryByTestId} = render(`
+    <select id="fruits" data-testid="select">
+      <option value="">Select a fruit...</option>
+      <option value="ananas">Ananas</option>
+      <option value="banana">Banana</option>
+      <option value="avocado">Avocado</option>
+    </select>
+  `)
+
+  expect(queryByTestId('select')).toHaveDisplayValue('Select a fruit...')
+  expect(queryByTestId('select')).not.toHaveDisplayValue('Banana')
+  expect(() =>
+    expect(queryByTestId('select')).not.toHaveDisplayValue('Select a fruit...'),
+  ).toThrow()
+  expect(() =>
+    expect(queryByTestId('select')).toHaveDisplayValue('Ananas'),
+  ).toThrow()
+})
+
+test('it should work with select multiple', () => {
+  const {queryByTestId} = render(`
+    <select id="fruits" data-testid="select" multiple>
+      <option value="">Select a fruit...</option>
+      <option value="ananas" selected>Ananas</option>
+      <option value="banana">Banana</option>
+      <option value="avocado" selected>Avocado</option>
+    </select>
+  `)
+
+  expect(queryByTestId('select')).toHaveDisplayValue(['Ananas', 'Avocado'])
+  expect(() =>
+    expect(queryByTestId('select')).not.toHaveDisplayValue([
+      'Ananas',
+      'Avocado',
+    ]),
+  ).toThrow()
+
+  expect(queryByTestId('select')).not.toHaveDisplayValue('Ananas')
+  expect(() =>
+    expect(queryByTestId('select')).toHaveDisplayValue('Ananas'),
+  ).toThrow()
+})
+
+test('it should throw if element is not valid', () => {
+  const {queryByTestId} = render(`
+    <input type="text" data-testid="input" value="Banana" />
+  `)
+
+  let errorMessage
+  try {
+    expect(queryByTestId('input')).toHaveDisplayValue('Banana')
+  } catch (err) {
+    errorMessage = err.message
+  }
+
+  expect(errorMessage).toMatchInlineSnapshot(
+    `".toHaveDisplayValue() currently supports select elements only, try to use .toHaveValue() or toBeChecked() instead."`,
+  )
+})

src/matchers.js

@@ -14,6 +14,7 @@ import {toBeDisabled, toBeEnabled} from './to-be-disabled'
 import {toBeRequired} from './to-be-required'
 import {toBeInvalid, toBeValid} from './to-be-invalid'
 import {toHaveValue} from './to-have-value'
+import {toHaveDisplayValue} from './to-have-display-value'
 import {toBeChecked} from './to-be-checked'
 
 export {
@@ -35,5 +36,6 @@ export {
   toBeInvalid,
   toBeValid,
   toHaveValue,
+  toHaveDisplayValue,
   toBeChecked,
 }

src/to-have-display-value.js

@@ -0,0 +1,34 @@
+import {matcherHint} from 'jest-matcher-utils'
+
+import {checkHtmlElement, getMessage} from './utils'
+
+export function toHaveDisplayValue(htmlElement, expectedValue) {
+  checkHtmlElement(htmlElement, toHaveDisplayValue, this)
+
+  if (htmlElement.tagName.toLowerCase() !== 'select') {
+    throw new Error(
+      '.toHaveDisplayValue() currently supports select elements only, try to use .toHaveValue() or toBeChecked() instead.',
+    )
+  }
+
+  const value = Array.from(htmlElement)
+    .filter(option => option.selected)
+    .map(option => option.textContent)
+    .toString()
+
+  return {
+    pass: value === expectedValue.toString(),
+    message: () =>
+      getMessage(
+        matcherHint(
+          `${this.isNot ? '.not' : ''}.toHaveDisplayValue`,
+          'element',
+          '',
+        ),
+        `Expected element ${this.isNot ? 'not ' : ''}to have display value`,
+        expectedValue,
+        'Received',
+        value,
+      ),
+  }
+}