feat: add toBePressed matcher (#203)

Author: kretajak

README.md

@@ -82,6 +82,7 @@ clear to read and to maintain.
   - [`toHaveRole`](#tohaverole)
   - [`toHaveErrorMessage`](#tohaveerrormessage)
   - [`toHaveSelection`](#tohaveselection)
+  - [`toBePressed`](#tobepressed)
 - [Deprecated matchers](#deprecated-matchers)
   - [`toBeEmpty`](#tobeempty)
   - [`toBeInTheDOM`](#tobeinthedom)
@@ -1306,6 +1307,44 @@ expect(timeInput).toHaveErrorMessage(expect.stringContaining('Invalid time')) //
 expect(timeInput).not.toHaveErrorMessage('Pikachu!')
 ```
 
+<hr />
+
+### `toBePressed`
+
+This allows to check whether given element has been [pressed](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed).
+
+It accepts elements with explicit or implicit `button` role and valid `aria-pressed` attribute of `"true"` or `"false"`.
+
+```typescript
+toBePressed()
+```
+
+#### Examples
+
+```html
+<button aria-pressed="true">Pressed</button>
+<button aria-pressed="false">Released</button>
+
+<input type="button" aria-pressed="true" value="Pressed input button" />
+<input type="button" aria-pressed="false" value="Released input button" />
+
+<span role="button" aria-pressed="true">Pressed span</span>
+<span role="button" aria-pressed="false">Released span</span>
+```
+
+##### Using DOM Testing Library
+
+```javascript
+screen.getByRole('button', { name: 'Pressed' }).toBePressed();
+screen.getByRole('button', { name: 'Released' }).not.toBePressed();
+
+screen.getByRole('button', { name: 'Pressed input button' }).toBePressed();
+screen.getByRole('button', { name: 'Released input button' }).not.toBePressed();
+
+screen.getByRole('button', { name: 'Pressed span' }).toBePressed();
+screen.getByRole('button', { name: 'Released span' }).not.toBePressed();
+```
+
 ## Deprecated matchers
 
 ### `toBeEmpty`

src/__tests__/to-be-pressed.js

@@ -0,0 +1,87 @@
+import {render} from './helpers/test-utils'
+
+describe('.toBePressed', () => {
+  test('handles button element', () => {
+    const {queryByTestId} = render(`
+      <button data-testid="button-pressed" aria-pressed="true" />
+      <button data-testid="button-not-pressed" aria-pressed="false" />
+    `)
+
+    expect(queryByTestId('button-pressed')).toBePressed()
+    expect(queryByTestId('button-not-pressed')).not.toBePressed()
+  })
+
+  test('handles element with role="button"', () => {
+    const {queryByTestId} = render(`
+      <span role="button" aria-pressed="true" data-testid="button-pressed" />
+      <span role="button" aria-pressed="false" data-testid="button-not-pressed" />
+    `)
+
+    expect(queryByTestId('button-pressed')).toBePressed()
+    expect(queryByTestId('button-not-pressed')).not.toBePressed()
+  })
+
+  test('handles input with button type', () => {
+    const {queryByTestId} = render(`
+      <input type="button" aria-pressed="true" data-testid="button-pressed" />
+      <input type="button" aria-pressed="false" data-testid="button-not-pressed" />
+    `)
+
+    expect(queryByTestId('button-pressed')).toBePressed()
+    expect(queryByTestId('button-not-pressed')).not.toBePressed()
+  })
+
+  test('throw an error when pressable element is not pressed but expected to be', () => {
+    const {queryByTestId} = render(`
+      <button data-testid="button" aria-pressed="false" />
+    `)
+
+    expect(() => expect(queryByTestId('button')).toBePressed())
+      .toThrowErrorMatchingInlineSnapshot(`
+      <dim>expect(</><red>element</><dim>).toBePressed()</>
+
+      Expected element to have:
+      <green>  aria-pressed="true"</>
+      Received:
+      <red>  aria-pressed="false"</>
+    `)
+  })
+
+  test('throw an error when pressable element is pressed but expected not to be', () => {
+    const {queryByTestId} = render(`
+      <button data-testid="button" aria-pressed="true" />
+    `)
+
+    expect(() => expect(queryByTestId('button')).not.toBePressed())
+      .toThrowErrorMatchingInlineSnapshot(`
+      <dim>expect(</><red>element</><dim>).not.toBePressed()</>
+
+      Expected element to have:
+      <green>  aria-pressed="false"</>
+      Received:
+      <red>  aria-pressed="true"</>
+    `)
+  })
+
+  test('throw an error when pressable element has invalid aria-pressed attribute', () => {
+    const {queryByTestId} = render(`
+      <button data-testid="button" aria-pressed="invalid" />
+    `)
+
+    expect(() =>
+      expect(queryByTestId('button')).toBePressed(),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `Only button or input with type="button" or element with role="button" and a valid aria-pressed attribute can be used with .toBePressed()`,
+    )
+  })
+
+  test('throws when element do not have aria-pressed attribute', () => {
+    const {queryByTestId} = render(`<span data-testid="span" />`)
+
+    expect(() =>
+      expect(queryByTestId('span')).toBePressed(),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `Only button or input with type="button" or element with role="button" and a valid aria-pressed attribute can be used with .toBePressed()`,
+    )
+  })
+})

src/matchers.js

@@ -25,3 +25,4 @@ export {toBePartiallyChecked} from './to-be-partially-checked'
 export {toHaveDescription} from './to-have-description'
 export {toHaveErrorMessage} from './to-have-errormessage'
 export {toHaveSelection} from './to-have-selection'
+export {toBePressed} from './to-be-pressed'

src/to-be-pressed.js

@@ -0,0 +1,56 @@
+import {checkHtmlElement, getMessage} from './utils'
+
+export function toBePressed(element) {
+  checkHtmlElement(element, toBePressed, this)
+
+  const isButton = () => {
+    return (
+      element.tagName.toLowerCase() === 'button' ||
+      element.getAttribute('role') === 'button' ||
+      (element.tagName.toLowerCase() === 'input' && element.type === 'button')
+    )
+  }
+
+  const isValidAriaElement = () => {
+    const ariaPressed = element.getAttribute('aria-pressed')
+
+    if (ariaPressed === 'true' || ariaPressed === 'false') {
+      return true
+    }
+
+    return false
+  }
+
+  if (!isButton() || !isValidAriaElement()) {
+    return {
+      pass: false,
+      message: () =>
+        `Only button or input with type="button" or element with role="button" and a valid aria-pressed attribute can be used with .toBePressed()`,
+    }
+  }
+
+  const isPressed = () => {
+    return element.getAttribute('aria-pressed') === 'true'
+  }
+
+  return {
+    pass: isButton() && isPressed(),
+
+    message: () => {
+      const matcher = this.utils.matcherHint(
+        `${this.isNot ? '.not' : ''}.toBePressed`,
+        'element',
+        '',
+      )
+
+      return getMessage(
+        this,
+        matcher,
+        `Expected element to have`,
+        `aria-pressed="${this.isNot ? 'false' : 'true'}"`,
+        `Received`,
+        `aria-pressed="${element.getAttribute('aria-pressed')}"`,
+      )
+    },
+  }
+}

types/matchers.d.ts

@@ -761,6 +761,36 @@ declare namespace matchers {
      * [testing-library/jest-dom#tohaveselection](https://github.com/testing-library/jest-dom#tohaveselection)
      */
     toHaveSelection(selection?: string): R
+    /*
+     * @description
+     * This allows to check whether given element has been [pressed](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) 
+     *
+     * It accepts elements with explicit or implicit `button` role and valid `aria-pressed` 
+     * attribute of `"true"` or `"false"`. 
+     *
+     * @example
+     * <button aria-pressed="true">Pressed</button>
+     * <button aria-pressed="false">Released</button>
+     *
+     * <input type="button" aria-pressed="true" value="Pressed input button" />
+     * <input type="button" aria-pressed="false" value="Released input button" />
+     * 
+     * <span role="button" aria-pressed="true">Pressed span</span>
+     * <span role="button" aria-pressed="false">Released span</span>
+     *
+     * screen.getByRole('button', { name: 'Pressed' }).toBePressed();
+     * screen.getByRole('button', { name: 'Released' }).not.toBePressed();
+     * 
+     * screen.getByRole('button', { name: 'Pressed input button' }).toBePressed();
+     * screen.getByRole('button', { name: 'Released input button' }).not.toBePressed();
+     * 
+     * screen.getByRole('button', { name: 'Pressed span' }).toBePressed();
+     * screen.getByRole('button', { name: 'Released span' }).not.toBePressed();
+     *
+     * @see
+     * [testing-library/jest-dom#tobepressed](https://github.com/testing-library/jest-dom#tobepressed)
+     */
+    toBePressed(): R
   }
 }