feat: Add toBeInvalid and toBeValid matchers (#110)

Author: hiwelo

README.md

@@ -49,7 +49,9 @@ to maintain.
   - [`toBeEnabled`](#tobeenabled)
   - [`toBeEmpty`](#tobeempty)
   - [`toBeInTheDocument`](#tobeinthedocument)
+  - [`toBeInvalid`](#tobeinvalid)
   - [`toBeRequired`](#toberequired)
+  - [`toBeValid`](#tobevalid)
   - [`toBeVisible`](#tobevisible)
   - [`toContainElement`](#tocontainelement)
   - [`toContainHTML`](#tocontainhtml)
@@ -235,6 +237,45 @@ expect(
 
 <hr />
 
+### `toBeInvalid`
+
+```typescript
+toBeInvalid()
+```
+
+This allows you to check if an form element is currently invalid.
+
+An element is invalid if it is having an [`aria-invalid` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute) or if the result of [`checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) are false.
+
+#### Examples
+
+```html
+<input data-testid="no-aria-invalid" />
+<input data-testid="aria-invalid" aria-invalid />
+<input data-testid="aria-invalid-value" aria-invalid="true" />
+<input data-testid="aria-invalid-false" aria-invalid="false" />
+```
+
+##### Using document.querySelector
+
+```javascript
+expect(queryByTestId('no-aria-invalid')).not.toBeInvalid()
+expect(queryByTestId('aria-invalid')).toBeInvalid()
+expect(queryByTestId('aria-invalid-value')).toBeInvalid()
+expect(queryByTestId('aria-invalid-false')).not.toBeInvalid()
+```
+
+##### Using dom-testing-library
+
+```javascript
+expect(getByTestId(container, 'no-aria-invalid')).not.toBeInvalid()
+expect(getByTestId(container, 'aria-invalid')).toBeInvalid()
+expect(getByTestId(container, 'aria-invalid-value')).toBeInvalid()
+expect(getByTestId(container, 'aria-invalid-false')).not.toBeInvalid()
+```
+
+<hr />
+
 ### `toBeRequired`
 
 ```typescript
@@ -303,6 +344,45 @@ expect(getByTestId(container, 'supported-role-aria')).toBeRequired()
 
 <hr />
 
+### `toBeValid`
+
+```typescript
+toBeValid()
+```
+
+This allows you to check if the value of a form element is currently valid.
+
+An element is valid if it is not having an [`aria-invalid` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute) or having `false` as a value and returning `true` when calling [`checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation).
+
+#### Examples
+
+```html
+<input data-testid="no-aria-invalid" />
+<input data-testid="aria-invalid" aria-invalid />
+<input data-testid="aria-invalid-value" aria-invalid="true" />
+<input data-testid="aria-invalid-false" aria-invalid="false" />
+```
+
+##### Using document.querySelector
+
+```javascript
+expect(queryByTestId('no-aria-invalid')).toBeValid()
+expect(queryByTestId('aria-invalid')).not.toBeValid()
+expect(queryByTestId('aria-invalid-value')).not.toBeValid()
+expect(queryByTestId('aria-invalid-false')).toBeValid()
+```
+
+##### Using dom-testing-library
+
+```javascript
+expect(getByTestId(container, 'no-aria-invalid')).toBeValid()
+expect(getByTestId(container, 'aria-invalid')).not.toBeValid()
+expect(getByTestId(container, 'aria-invalid-value')).not.toBeValid()
+expect(getByTestId(container, 'aria-invalid-false')).toBeValid()
+```
+
+<hr />
+
 ### `toBeVisible`
 
 ```typescript

extend-expect.d.ts

@@ -9,7 +9,9 @@ declare namespace jest {
     toBeEmpty(): R
     toBeDisabled(): R
     toBeEnabled(): R
+    toBeInvalid(): R
     toBeRequired(): R
+    toBeValid(): R
     toContainElement(element: HTMLElement | SVGElement | null): R
     toContainHTML(htmlText: string): R
     toHaveAttribute(attr: string, value?: any): R

package.json

@@ -43,7 +43,7 @@
     "redent": "^2.0.0"
   },
   "devDependencies": {
-    "jsdom": "^12.2.0",
+    "jsdom": "^15.1.0",
     "kcd-scripts": "^0.44.0"
   },
   "eslintConfig": {

src/__tests__/to-be-invalid.js

@@ -0,0 +1,92 @@
+import {JSDOM} from 'jsdom'
+import {render} from './helpers/test-utils'
+
+/*
+ * This function is being used to test if `.toBeInvalid` and `.toBeValid`
+ * are correctly triggered by the DOM Node method `.checkValidity()`, part
+ * of the Web API.
+ *
+ * For this check, we are using the `jsdom` library to return a DOM Node
+ * sending the good information to our test.
+ *
+ * We are using this library because without it `.checkValidity()` returns
+ * always `true` when using `yarn test` in a terminal.
+ *
+ * Please consult the PR 110 to get more information:
+ * https://github.com/testing-library/jest-dom/pull/110
+ *
+ * @link https://github.com/testing-library/jest-dom/pull/110
+ * @link https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
+ * @link https://github.com/jsdom/jsdom
+ */
+function getDOMInput(htmlString) {
+  const dom = new JSDOM(htmlString)
+
+  return dom.window.document.querySelector('input')
+}
+
+const invalidInputNode = getDOMInput(
+  `<input pattern="[a-z]{1,3}" value="test+">`,
+)
+
+test('.toBeInvalid', () => {
+  const {queryByTestId} = render(`
+    <div>
+      <input data-testid="no-aria-invalid">
+      <input data-testid="aria-invalid" aria-invalid>
+      <input data-testid="aria-invalid-value" aria-invalid="true">
+      <input data-testid="aria-invalid-false" aria-invalid="false">
+    </div>
+    `)
+
+  expect(queryByTestId('no-aria-invalid')).not.toBeInvalid()
+  expect(queryByTestId('aria-invalid')).toBeInvalid()
+  expect(queryByTestId('aria-invalid-value')).toBeInvalid()
+  expect(queryByTestId('aria-invalid-false')).not.toBeInvalid()
+  expect(invalidInputNode).toBeInvalid()
+
+  // negative test cases wrapped in throwError assertions for coverage.
+  expect(() =>
+    expect(queryByTestId('no-aria-invalid')).toBeInvalid(),
+  ).toThrowError()
+  expect(() =>
+    expect(queryByTestId('aria-invalid')).not.toBeInvalid(),
+  ).toThrowError()
+  expect(() =>
+    expect(queryByTestId('aria-invalid-value')).not.toBeInvalid(),
+  ).toThrowError()
+  expect(() =>
+    expect(queryByTestId('aria-invalid-false')).toBeInvalid(),
+  ).toThrowError()
+  expect(() => expect(invalidInputNode).not.toBeInvalid()).toThrowError()
+})
+
+test('.toBeValid', () => {
+  const {queryByTestId} = render(`
+    <div>
+      <input data-testid="no-aria-invalid">
+      <input data-testid="aria-invalid" aria-invalid>
+      <input data-testid="aria-invalid-value" aria-invalid="true">
+      <input data-testid="aria-invalid-false" aria-invalid="false">
+    </div>
+    `)
+
+  expect(queryByTestId('no-aria-invalid')).toBeValid()
+  expect(queryByTestId('aria-invalid')).not.toBeValid()
+  expect(queryByTestId('aria-invalid-value')).not.toBeValid()
+  expect(queryByTestId('aria-invalid-false')).toBeValid()
+  expect(invalidInputNode).not.toBeValid()
+
+  // negative test cases wrapped in throwError assertions for coverage.
+  expect(() =>
+    expect(queryByTestId('no-aria-invalid')).not.toBeValid(),
+  ).toThrowError()
+  expect(() => expect(queryByTestId('aria-invalid')).toBeValid()).toThrowError()
+  expect(() =>
+    expect(queryByTestId('aria-invalid-value')).toBeValid(),
+  ).toThrowError()
+  expect(() =>
+    expect(queryByTestId('aria-invalid-false')).not.toBeValid(),
+  ).toThrowError()
+  expect(() => expect(invalidInputNode).toBeValid()).toThrowError()
+})

src/index.js

@@ -12,6 +12,7 @@ import {toHaveFormValues} from './to-have-form-values'
 import {toBeVisible} from './to-be-visible'
 import {toBeDisabled, toBeEnabled} from './to-be-disabled'
 import {toBeRequired} from './to-be-required'
+import {toBeInvalid, toBeValid} from './to-be-invalid'
 
 export {
   toBeInTheDOM,
@@ -29,4 +30,6 @@ export {
   toBeDisabled,
   toBeEnabled,
   toBeRequired,
+  toBeInvalid,
+  toBeValid,
 }

src/to-be-disabled.js

@@ -1,5 +1,5 @@
 import {matcherHint, printReceived} from 'jest-matcher-utils'
-import {checkHtmlElement} from './utils'
+import {checkHtmlElement, getTag} from './utils'
 
 // form elements that support 'disabled'
 const FORM_TAGS = [
@@ -12,10 +12,6 @@ const FORM_TAGS = [
   'textarea',
 ]
 
-function getTag(element) {
-  return element.tagName && element.tagName.toLowerCase()
-}
-
 /*
  * According to specification:
  * If <fieldset> is disabled, the form controls that are its descendants,

src/to-be-invalid.js

@@ -0,0 +1,56 @@
+import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {checkHtmlElement, getTag} from './utils'
+
+const FORM_TAGS = ['input', 'select', 'textarea']
+
+function isElementHavingAriaInvalid(element) {
+  return (
+    element.hasAttribute('aria-invalid') &&
+    element.getAttribute('aria-invalid') !== 'false'
+  )
+}
+
+function isElementInvalid(element) {
+  return !element.checkValidity()
+}
+
+export function toBeInvalid(element) {
+  checkHtmlElement(element, toBeInvalid, this)
+
+  const isInvalid =
+    isElementHavingAriaInvalid(element) || isElementInvalid(element)
+
+  return {
+    pass: isInvalid,
+    message: () => {
+      const is = isInvalid ? 'is' : 'is not'
+      return [
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeInvalid`, 'element', ''),
+        '',
+        `Received element ${is} currently invalid:`,
+        `  ${printReceived(element.cloneNode(false))}`,
+      ].join('\n')
+    },
+  }
+}
+
+export function toBeValid(element) {
+  checkHtmlElement(element, toBeValid, this)
+
+  const isValid =
+    !isElementHavingAriaInvalid(element) &&
+    (FORM_TAGS.includes(getTag(element)) && !isElementInvalid(element))
+
+  return {
+    pass: isValid,
+    message: () => {
+      const is = isValid ? 'is' : 'is not'
+      return [
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeValid`, 'element', ''),
+        '',
+        `Received element ${is} currently valid:`,
+        `  ${printReceived(element.cloneNode(false))}`,
+      ].join('\n')
+    },
+  }
+}

src/to-be-required.js

@@ -1,5 +1,5 @@
 import {matcherHint, printReceived} from 'jest-matcher-utils'
-import {checkHtmlElement} from './utils'
+import {checkHtmlElement, getTag} from './utils'
 
 // form elements that support 'required'
 const FORM_TAGS = ['select', 'textarea']
@@ -23,10 +23,6 @@ const SUPPORTED_ARIA_ROLES = [
   'tree',
 ]
 
-function getTag(element) {
-  return element.tagName && element.tagName.toLowerCase()
-}
-
 function isRequiredOnFormTagsExceptInput(element) {
   return FORM_TAGS.includes(getTag(element)) && element.hasAttribute('required')
 }

src/utils.js

@@ -133,6 +133,10 @@ function normalize(text) {
   return text.replace(/\s+/g, ' ').trim()
 }
 
+function getTag(element) {
+  return element.tagName && element.tagName.toLowerCase()
+}
+
 export {
   HtmlElementTypeError,
   checkHtmlElement,
@@ -141,4 +145,5 @@ export {
   getMessage,
   matches,
   normalize,
+  getTag,
 }