feat: add toHaveVirtualFocus matcher (#207)

README.md

@@ -72,6 +72,7 @@ clear to read and to maintain.
   - [`toHaveAttribute`](#tohaveattribute)
   - [`toHaveClass`](#tohaveclass)
   - [`toHaveFocus`](#tohavefocus)
+  - [`toHaveVirtualFocus`](#tohavevirtualfocus)
   - [`toHaveFormValues`](#tohaveformvalues)
   - [`toHaveStyle`](#tohavestyle)
   - [`toHaveTextContent`](#tohavetextcontent)
@@ -836,6 +837,44 @@ expect(input).not.toHaveFocus()
 
 <hr />
 
+### `toHaveVirtualFocus`
+
+```typescript
+toHaveVirtualFocus()
+```
+
+This allows you to assert whether an element has "virtual focus", i.e. it is
+referenced by the `aria-activedescendant` attribute of the element that
+currently has DOM focus. This is common in composite widgets such as listboxes
+and comboboxes, where DOM focus stays on a container element while
+`aria-activedescendant` points at the item that is currently "active".
+
+#### Examples
+
+```html
+<ul
+  role="listbox"
+  aria-activedescendant="option1"
+  tabindex="0"
+  data-testid="listbox"
+>
+  <li role="option" id="option1" data-testid="option1">option 1</li>
+  <li role="option" id="option2" data-testid="option2">option 2</li>
+</ul>
+```
+
+```javascript
+const listbox = getByTestId('listbox')
+const option1 = getByTestId('option1')
+const option2 = getByTestId('option2')
+
+listbox.focus()
+expect(option1).toHaveVirtualFocus()
+expect(option2).not.toHaveVirtualFocus()
+```
+
+<hr />
+
 ### `toHaveFormValues`
 
 ```typescript

src/__tests__/to-have-virtual-focus.js

@@ -0,0 +1,56 @@
+import {render} from './helpers/test-utils'
+import document from './helpers/document'
+
+test('.toHaveVirtualFocus', () => {
+  const {container} = render(`
+      <ul role="listbox" tabindex="0" aria-activedescendant="option1" data-testid="listbox">
+        <li role="option" id="option1" data-testid="option1">option 1</li>
+        <li role="option" id="option2" data-testid="option2">option 2</li>
+      </ul>`)
+
+  const listbox = container.querySelector('[data-testid="listbox"]')
+  const option1 = container.querySelector('#option1')
+  const option2 = container.querySelector('#option2')
+
+  document.body.appendChild(container)
+  listbox.focus()
+
+  expect(option1).toHaveVirtualFocus()
+  expect(option2).not.toHaveVirtualFocus()
+
+  expect(() => expect(option1).not.toHaveVirtualFocus()).toThrowError()
+  expect(() => expect(option2).toHaveVirtualFocus()).toThrowError()
+})
+
+test('.toHaveVirtualFocus when the container does not have DOM focus', () => {
+  const {container} = render(`
+      <ul role="listbox" tabindex="0" aria-activedescendant="option1" data-testid="listbox">
+        <li role="option" id="option1" data-testid="option1">option 1</li>
+      </ul>`)
+
+  const option1 = container.querySelector('#option1')
+
+  expect(option1).not.toHaveVirtualFocus()
+})
+
+test('.toHaveVirtualFocus updates as aria-activedescendant changes', () => {
+  const {container} = render(`
+      <ul role="listbox" tabindex="0" aria-activedescendant="option1" data-testid="listbox">
+        <li role="option" id="option1" data-testid="option1">option 1</li>
+        <li role="option" id="option2" data-testid="option2">option 2</li>
+      </ul>`)
+
+  const listbox = container.querySelector('[data-testid="listbox"]')
+  const option1 = container.querySelector('#option1')
+  const option2 = container.querySelector('#option2')
+
+  document.body.appendChild(container)
+  listbox.focus()
+
+  expect(option1).toHaveVirtualFocus()
+
+  listbox.setAttribute('aria-activedescendant', 'option2')
+
+  expect(option1).not.toHaveVirtualFocus()
+  expect(option2).toHaveVirtualFocus()
+})

src/matchers.js

@@ -13,6 +13,7 @@ export {toHaveAttribute} from './to-have-attribute'
 export {toHaveClass} from './to-have-class'
 export {toHaveStyle} from './to-have-style'
 export {toHaveFocus} from './to-have-focus'
+export {toHaveVirtualFocus} from './to-have-virtual-focus'
 export {toHaveFormValues} from './to-have-form-values'
 export {toBeVisible} from './to-be-visible'
 export {toBeDisabled, toBeEnabled} from './to-be-disabled'

src/to-have-virtual-focus.js

@@ -0,0 +1,38 @@
+import {checkHtmlElement} from './utils'
+
+export function toHaveVirtualFocus(element) {
+  checkHtmlElement(element, toHaveVirtualFocus, this)
+
+  const {activeElement} = element.ownerDocument
+  const activeDescendantId = activeElement?.getAttribute(
+    'aria-activedescendant',
+  )
+  const virtuallyFocusedElement = activeDescendantId
+    ? element.ownerDocument.getElementById(activeDescendantId)
+    : null
+
+  return {
+    pass: virtuallyFocusedElement === element,
+    message: () => {
+      return [
+        this.utils.matcherHint(
+          `${this.isNot ? '.not' : ''}.toHaveVirtualFocus`,
+          'element',
+          '',
+        ),
+        '',
+        ...(this.isNot
+          ? [
+              'Received element has virtual focus via aria-activedescendant:',
+              `  ${this.utils.printReceived(element)}`,
+            ]
+          : [
+              'Expected element to have virtual focus via aria-activedescendant:',
+              `  ${this.utils.printExpected(element)}`,
+              'Received element with virtual focus:',
+              `  ${this.utils.printReceived(virtuallyFocusedElement)}`,
+            ]),
+      ].join('\n')
+    },
+  }
+}

types/matchers.d.ts

@@ -319,6 +319,25 @@ declare namespace matchers {
      * [testing-library/jest-dom#tohavefocus](https://github.com/testing-library/jest-dom#tohavefocus)
      */
     toHaveFocus(): R
+    /**
+     * @description
+     * Assert whether an element has virtual focus via `aria-activedescendant`,
+     * i.e. it is referenced by the `aria-activedescendant` attribute of the
+     * element that currently has DOM focus.
+     * @example
+     * <ul role="listbox" aria-activedescendant="option1" tabindex="0" data-testid="listbox">
+     *   <li role="option" id="option1" data-testid="option1">option 1</li>
+     *   <li role="option" id="option2" data-testid="option2">option 2</li>
+     * </ul>
+     *
+     * const listbox = getByTestId('listbox')
+     * const option1 = getByTestId('option1')
+     * listbox.focus()
+     * expect(option1).toHaveVirtualFocus()
+     * @see
+     * [testing-library/jest-dom#tohavevirtualfocus](https://github.com/testing-library/jest-dom#tohavevirtualfocus)
+     */
+    toHaveVirtualFocus(): R
     /**
      * @description
      * Check if a form or fieldset contains form controls for each given name, and having the specified value.