.github/workflows/validate.yml

@@ -16,7 +16,7 @@ jobs:
     if: ${{ !contains(github.head_ref, 'all-contributors') }}
     strategy:
       matrix:
-        node: [10.14, 12, 14, 15, 16]
+        node: [14, 16, 18, 20]
     runs-on: ubuntu-latest
     steps:
       - name: ⬇️ Checkout repo

README.md

@@ -51,7 +51,10 @@ clear to read and to maintain.
 
 - [Installation](#installation)
 - [Usage](#usage)
+  - [With `@jest/globals`](#with-jestglobals)
+  - [With Vitest](#with-vitest)
   - [With TypeScript](#with-typescript)
+  - [With another Jest-compatible `expect`](#with-another-jest-compatible-expect)
 - [Custom matchers](#custom-matchers)
   - [`toBeDisabled`](#tobedisabled)
   - [`toBeEnabled`](#tobeenabled)
@@ -64,6 +67,7 @@ clear to read and to maintain.
   - [`toContainElement`](#tocontainelement)
   - [`toContainHTML`](#tocontainhtml)
   - [`toHaveAccessibleDescription`](#tohaveaccessibledescription)
+  - [`toHaveAccessibleErrorMessage`](#tohaveaccessibleerrormessage)
   - [`toHaveAccessibleName`](#tohaveaccessiblename)
   - [`toHaveAttribute`](#tohaveattribute)
   - [`toHaveClass`](#tohaveclass)
@@ -127,6 +131,39 @@ import '@testing-library/jest-dom'
 setupFilesAfterEnv: ['<rootDir>/jest-setup.js']
 ```
 
+### With `@jest/globals`
+
+If you are using [`@jest/globals`][jest-globals announcement] with
+[`injectGlobals: false`][inject-globals docs], you will need to use a different
+import in your tests setup file:
+
+```javascript
+// In your own jest-setup.js (or any other name)
+import '@testing-library/jest-dom/jest-globals'
+```
+
+[jest-globals announcement]:
+  https://jestjs.io/blog/2020/05/05/jest-26#a-new-way-to-consume-jest---jestglobals
+[inject-globals docs]:
+  https://jestjs.io/docs/configuration#injectglobals-boolean
+
+### With Vitest
+
+If you are using [vitest][], this module will work as-is, but you will need to
+use a different import in your tests setup file. This file should be added to
+the [`setupFiles`][vitest setupfiles] property in your vitest config:
+
+```javascript
+// In your own vitest-setup.js (or any other name)
+import '@testing-library/jest-dom/vitest'
+
+// In vitest.config.js add (if you haven't already)
+setupFiles: ['./vitest-setup.js']
+```
+
+[vitest]: https://vitest.dev/
+[vitest setupfiles]: https://vitest.dev/config/#setupfiles
+
 ### With TypeScript
 
 If you're using TypeScript, make sure your setup file is a `.ts` and not a `.js`
@@ -143,6 +180,18 @@ haven't already:
   ],
 ```
 
+### With another Jest-compatible `expect`
+
+If you are using a different test runner that is compatible with Jest's `expect`
+interface, it might be possible to use it with this library:
+
+```javascript
+import * as matchers from '@testing-library/jest-dom/matchers'
+import {expect} from 'my-test-runner/expect'
+
+expect.extend(matchers)
+```
+
 ## Custom matchers
 
 `@testing-library/jest-dom` can work with any library or framework that returns
@@ -561,6 +610,63 @@ expect(getByTestId('logo')).toHaveAccessibleDescription(
 
 <hr />
 
+### `toHaveAccessibleErrorMessage`
+
+```typescript
+toHaveAccessibleErrorMessage(expectedAccessibleErrorMessage?: string | RegExp)
+```
+
+This allows you to assert that an element has the expected
+[accessible error message](https://w3c.github.io/aria/#aria-errormessage).
+
+You can pass the exact string of the expected accessible error message.
+Alternatively, you can perform a partial match by passing a regular expression
+or by using
+[expect.stringContaining](https://jestjs.io/docs/en/expect.html#expectnotstringcontainingstring)/[expect.stringMatching](https://jestjs.io/docs/en/expect.html#expectstringmatchingstring-regexp).
+
+#### Examples
+
+```html
+<input
+  aria-label="Has Error"
+  aria-invalid="true"
+  aria-errormessage="error-message"
+/>
+<div id="error-message" role="alert">This field is invalid</div>
+
+<input aria-label="No Error Attributes" />
+<input
+  aria-label="Not Invalid"
+  aria-invalid="false"
+  aria-errormessage="error-message"
+/>
+```
+
+```js
+// Inputs with Valid Error Messages
+expect(getByRole('textbox', {name: 'Has Error'})).toHaveAccessibleErrorMessage()
+expect(getByRole('textbox', {name: 'Has Error'})).toHaveAccessibleErrorMessage(
+  'This field is invalid',
+)
+expect(getByRole('textbox', {name: 'Has Error'})).toHaveAccessibleErrorMessage(
+  /invalid/i,
+)
+expect(
+  getByRole('textbox', {name: 'Has Error'}),
+).not.toHaveAccessibleErrorMessage('This field is absolutely correct!')
+
+// Inputs without Valid Error Messages
+expect(
+  getByRole('textbox', {name: 'No Error Attributes'}),
+).not.toHaveAccessibleErrorMessage()
+
+expect(
+  getByRole('textbox', {name: 'Not Invalid'}),
+).not.toHaveAccessibleErrorMessage()
+```
+
+<hr />
+
 ### `toHaveAccessibleName`
 
 ```typescript
@@ -1069,6 +1175,10 @@ expect(inputCheckboxIndeterminate).toBePartiallyChecked()
 
 ### `toHaveErrorMessage`
 
+> This custom matcher is deprecated. Prefer
+> [`toHaveAccessibleErrorMessage`](#tohaveaccessibleerrormessage) instead, which
+> is more comprehensive in implementing the official spec.
+
 ```typescript
 toHaveErrorMessage(text: string | RegExp)
 ```

jest-globals.d.ts

@@ -0,0 +1 @@
+/// <reference path="types/jest-globals.d.ts" />

jest-globals.js

@@ -0,0 +1,4 @@
+const globals = require('@jest/globals')
+const extensions = require('./dist/matchers')
+
+globals.expect.extend(extensions)

matchers.d.ts

@@ -0,0 +1,3 @@
+import * as matchers from './types/matchers'
+
+export = matchers

package.json

@@ -3,8 +3,9 @@
   "version": "0.0.0-semantically-released",
   "description": "Custom jest matchers to test the state of the DOM",
   "main": "dist/index.js",
+  "types": "types/index.d.ts",
   "engines": {
-    "node": ">=8",
+    "node": ">=14",
     "npm": ">=6",
     "yarn": ">=1"
   },
@@ -19,8 +20,11 @@
   },
   "files": [
     "dist",
-    "extend-expect.js",
-    "matchers.js"
+    "types",
+    "*.d.ts",
+    "jest-globals.js",
+    "matchers.js",
+    "vitest.js"
   ],
   "keywords": [
     "testing",
@@ -32,7 +36,6 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.9.2",
-    "@types/testing-library__jest-dom": "^5.9.1",
     "aria-query": "^5.0.0",
     "chalk": "^3.0.0",
     "@adobe/css-tools": "^4.0.1",
@@ -42,16 +45,44 @@
     "redent": "^3.0.0"
   },
   "devDependencies": {
+    "@jest/globals": "^29.6.2",
+    "expect": "^29.6.2",
     "jest-environment-jsdom-sixteen": "^1.0.3",
     "jest-watch-select-projects": "^2.0.0",
     "jsdom": "^16.2.1",
-    "kcd-scripts": "^11.1.0",
-    "pretty-format": "^25.1.0"
+    "kcd-scripts": "^14.0.0",
+    "pretty-format": "^25.1.0",
+    "vitest": "^0.34.1",
+    "typescript": "^5.1.6"
+  },
+  "peerDependencies": {
+    "@jest/globals": ">= 28",
+    "@types/jest": ">= 28",
+    "jest": ">= 28",
+    "vitest": ">= 0.32"
+  },
+  "peerDependenciesMeta": {
+    "@jest/globals": {
+      "optional": true
+    },
+    "@types/jest": {
+      "optional": true
+    },
+    "jest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
   },
   "eslintConfig": {
     "extends": "./node_modules/kcd-scripts/eslint.js",
+    "parserOptions": {
+      "sourceType": "module",
+      "ecmaVersion": 2020
+    },
     "rules": {
-      "@babel/no-invalid-this": "off"
+      "no-invalid-this": "off"
     },
     "overrides": [
       {
@@ -61,6 +92,18 @@
         "rules": {
           "max-lines-per-function": "off"
         }
+      },
+      {
+        "files": [
+          "**/*.d.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/no-empty-interface": "off",
+          "@typescript-eslint/no-explicit-any": "off",
+          "@typescript-eslint/no-invalid-void-type": "off",
+          "@typescript-eslint/no-unused-vars": "off",
+          "@typescript-eslint/triple-slash-reference": "off"
+        }
       }
     ]
   },