Add toBeReadonly matcher

README.md

@@ -68,6 +68,7 @@ clear to read and to maintain.
   - [`toHaveValue`](#tohavevalue)
   - [`toHaveDisplayValue`](#tohavedisplayvalue)
   - [`toBeChecked`](#tobechecked)
+  - [`toBeReadonly`](#tobereadonly)
 - [Deprecated matchers](#deprecated-matchers)
   - [`toBeInTheDOM`](#tobeinthedom)
 - [Inspiration](#inspiration)
@@ -86,9 +87,11 @@ should be installed as one of your project's `devDependencies`:
 ```
 npm install --save-dev @testing-library/jest-dom
 ```
-or 
+
+or
 
 for installation with [yarn](https://yarnpkg.com/) package manager.
+
 ```
 yarn add --dev @testing-library/jest-dom
 ```
@@ -886,6 +889,63 @@ expect(ariaSwitchChecked).toBeChecked()
 expect(ariaSwitchUnchecked).not.toBeChecked()
 ```
 
+<hr />
+
+### `toBeReadonly`
+
+```typescript
+toBeReadonly()
+```
+
+This allows you to check if a form element is readonly.
+
+An element is readonly if it is having a `readonly` or `aria-readonly="true"`
+attribute.
+
+#### Examples
+
+```html
+<input data-testid="readonly-input" readonly />
+<input data-testid="aria-readonly-input" aria-readonly="true" />
+<input data-testid="conflicted-input" readonly aria-readonly="false" />
+<input data-testid="aria-not-readonly-input" aria-readonly="false" />
+<input data-testid="optional-input" />
+<input data-testid="unsupported-type" type="image" readonly />
+<textarea data-testid="textarea" readonly></textarea>
+<table role="grid">
+  <thead>
+    <tr>
+      <th
+        role="columnheader"
+        aria-readonly="true"
+        data-testid="supported-role-aria"
+      >
+        The table header
+      </th>
+      <th role="columnheader" data-testid="supported-role">The table header</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>The table body</td>
+      <td>The table body</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+```javascript
+expect(getByTestId('readonly-input')).toBeReadonly()
+expect(getByTestId('aria-readonly-input')).toBeReadonly()
+expect(getByTestId('conflicted-input')).toBeReadonly()
+expect(getByTestId('aria-not-readonly-input')).not.toBeReadonly()
+expect(getByTestId('optional-input')).not.toBeReadonly()
+expect(getByTestId('unsupported-type')).not.toBeReadonly()
+expect(getByTestId('textarea')).toBeReadonly()
+expect(getByTestId('supported-role')).not.toBeReadonly()
+expect(getByTestId('supported-role-aria')).toBeReadonly()
+```
+
 ## Deprecated matchers
 
 ### `toBeInTheDOM`
@@ -1026,6 +1086,7 @@ Thanks goes to these people ([emoji key][emojis]):
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.

src/__tests__/to-be-readonly.js

@@ -0,0 +1,215 @@
+import {render} from './helpers/test-utils'
+
+test('handles textarea', () => {
+  const {queryByTestId} = render(`
+    <textarea readonly data-testid="textarea-element-readonly"></textarea>
+    <textarea  data-testid="textarea-element"></textarea>
+  `)
+
+  expect(queryByTestId('textarea-element-readonly')).toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('textarea-element')).toBeReadonly(),
+  ).toThrowError()
+  expect(queryByTestId('textarea-element')).not.toBeReadonly()
+})
+
+test('handles text input', () => {
+  const {queryByTestId} = render(`
+    <input type="text" readonly data-testid="text-input-readonly" />
+    <input type="text" data-testid="text-input" />
+  `)
+
+  expect(queryByTestId('text-input-readonly')).toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('text-input-readonly')).not.toBeReadonly(),
+  ).toThrowError()
+  expect(queryByTestId('text-input')).not.toBeReadonly()
+})
+
+test('handles search input', () => {
+  const {queryByTestId} = render(`
+    <input type="search" readonly data-testid="search-input-readonly" />
+    <input type="search" data-testid="search-input" />
+  `)
+
+  expect(queryByTestId('search-input-readonly')).toBeReadonly()
+  expect(queryByTestId('search-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('search-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles url input', () => {
+  const {queryByTestId} = render(`
+    <input type="url" readonly data-testid="url-input-readonly" />
+    <input type="url" data-testid="url-input" />
+  `)
+
+  expect(queryByTestId('url-input-readonly')).toBeReadonly()
+  expect(queryByTestId('url-input')).not.toBeReadonly()
+  expect(() => expect(queryByTestId('url-input')).toBeReadonly()).toThrowError()
+})
+
+test('handles email input', () => {
+  const {queryByTestId} = render(`
+    <input type="email" readonly data-testid="email-input-readonly" />
+    <input type="email" data-testid="email-input" />
+  `)
+
+  expect(queryByTestId('email-input-readonly')).toBeReadonly()
+  expect(queryByTestId('email-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('email-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles password input', () => {
+  const {queryByTestId} = render(`
+    <input type="password" readonly data-testid="password-input-readonly" />
+    <input type="password" data-testid="password-input" />
+  `)
+
+  expect(queryByTestId('password-input-readonly')).toBeReadonly()
+  expect(queryByTestId('password-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('password-input-readonly')).not.toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles date input', () => {
+  const {queryByTestId} = render(`
+    <input type="date" readonly data-testid="date-input-readonly" />
+    <input type="date" data-testid="date-input" />
+  `)
+
+  expect(queryByTestId('date-input-readonly')).toBeReadonly()
+  expect(queryByTestId('date-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('date-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles month input', () => {
+  const {queryByTestId} = render(`
+    <input type="month" readonly data-testid="month-input-readonly" />
+    <input type="month" data-testid="month-input" />
+  `)
+
+  expect(queryByTestId('month-input-readonly')).toBeReadonly()
+  expect(queryByTestId('month-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('month-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles week input', () => {
+  const {queryByTestId} = render(`
+    <input type="week" readonly data-testid="week-input-readonly" />
+    <input type="week" data-testid="week-input" />
+  `)
+
+  expect(queryByTestId('week-input-readonly')).toBeReadonly()
+  expect(queryByTestId('week-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('week-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles time input', () => {
+  const {queryByTestId} = render(`
+    <input type="time" readonly data-testid="time-input-readonly" />
+    <input type="time" data-testid="time-input" />
+  `)
+
+  expect(queryByTestId('time-input-readonly')).toBeReadonly()
+  expect(queryByTestId('time-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('time-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles datetime-local input', () => {
+  const {queryByTestId} = render(`
+    <input type="datetime-local" readonly data-testid="datetime-local-input-readonly" />
+    <input type="datetime-local" data-testid="datetime-local-input" />
+  `)
+
+  expect(queryByTestId('datetime-local-input-readonly')).toBeReadonly()
+  expect(queryByTestId('datetime-local-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('datetime-local-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles number input', () => {
+  const {queryByTestId} = render(`
+    <input type="number" readonly data-testid="number-input-readonly" />
+    <input type="number" data-testid="number-input" />
+  `)
+
+  expect(queryByTestId('number-input-readonly')).toBeReadonly()
+  expect(queryByTestId('number-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('number-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles input with no type', () => {
+  const {queryByTestId} = render(`
+    <input readonly data-testid="number-input-readonly" />
+    <input data-testid="number-input" />
+  `)
+
+  expect(queryByTestId('number-input-readonly')).toBeReadonly()
+  expect(queryByTestId('number-input')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('number-input')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles supported aria roles', () => {
+  const {queryByTestId} = render(`
+    <table role="grid">
+      <thead>
+        <tr>
+          <th role="columnheader" aria-readonly="true" data-testid="supported-role-aria">The table header</th>
+          <th role="columnheader" data-testid="supported-role">The table header</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>The table body</td>
+          <td>The table body</td>
+        </tr>
+      </tbody>
+    </table>
+  `)
+
+  expect(queryByTestId('supported-role-aria')).toBeReadonly()
+  expect(queryByTestId('supported-role')).not.toBeReadonly()
+  expect(() =>
+    expect(queryByTestId('supported-role')).toBeReadonly(),
+  ).toThrowError()
+})
+
+test('handles an unsupported elements', () => {
+  const {queryByTestId} = render(`
+    <div readonly data-testid="unsupported-element-type" />
+  `)
+
+  expect(queryByTestId('unsupported-element-type')).not.toBeRequired()
+  expect(() =>
+    expect(queryByTestId('unsupported-element-type')).toBeRequired(),
+  ).toThrowError()
+})
+
+test('handles an unsupported input type', () => {
+  const {queryByTestId} = render(`
+    <input type="image" readonly data-testid="unsupported-input-type" />
+  `)
+
+  expect(queryByTestId('unsupported-input-type')).not.toBeRequired()
+  expect(() =>
+    expect(queryByTestId('unsupported-input-type')).toBeRequired(),
+  ).toThrowError()
+})

src/matchers.js

@@ -16,6 +16,7 @@ import {toBeInvalid, toBeValid} from './to-be-invalid'
 import {toHaveValue} from './to-have-value'
 import {toHaveDisplayValue} from './to-have-display-value'
 import {toBeChecked} from './to-be-checked'
+import {toBeReadonly} from './to-be-readonly'
 
 export {
   toBeInTheDOM,
@@ -38,4 +39,5 @@ export {
   toHaveValue,
   toHaveDisplayValue,
   toBeChecked,
+  toBeReadonly,
 }

src/to-be-readonly.js

@@ -0,0 +1,74 @@
+import {matcherHint, printReceived} from 'jest-matcher-utils'
+import {checkHtmlElement, getTag} from './utils'
+
+const SUPPORTED_INPUT_TYPES = [
+  'text',
+  'search',
+  'url',
+  'tel',
+  'email',
+  'password',
+  'date',
+  'month',
+  'week',
+  'time',
+  'datetime-local',
+  'number',
+]
+
+const SUPPORTED_ARIA_TAGS = ['input', 'textarea', 'table', 'td', 'th']
+
+const SUPPORTED_ARIA_ROLES = [
+  'grid',
+  'gridcell',
+  'textbox',
+  'columnheader',
+  'rowheader',
+  'treegrid',
+]
+
+function isReadOnlyTextarea(element) {
+  return getTag(element) === 'textarea' && element.hasAttribute('readonly')
+}
+
+function isReadonlyOnSupportedInput(element) {
+  return (
+    getTag(element) === 'input' &&
+    element.hasAttribute('readonly') &&
+    ((element.hasAttribute('type') &&
+      SUPPORTED_INPUT_TYPES.includes(element.getAttribute('type'))) ||
+      !element.hasAttribute('type'))
+  )
+}
+
+function isElementRequiredByARIA(element) {
+  return (
+    element.hasAttribute('aria-readonly') &&
+    element.getAttribute('aria-readonly') === 'true' &&
+    SUPPORTED_ARIA_TAGS.includes(getTag(element)) &&
+    element.hasAttribute('role') &&
+    SUPPORTED_ARIA_ROLES.includes(element.getAttribute('role'))
+  )
+}
+
+export function toBeReadonly(element) {
+  checkHtmlElement(element, toBeReadonly, this)
+
+  const isReadonly =
+    isReadOnlyTextarea(element) ||
+    isReadonlyOnSupportedInput(element) ||
+    isElementRequiredByARIA(element)
+
+  return {
+    pass: isReadonly,
+    message: () => {
+      const is = isReadonly ? 'is' : 'is not'
+      return [
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeReadonly`, 'element', ''),
+        '',
+        `Received element ${is} readonly:`,
+        `  ${printReceived(element.cloneNode(false))}`,
+      ].join('\n')
+    },
+  }
+}