feat: add toBePartiallyPressed matcher (#203)

README.md

@@ -82,6 +82,7 @@ clear to read and to maintain.
   - [`toHaveRole`](#tohaverole)
   - [`toHaveErrorMessage`](#tohaveerrormessage)
   - [`toBePressed`](#tobepressed)
+  - [`toBePartiallyPressed`](#tobepartiallypressed)
 - [Deprecated matchers](#deprecated-matchers)
   - [`toBeEmpty`](#tobeempty)
   - [`toBeInTheDOM`](#tobeinthedom)
@@ -1347,6 +1348,44 @@ screen.getByRole('button', {name: 'Pressed span'}).toBePressed()
 screen.getByRole('button', {name: 'Released span'}).not.toBePressed()
 ```
 
+<hr />
+
+### `toBePartiallyPressed`
+
+This allows to check whether given element is partially
+[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 `mixed`.
+
+```typescript
+toBePressed()
+```
+
+#### Examples
+
+```html
+<button aria-pressed="mixed">Partially pressed</button>
+<input
+  type="button"
+  aria-pressed="mixed"
+  value="Partially pressed input button"
+/>
+<span role="button" aria-pressed="mixed">Partially pressed span</span>
+```
+
+##### Using DOM Testing Library
+
+```javascript
+screen.getByRole('button', {name: 'Partially pressed'}).toBePartiallyPressed()
+screen
+  .getByRole('button', {name: 'Partially pressed input button'})
+  .toBePartiallyPressed()
+screen
+  .getByRole('button', {name: 'Partially pressed span'})
+  .toBePartiallyPressed()
+```
+
 ## Deprecated matchers
 
 ### `toBeEmpty`

src/__tests__/to-be-partially-pressed.js

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

src/matchers.js

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

src/to-be-partially-pressed.js

@@ -0,0 +1,54 @@
+import {checkHtmlElement, getMessage} from './utils'
+
+export function toBePartiallyPressed(element) {
+  checkHtmlElement(element, toBePartiallyPressed, this)
+
+  const roles = (element.getAttribute('role') || '')
+    .split(' ')
+    .map(role => role.trim())
+
+  const isButton =
+    element.tagName.toLowerCase() === 'button' ||
+    (element.tagName.toLowerCase() === 'input' && element.type === 'button') ||
+    roles.includes('button')
+
+  const pressedAttribute = element.getAttribute('aria-pressed')
+
+  const isValidAriaElement =
+    pressedAttribute === 'true' ||
+    pressedAttribute === 'false' ||
+    pressedAttribute === 'mixed'
+
+  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 .toBePartiallyPressed()`,
+    }
+  }
+
+  const isPartiallyPressed = pressedAttribute === 'mixed'
+
+  return {
+    pass: isButton && isPartiallyPressed,
+
+    message: () => {
+      const to = this.isNot ? 'not to' : 'to'
+
+      const matcher = this.utils.matcherHint(
+        `${this.isNot ? '.not' : ''}.toBePartiallyPressed`,
+        'element',
+        '',
+      )
+
+      return getMessage(
+        this,
+        matcher,
+        `Expected element ${to} have`,
+        `aria-pressed="mixed"`,
+        `Received`,
+        `aria-pressed="${pressedAttribute}"`,
+      )
+    },
+  }
+}

types/matchers.d.ts

@@ -763,34 +763,53 @@ declare namespace matchers {
     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) 
+     * 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"`. 
+     * 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
+    /*
+     * @description
+     * This allows to check whether given element has been [partially 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` of `"mixed"`.
+     *
+     * @example
+     * <button aria-pressed="mixed">Partially Pressed</button>
+     * <input type="button" aria-pressed="mixed" value="Partially pressed input button" />
+     * <span role="button" aria-pressed="mixed">Partially pressed span</span>
+     *
+     * screen.getByRole('button', { name: 'Partially Pressed' }).toBePartiallyPressed();
+     * screen.getByRole('button', { name: 'Partially pressed input button' }).toBePartiallyPressed();
+     * screen.getByRole('button', { name: 'Partially pressed span' }).toBePartiallyPressed();
+     *
+     * @See
+     * [testing-library/jest-dom#tobepartiallypressed](https://github.com/testing-library/jest-dom#tobepartiallypressed)
+     */
+    toBePartiallyPressed(): R
   }
 }