docs: add docs for toHaveErrorMessage

update test cases to match example

Author: SevenOutman

README.md

@@ -75,6 +75,7 @@ clear to read and to maintain.
   - [`toBeChecked`](#tobechecked)
   - [`toBePartiallyChecked`](#tobepartiallychecked)
   - [`toHaveDescription`](#tohavedescription)
+  - [`toHaveErrorMessage`](#tohaveerrormessage)
 - [Deprecated matchers](#deprecated-matchers)
   - [`toBeInTheDOM`](#tobeinthedom)
 - [Inspiration](#inspiration)
@@ -1042,6 +1043,58 @@ expect(deleteButton).not.toHaveDescription()
 expect(deleteButton).toHaveDescription('') // Missing or empty description always becomes a blank string
 ```
 
+### `toHaveErrorMessage`
+
+```typescript
+toHaveErrorMessage(text: string | RegExp)
+```
+
+This allows you to check whether the given element has an
+[ARIA error message](https://www.w3.org/TR/wai-aria/#aria-errormessage) or not.
+
+Use the `aria-errormessage` attribute to reference another element that contains
+custom error message text. Multiple ids is **NOT** allowed. Authors MUST use
+`aria-invalid` in conjunction with `aria-errormessage`. Leran more from
+[`aria-errormessage` spec](https://www.w3.org/TR/wai-aria/#aria-errormessage).
+
+Whitespace is normalized.
+
+When a `string` argument is passed through, it will perform a whole
+case-sensitive match to the error message text.
+
+To perform a case-insensitive match, you can use a `RegExp` with the `/i`
+modifier.
+
+To perform a partial match, you can pass a `RegExp` or use
+`expect.stringContaining("partial string")`.
+
+#### Examples
+
+```html
+<label for="startTime"> Please enter a start time for the meeting: </label>
+<input
+  id="startTime"
+  type="text"
+  aria-errormessage="msgID"
+  aria-invalid="true"
+  value="11:30 PM"
+/>
+<span id="msgID" aria-live="assertive" style="visibility:visible">
+  Invalid time: the time must be between 9:00 AM and 5:00 PM"
+</span>
+```
+
+```javascript
+const timeInput = getByLabel('startTime')
+
+expect(timeInput).toHaveErrorMessage(
+  'Invalid time: the time must be between 9:00 AM and 5:00 PM',
+)
+expect(timeInput).toHaveErrorMessage(/invalid time/i) // to partially match
+expect(timeInput).toHaveErrorMessage(expect.stringContaining('Invalid time')) // to partially match
+expect(timeInput).not.toHaveErrorMessage('Pikachu!')
+```
+
 ## Deprecated matchers
 
 ### `toBeInTheDOM`

src/__tests__/to-have-errormessage.js

@@ -4,42 +4,40 @@ import {render} from './helpers/test-utils'
 describe('.toHaveErrorMessage', () => {
   test('resolves for object with correct aria-errormessage reference', () => {
     const {queryByTestId} = render(`
-    <div id="errormessage">The errormessage</div>
-    <div data-testid="invalid" aria-errormessage="errormessage" aria-invalid="true"></div>
-    <div data-testid="implicitly_invalid" aria-errormessage="errormessage" aria-invalid></div>
+    <label for="startTime"> Please enter a start time for the meeting: </label>
+    <input data-testid="startTime" type="text" aria-errormessage="msgID" aria-invalid="true" value="11:30 PM" >
+    <span id="msgID" aria-live="assertive" style="visibility:visible"> Invalid time:  the time must be between 9:00 AM and 5:00 PM </span>
     `)
 
-    // element with aria-invalid="true"
-    expect(queryByTestId('invalid')).toHaveErrorMessage('The errormessage')
-    expect(queryByTestId('invalid')).toHaveErrorMessage(
-      expect.stringContaining('The'),
-    )
-    expect(queryByTestId('invalid')).toHaveErrorMessage(/The/)
-    expect(queryByTestId('invalid')).toHaveErrorMessage(
-      expect.stringMatching(/The/),
-    )
-    expect(queryByTestId('invalid')).toHaveErrorMessage(/errormessage/)
-    expect(queryByTestId('invalid')).not.toHaveErrorMessage('Something else')
-    expect(queryByTestId('invalid')).not.toHaveErrorMessage('The')
+    const timeInput = queryByTestId('startTime')
 
-    // element with aria-invalid attribute
-    expect(queryByTestId('implicitly_invalid')).toHaveErrorMessage(
-      'The errormessage',
-    )
-    expect(queryByTestId('implicitly_invalid')).toHaveErrorMessage(
-      expect.stringContaining('The'),
-    )
-    expect(queryByTestId('implicitly_invalid')).toHaveErrorMessage(/The/)
-    expect(queryByTestId('implicitly_invalid')).toHaveErrorMessage(
-      expect.stringMatching(/The/),
-    )
-    expect(queryByTestId('implicitly_invalid')).toHaveErrorMessage(
-      /errormessage/,
+    expect(timeInput).toHaveErrorMessage(
+      'Invalid time: the time must be between 9:00 AM and 5:00 PM',
     )
-    expect(queryByTestId('implicitly_invalid')).not.toHaveErrorMessage(
-      'Something else',
+    expect(timeInput).toHaveErrorMessage(/invalid time/i) // to partially match
+    expect(timeInput).toHaveErrorMessage(
+      expect.stringContaining('Invalid time'),
+    ) // to partially match
+    expect(timeInput).not.toHaveErrorMessage('Pikachu!')
+  })
+
+  test('works correctly on implicit invalid element', () => {
+    const {queryByTestId} = render(`
+    <label for="startTime"> Please enter a start time for the meeting: </label>
+    <input data-testid="startTime" type="text" aria-errormessage="msgID" aria-invalid value="11:30 PM" >
+    <span id="msgID" aria-live="assertive" style="visibility:visible"> Invalid time:  the time must be between 9:00 AM and 5:00 PM </span>
+    `)
+
+    const timeInput = queryByTestId('startTime')
+
+    expect(timeInput).toHaveErrorMessage(
+      'Invalid time: the time must be between 9:00 AM and 5:00 PM',
     )
-    expect(queryByTestId('implicitly_invalid')).not.toHaveErrorMessage('The')
+    expect(timeInput).toHaveErrorMessage(/invalid time/i) // to partially match
+    expect(timeInput).toHaveErrorMessage(
+      expect.stringContaining('Invalid time'),
+    ) // to partially match
+    expect(timeInput).not.toHaveErrorMessage('Pikachu!')
   })
 
   test('rejects for valid object', () => {