feat: toBeDisabled custom matcher (#18) (#19)

* feat: toBeDisabled custom matcher (#18)

* Updated tests, removed nested divs

* Updated documentation

* toBeDisabled test moved to a separate file

Author: callada

.all-contributorsrc

@@ -168,6 +168,17 @@
         "bug",
         "code"
       ]
+    },
+    {
+      "login": "callada",
+      "name": "Iwona",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/7830590?v=4",
+      "profile": "https://github.com/callada",
+      "contributions": [
+        "code",
+        "doc",
+        "test"
+      ]
     }
   ]
 }

README.md

@@ -16,7 +16,7 @@
 [![downloads][downloads-badge]][npmtrends]
 [![MIT License][license-badge]][license]
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-16-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-17-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs]
 [![Code of Conduct][coc-badge]][coc]
 
@@ -54,6 +54,7 @@ to maintain.
   - [`toHaveStyle`](#tohavestyle)
   - [`toHaveFocus`](#tohavefocus)
   - [`toBeVisible`](#tobevisible)
+  - [`toBeDisabled`](#tobedisabled)
 - [Inspiration](#inspiration)
 - [Other Solutions](#other-solutions)
 - [Guiding Principles](#guiding-principles)
@@ -305,6 +306,38 @@ expect(container.querySelector('strong')).not.toBeVisible()
 // ...
 ```
 
+### `toBeDisabled`
+
+This allows you to check whether an element is disabled from the user's perspective.
+
+It matches if the element is a form control and the `disabled` attribute is
+specified on this element or the element is a descendant of a form element
+with a `disabled` attribute.
+
+According to the specification, the following elements can be [actually disabled](https://html.spec.whatwg.org/multipage/semantics-other.html#disabled-elements):
+`button`, `input`, `select`, `textarea`, `optgroup`, `option`, `fieldset`.
+
+```javascript
+// add the custom expect matchers once
+import 'jest-dom/extend-expect'
+
+// ...
+// <button data-testid="button" type="submit" disabled>
+//   SUBMIT
+// </button>
+// <fieldset disabled>
+//   <input type="text" data-testid="text" />
+// </fieldset>
+expect(getByTestId(container, 'button')).toBeDisabled()
+expect(getByTestId(container, 'text')).toBeDisabled()
+// ...
+
+// ...
+// <a href="..." disabled>LINK</a>
+expect(getByText(container, 'LINK')).not.toBeDisabled()
+// ...
+```
+
 ## Inspiration
 
 This whole library was extracted out of Kent C. Dodds' [dom-testing-library][],
@@ -343,7 +376,7 @@ Thanks goes to these people ([emoji key][emojis]):
 | [<img src="https://avatars.githubusercontent.com/u/1500684?v=3" width="100px;"/><br /><sub><b>Kent C. Dodds</b></sub>](https://kentcdodds.com)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=kentcdodds "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=kentcdodds "Documentation") [🚇](#infra-kentcdodds "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/gnapse/jest-dom/commits?author=kentcdodds "Tests") | [<img src="https://avatars1.githubusercontent.com/u/2430381?v=4" width="100px;"/><br /><sub><b>Ryan Castner</b></sub>](http://audiolion.github.io)<br />[📖](https://github.com/gnapse/jest-dom/commits?author=audiolion "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/8008023?v=4" width="100px;"/><br /><sub><b>Daniel Sandiego</b></sub>](https://www.dnlsandiego.com)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=dnlsandiego "Code") | [<img src="https://avatars2.githubusercontent.com/u/12592677?v=4" width="100px;"/><br /><sub><b>Paweł Mikołajczyk</b></sub>](https://github.com/Miklet)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=Miklet "Code") | [<img src="https://avatars3.githubusercontent.com/u/464978?v=4" width="100px;"/><br /><sub><b>Alejandro Ñáñez Ortiz</b></sub>](http://co.linkedin.com/in/alejandronanez/)<br />[📖](https://github.com/gnapse/jest-dom/commits?author=alejandronanez "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/1402095?v=4" width="100px;"/><br /><sub><b>Matt Parrish</b></sub>](https://github.com/pbomb)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Apbomb "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=pbomb "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=pbomb "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=pbomb "Tests") | [<img src="https://avatars1.githubusercontent.com/u/1288694?v=4" width="100px;"/><br /><sub><b>Justin Hall</b></sub>](https://github.com/wKovacs64)<br />[📦](#platform-wKovacs64 "Packaging/porting to new platform") |
 | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
 | [<img src="https://avatars1.githubusercontent.com/u/1241511?s=460&v=4" width="100px;"/><br /><sub><b>Anto Aravinth</b></sub>](https://github.com/antoaravinth)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=antoaravinth "Code") [⚠️](https://github.com/gnapse/jest-dom/commits?author=antoaravinth "Tests") [📖](https://github.com/gnapse/jest-dom/commits?author=antoaravinth "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/3462296?v=4" width="100px;"/><br /><sub><b>Jonah Moses</b></sub>](https://github.com/JonahMoses)<br />[📖](https://github.com/gnapse/jest-dom/commits?author=JonahMoses "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/4002543?v=4" width="100px;"/><br /><sub><b>Łukasz Gandecki</b></sub>](http://team.thebrain.pro)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=lgandecki "Code") [⚠️](https://github.com/gnapse/jest-dom/commits?author=lgandecki "Tests") [📖](https://github.com/gnapse/jest-dom/commits?author=lgandecki "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/498274?v=4" width="100px;"/><br /><sub><b>Ivan Babak</b></sub>](https://sompylasar.github.io)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Asompylasar "Bug reports") [🤔](#ideas-sompylasar "Ideas, Planning, & Feedback") | [<img src="https://avatars3.githubusercontent.com/u/4439618?v=4" width="100px;"/><br /><sub><b>Jesse Day</b></sub>](https://github.com/jday3)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=jday3 "Code") | [<img src="https://avatars0.githubusercontent.com/u/15199?v=4" width="100px;"/><br /><sub><b>Ernesto García</b></sub>](http://gnapse.github.io)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=gnapse "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=gnapse "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=gnapse "Tests") | [<img src="https://avatars0.githubusercontent.com/u/79312?v=4" width="100px;"/><br /><sub><b>Mark Volkmann</b></sub>](http://ociweb.com/mark/)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Amvolkmann "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=mvolkmann "Code") |
-| [<img src="https://avatars1.githubusercontent.com/u/1659099?v=4" width="100px;"/><br /><sub><b>smacpherson64</b></sub>](https://github.com/smacpherson64)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Tests") | [<img src="https://avatars2.githubusercontent.com/u/132233?v=4" width="100px;"/><br /><sub><b>John Gozde</b></sub>](https://github.com/jgoz)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Ajgoz "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=jgoz "Code") |
+| [<img src="https://avatars1.githubusercontent.com/u/1659099?v=4" width="100px;"/><br /><sub><b>smacpherson64</b></sub>](https://github.com/smacpherson64)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=smacpherson64 "Tests") | [<img src="https://avatars2.githubusercontent.com/u/132233?v=4" width="100px;"/><br /><sub><b>John Gozde</b></sub>](https://github.com/jgoz)<br />[🐛](https://github.com/gnapse/jest-dom/issues?q=author%3Ajgoz "Bug reports") [💻](https://github.com/gnapse/jest-dom/commits?author=jgoz "Code") | [<img src="https://avatars2.githubusercontent.com/u/7830590?v=4" width="100px;"/><br /><sub><b>Iwona</b></sub>](https://github.com/callada)<br />[💻](https://github.com/gnapse/jest-dom/commits?author=callada "Code") [📖](https://github.com/gnapse/jest-dom/commits?author=callada "Documentation") [⚠️](https://github.com/gnapse/jest-dom/commits?author=callada "Tests") |
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 

extend-expect.d.ts

@@ -3,6 +3,7 @@ declare namespace jest {
     toBeInTheDOM(container?: HTMLElement): R
     toBeVisible(): R
     toBeEmpty(): R
+    toBeDisabled(): R
     toContainElement(element: HTMLElement): R
     toHaveAttribute(attr: string, value?: string): R
     toHaveClass(...classNames: string[]): R

src/__tests__/to-be-disabled.js

@@ -0,0 +1,109 @@
+import '../extend-expect'
+import {plugins} from 'pretty-format'
+import {render} from './helpers/test-utils'
+
+expect.addSnapshotSerializer(plugins.ConvertAnsi)
+
+test('.toBeDisabled', () => {
+  const {queryByTestId} = render(`
+    <div>
+      <button disabled={true} data-testid="button-element">x</button>
+      <textarea disabled={true} data-testid="textarea-element"></textarea>
+      <input type="checkbox" disabled={true} data-testid="input-element" />
+
+      <fieldset disabled={true} data-testid="fieldset-element">
+        <button data-testid="fieldset-child-element">x</button>
+      </fieldset>
+
+      <div disabled={true} data-testid="div-element">
+        <button data-testid="div-child-element">x</button>
+      </div>
+
+      <fieldset disabled={true}>
+        <div>
+          <button data-testid="nested-form-element">x</button>
+        
+          <select data-testid="deep-select-element">
+            <optgroup data-testid="deep-optgroup-element">
+              <option data-testid="deep-option-element">x</option>
+            </optgroup>
+          </select>
+        </div>
+      </fieldset>
+
+      <a href="http://github.com" disabled={true} data-testid="a-element">x</a>
+    </div>
+    `)
+
+  expect(queryByTestId('button-element')).toBeDisabled()
+  expect(() =>
+    expect(queryByTestId('button-element')).not.toBeDisabled(),
+  ).toThrowError()
+  expect(queryByTestId('textarea-element')).toBeDisabled()
+  expect(queryByTestId('input-element')).toBeDisabled()
+
+  expect(queryByTestId('fieldset-element')).toBeDisabled()
+  expect(queryByTestId('fieldset-child-element')).toBeDisabled()
+
+  expect(queryByTestId('div-element')).not.toBeDisabled()
+  expect(queryByTestId('div-child-element')).not.toBeDisabled()
+
+  expect(queryByTestId('nested-form-element')).toBeDisabled()
+  expect(queryByTestId('deep-select-element')).toBeDisabled()
+  expect(queryByTestId('deep-optgroup-element')).toBeDisabled()
+  expect(queryByTestId('deep-option-element')).toBeDisabled()
+
+  expect(queryByTestId('a-element')).not.toBeDisabled()
+  expect(() => expect(queryByTestId('a-element')).toBeDisabled()).toThrowError()
+})
+
+test('.toBeDisabled fieldset>legend', () => {
+  const {queryByTestId} = render(`
+    <div>
+      <fieldset disabled={true}>
+        <button data-testid="inherited-element">x</button>
+      </fieldset>
+
+      <fieldset disabled={true}>
+        <legend>
+          <button data-testid="inside-legend-element">x</button>
+        </legend>
+      </fieldset>
+
+      <fieldset disabled={true}>
+        <legend>
+          <div>
+            <button data-testid="nested-inside-legend-element">x</button>
+          </div>
+        </legend>
+      </fieldset>
+
+      <fieldset disabled={true}>
+        <div></div>
+        <legend>
+          <button data-testid="first-legend-element">x</button>
+        </legend>
+        <legend>
+          <button data-testid="second-legend-element">x</button>
+        </legend>
+      </fieldset>
+
+      <fieldset disabled={true}>
+        <fieldset>
+          <legend>
+            <button data-testid="outer-fieldset-element">x</button>
+          </legend>
+        </fieldset>
+      </fieldset>
+    </div>
+    `)
+
+  expect(queryByTestId('inherited-element')).toBeDisabled()
+  expect(queryByTestId('inside-legend-element')).not.toBeDisabled()
+  expect(queryByTestId('nested-inside-legend-element')).not.toBeDisabled()
+
+  expect(queryByTestId('first-legend-element')).not.toBeDisabled()
+  expect(queryByTestId('second-legend-element')).toBeDisabled()
+
+  expect(queryByTestId('outer-fieldset-element')).toBeDisabled()
+})

src/index.js

@@ -7,6 +7,7 @@ import {toHaveClass} from './to-have-class'
 import {toHaveStyle} from './to-have-style'
 import {toHaveFocus} from './to-have-focus'
 import {toBeVisible} from './to-be-visible'
+import {toBeDisabled} from './to-be-disabled'
 
 export {
   toBeInTheDOM,
@@ -18,4 +19,5 @@ export {
   toHaveStyle,
   toHaveFocus,
   toBeVisible,
+  toBeDisabled,
 }

src/to-be-disabled.js

@@ -0,0 +1,73 @@
+import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {checkHtmlElement} from './utils'
+
+// form elements that support 'disabled'
+const FORM_TAGS = [
+  'fieldset',
+  'input',
+  'select',
+  'optgroup',
+  'option',
+  'button',
+  'textarea',
+]
+
+function getTag(element) {
+  return element.tagName && element.tagName.toLowerCase()
+}
+
+/*
+ * According to specification:
+ * If <fieldset> is disabled, the form controls that are its descendants,
+ * except descendants of its first optional <legend> element, are disabled
+ * 
+ * https://html.spec.whatwg.org/multipage/form-elements.html#concept-fieldset-disabled
+ *
+ * This method tests whether element is first legend child of fieldset parent
+ */
+function isFirstLegendChildOfFieldset(element, parent) {
+  return (
+    getTag(element) === 'legend' &&
+    getTag(parent) === 'fieldset' &&
+    element.isSameNode(
+      Array.from(parent.children).find(child => getTag(child) === 'legend'),
+    )
+  )
+}
+
+function isElementDisabledByParent(element, parent) {
+  return (
+    isElementDisabled(parent) && !isFirstLegendChildOfFieldset(element, parent)
+  )
+}
+
+function isElementDisabled(element) {
+  return FORM_TAGS.includes(getTag(element)) && element.hasAttribute('disabled')
+}
+
+function isAncestorDisabled(element) {
+  const parent = element.parentElement
+  return (
+    Boolean(parent) &&
+    (isElementDisabledByParent(element, parent) || isAncestorDisabled(parent))
+  )
+}
+
+export function toBeDisabled(element) {
+  checkHtmlElement(element, toBeDisabled, this)
+
+  const isDisabled = isElementDisabled(element) || isAncestorDisabled(element)
+
+  return {
+    pass: isDisabled,
+    message: () => {
+      const is = isDisabled ? 'is' : 'is not'
+      return [
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeDisabled`, 'element', ''),
+        '',
+        `Received element ${is} disabled:`,
+        `  ${printReceived(element.cloneNode(false))}`,
+      ].join('\n')
+    },
+  }
+}