Jest DOMDocs

toBeDisabled toBeEmptyDOMElement toBeInTheDocument toBeRequired toBeValid toBeInvalid

toBeVisible toContainElement toHaveAccessibleDescription toHaveAccessibleName toHaveAttribute toHaveClass

toHaveFocus toHaveFormValues toHaveTextContent toHaveValue toHaveDisplayValue toBeChecked

toBeDisabled

This allows you to check whether an element is disabled from the user's perspective. According to the specification, the following elements can be disabled: button, input, select, textarea, optgroup, option, fieldset, and custom elements. This custom matcher considers an element as disabled if the element is among the types of elements that can be disabled (listed above), and the disabled attribute is present. It will also consider the element as disabled if it's inside a parent form element that supports being disabled and has the disabled attribute present.

Example Test :

<button data-testid="button-native-disabled" type="submit" disabled>
  Button Native Disabled
</button>
<input type="text" data-testid="input-native-disabled" placeholder='Input Native Disabled' disabled />
<a data-testid="link-toBeDisabled" href="#" disabled>link</a>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeDisabled', () => {
  render(<Native />)
  const button = screen.getByTestId('button-native-disabled')
  const input = screen.getByTestId('input-native-disabled')
  const aTag = screen.getByTestId('link-toBeDisabled')
  expect(button).toBeDisabled()
  expect(input).toBeDisabled()
  expect(aTag).not.toBeDisabled()
})

toBeEmptyDOMElement

This allows you to assert whether an element has no visible content for the user. It ignores comments but will fail if the element contains white-space.

Example Test :

<span data-testid="not-empty">
  <span data-testid="empty"></span>
</span>
<span data-testid="with-whitespace"> </span>
<span data-testid="with-comment">{/* comment */}</span>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeEmptyDOMElement', () => {
  render(<Native />)
  expect(screen.queryByTestId('empty')).toBeEmptyDOMElement()
  expect(screen.queryByTestId('not-empty')).not.toBeEmptyDOMElement()
  expect(screen.queryByTestId('with-whitespace')).not.toBeEmptyDOMElement()
})

toBeInTheDocument

This allows you to assert whether an element is present in the document or not.

Html Element

Example Test :

<span data-testid="html-element">
  <span className="dark:text-white text-sm">Html Element</span>
</span>
<svg data-testid="svg-element" className="border border-red-500 rounded mt-2"></svg>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeInTheDocument', () => {
  render(<Native />)
  expect(screen.getByTestId('html-element'),).toBeInTheDocument()
  expect(screen.getByTestId('svg-element')).toBeInTheDocument()
  expect(screen.queryByTestId('does-not-exist'),).not.toBeInTheDocument()
})

toBeRequired

This allows you to check if a form element is currently required. An element is required if it is having a required or aria-required="true" attribute.

Example Test :

<input data-testid="required-input" required />
<input data-testid="aria-required-input" aria-required="true" />
<input data-testid="conflicted-input" required aria-required="false" />
<input data-testid="aria-not-required-input" aria-required="false" />
<input data-testid="optional-input" />
<input data-testid="unsupported-type" type="image" required />
<select data-testid="select" required>
  <option value="optiona">Option A</option>
  <option value="optionb">Option B</option>
</select>
<textarea data-testid="textarea" required></textarea>
<div data-testid="supported-role" role="tree" required className="border border-red-500 h-10 rounded mt-2"></div>
<div data-testid="supported-role-aria" role="tree" aria-required="true" className="border border-red-500 h-10 rounded mt-2"></div>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeRequired', () => {
  render(<Native />)
  expect(screen.getByTestId('required-input')).toBeRequired()
  expect(screen.getByTestId('aria-required-input')).toBeRequired()
  expect(screen.getByTestId('conflicted-input')).toBeRequired()
  expect(screen.getByTestId('aria-not-required-input')).not.toBeRequired()
  expect(screen.getByTestId('optional-input')).not.toBeRequired()
  expect(screen.getByTestId('unsupported-type')).not.toBeRequired()
  expect(screen.getByTestId('select')).toBeRequired()
  expect(screen.getByTestId('textarea')).toBeRequired()
  expect(screen.getByTestId('supported-role')).not.toBeRequired()
  expect(screen.getByTestId('supported-role-aria')).toBeRequired()
})

toBeValid

This allows you to check if the value of an element, is currently valid. An element is valid if it has no aria-invalid attributes or an attribute value of "false". The result of checkValidity() must also be true if it's a form element.

Example Test :

<input data-testid="no-aria-invalidd" />
<input data-testid="aria-invalidd" aria-invalid />
<input data-testid="aria-invalid-valuee" aria-invalid="true" />
<input data-testid="aria-invalid-falsee" aria-invalid="false" />
<form data-testid="valid-formm">
  <input />
</form>
<form data-testid="invalid-formm">
  <input required />
</form>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeValid', () => {
  render(<Native />)
  expect(screen.getByTestId('no-aria-invalidd')).toBeValid()
  expect(screen.getByTestId('aria-invalidd')).not.toBeValid()
  expect(screen.getByTestId('aria-invalid-valuee')).not.toBeValid()
  expect(screen.getByTestId('aria-invalid-falsee')).toBeValid()
  expect(screen.getByTestId('valid-formm')).toBeValid()
  expect(screen.getByTestId('invalid-formm')).not.toBeValid()
})

toBeInvalid

This allows you to check if an element, is currently invalid. An element is invalid if it has an aria-invalid attribute with no value or a value of true, or if the result of checkValidity() is false. Examples

Example Test :

<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" />
<form data-testid="valid-form">
  <input />
</form>
<form data-testid="invalid-form">
  <input required />
</form>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeInvalid', () => {
  render(<Native />)
  expect(screen.getByTestId('no-aria-invalid')).not.toBeInvalid()
  expect(screen.getByTestId('aria-invalid')).toBeInvalid()
  expect(screen.getByTestId('aria-invalid-value')).toBeInvalid()
  expect(screen.getByTestId('aria-invalid-false')).not.toBeInvalid()
  expect(screen.getByTestId('valid-form')).not.toBeInvalid()
  expect(screen.getByTestId('invalid-form')).toBeInvalid()
})

toBeVisible

This allows you to check if an element is currently visible to the user. An element is visible if all the following conditions are met:

it is present in the document
it does not have its css property display set to none
it does not have its css property visibility set to either hidden or collapse
it does not have its css property opacity set to 0
its parent element is also visible (and so on up to the top of the DOM tree)
it does not have the hidden attribute
if details it has the open attribute

Zero Opacity Example

Visibility Hidden Example

Hidden Parent Example

Visible Example

Title of hidden text

Hidden Details Example

Title of visible text

Visible Details Example

Example Test :

<div data-testid="zero-opacity" style={{ opacity: 0 }}>Zero Opacity Example</div>
<div data-testid="visibility-hidden" style={{ visibility: 'hidden' }}>
  Visibility Hidden Example
</div>
<div data-testid="display-none" style={{ display: 'none' }}>Display None Example</div>
<div style={{ opacity: 0 }}>
  <span data-testid="hidden-parent">Hidden Parent Example</span>
</div>
<div data-testid="visible">Visible Example</div>
<div data-testid="hidden-attribute" hidden>Hidden Attribute Example</div>
<details data-testid="hidden-details">
  <summary>Title of hidden text</summary>
  Hidden Details Example
</details>
<details data-testid="visible-details" open>
  <summary>Title of visible text</summary>
  <div>Visible Details Example</div>
</details>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeVisible', () => {
  render(<Native />)
  expect(screen.getByTestId('zero-opacity')).not.toBeVisible()
  expect(screen.getByTestId('visibility-hidden')).not.toBeVisible()
  expect(screen.getByTestId('display-none')).not.toBeVisible()
  expect(screen.getByTestId('hidden-parent')).not.toBeVisible()
  expect(screen.getByTestId('visible')).toBeVisible()
  expect(screen.getByTestId('hidden-attribute')).not.toBeVisible()
  expect(screen.getByTestId('hidden-details')).not.toBeVisible()
  expect(screen.getByTestId('visible-details')).toBeVisible()
})

toContainElement

This allows you to assert whether an element contains another element as a descendant or not.

Example Test :

<span data-testid="ancestor">
  <span data-testid="descendant"></span>
</span>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toContainElement', () => {
  render(<Native />)
  const ancestor = screen.getByTestId('ancestor')
  const descendant = screen.getByTestId('descendant')
  expect(ancestor).toContainElement(descendant)
  expect(descendant).not.toContainElement(ancestor)
})

toHaveAccessibleDescription

This allows you to assert that an element has the expected accessible description.

Link to Start Link to About

The logo of Our Company

Example Test :

<a data-testid="link" href="#" aria-label="Home page" title="A link to start over">Link to Start</a>
<a data-testid="extra-link" href="#" aria-label="About page">Link to About</a>
<img src="favicon.ico" data-testid="avatar" alt="User profile pic" />
<img src="favicon.ico" data-testid="logo" alt="Company logo" aria-describedby="t1" />
<span id="t1" role="presentation">The logo of Our Company</span>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveAccessibleDescription', () => {
  render(<Native />)
  expect(screen.getByTestId('link')).toHaveAccessibleDescription()
  expect(screen.getByTestId('link')).toHaveAccessibleDescription('A link to start over')
  expect(screen.getByTestId('link')).not.toHaveAccessibleDescription('Home page')
  expect(screen.getByTestId('extra-link')).not.toHaveAccessibleDescription()
  expect(screen.getByTestId('avatar')).not.toHaveAccessibleDescription()
  expect(screen.getByTestId('logo')).not.toHaveAccessibleDescription('Company logo')
  expect(screen.getByTestId('logo')).toHaveAccessibleDescription(
    'The logo of Our Company',
  )
})

toHaveAccessibleName

This allows you to assert that an element has the expected accessible name. It is useful, for instance, to assert that form elements and buttons are properly labelled.

Test content

Example Test :

<img data-testid="img-alt" src="favicon.ico" alt="Test alt" className="h-20 w-20 my-2" />
<img data-testid="img-empty-alt" src="favicon.ico" alt="" className="h-20 w-20 my-2" />
<svg data-testid="svg-title" className="border border-red-500 rounded">
  <title>Test title</title>
</svg>
<button data-testid="button-img-alt">
  <img src="favicon.ico" alt="Test" className="h-20 w-20 my-2" />
</button>
<p className="dark:text-white text-sm mb-4">
  <img data-testid="img-paragraph" src="favicon.ico" alt="" className="h-20 w-20 my-2" />
  Test content
</p>
<button data-testid="svg-button" className="border rounded p-4">
  <svg className="border border-red-500 rounded p-4">
    <title>Test</title>
  </svg>
</button>
<div className="my-4">
  <svg data-testid="svg-without-title" className="border border-red-500 rounded"></svg>
</div>
<input data-testid="input-title" title="test" className={inputClassName} />

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveAccessibleName', () => {
  render(<Native />)
  expect(screen.getByTestId('img-alt')).toHaveAccessibleName('Test alt')
  expect(screen.getByTestId('img-empty-alt')).not.toHaveAccessibleName()
  expect(screen.getByTestId('svg-title')).toHaveAccessibleName('Test title')
  expect(screen.getByTestId('button-img-alt')).toHaveAccessibleName()
  expect(screen.getByTestId('img-paragraph')).not.toHaveAccessibleName()
  expect(screen.getByTestId('svg-button')).toHaveAccessibleName()
  expect(screen.getByTestId('svg-without-title')).not.toHaveAccessibleName()
  expect(screen.getByTestId('input-title')).toHaveAccessibleName()
})

toHaveAttribute

This allows you to check whether the given element has an attribute or not.

Example Test :

<button data-testid="ok-button" type="submit" disabled>
  Ok Button
</button>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveAttribute', () => {
  render(<Native />)
  const button = screen.getByTestId('ok-button')
  expect(button).toHaveAttribute('disabled')
  expect(button).toHaveAttribute('type', 'submit')
  expect(button).not.toHaveAttribute('type', 'button')
  expect(button).toHaveAttribute('type', expect.stringContaining('sub'))
  expect(button).toHaveAttribute('type', expect.not.stringContaining('but'))
})

toHaveClass

This allows you to check whether the given element has certain classes within its class attribute. You must provide at least one class, unless you are asserting that an element does not have any classes.

Example Test :

<button data-testid="delete-button" className="btn extra btn-danger">
  Delete item
</button>
<button data-testid="no-classes">No Classes</button>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveClass', () => {
  render(<Native />)
  const deleteButton = screen.getByTestId('delete-button')
  const noClasses = screen.getByTestId('no-classes')
  expect(deleteButton).toHaveClass('extra')
  expect(deleteButton).toHaveClass('btn-danger btn')
  expect(deleteButton).toHaveClass('btn-danger', 'btn')
  expect(deleteButton).not.toHaveClass('btn-link')
  // to check if the element has EXACTLY a set of classes
  expect(deleteButton).toHaveClass('btn extra btn-danger text-sm text-white py-1 px-2 block rounded my-3 bg-blue-500 hover:bg-blue-600 hover:cursor-pointer transition-all', { exact: true })
  // if it has more than expected it is going to fail
  expect(deleteButton).not.toHaveClass('btn-danger extra', { exact: true })
  expect(noClasses).not.toHaveClass()
})

toHaveFocus

This allows you to assert whether an element has focus or not.

Example Test :

<div>
  <input type="text" data-testid="element-to-focus" />
</div>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveFocus', () => {
  render(<Native />)
  const input = screen.getByTestId('element-to-focus')
  input.focus()
  expect(input).toHaveFocus()
  input.blur()
  expect(input).not.toHaveFocus()
})

toHaveFormValues

This allows you to check if a form or fieldset contains form controls for each given name, and having the specified value.

Example Test :

<form data-testid="login-form">
  <input type="text" name="username" value="john.doe" />
  <input type="password" name="password" value='12345678' />
  <input type="checkbox" name="rememberMe" checked="true"  />
  <button type="submit">Sign in</button>
</form>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveFormValues', () => {
  render(<Native />)
  expect(screen.getByTestId('login-form')).toHaveFormValues({
    username: 'john.doe',
    password: '12345678',
    rememberMe: true,
  })
})

toHaveTextContent

This allows you to check whether the given node has a text content or not. This supports elements, but also text nodes and fragments. When a string argument is passed through, it will perform a partial case-sensitive match to the node content. To perform a case-insensitive match, you can use a RegExp with the /i modifier. If you want to match the whole content, you can use a RegExp to do it.

Text Content

Example Test :

<span data-testid="text-content" className="dark:text-white">Text Content</span>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveTextContent', () => {
  render(<Native />)
  const element = screen.getByTestId('text-content')
  expect(element).toHaveTextContent('Content')
  // to match the whole content
  expect(element).toHaveTextContent(/^Text Content$/)
  // to use case-insensitive match
  expect(element).toHaveTextContent(/content$/i)
  expect(element).not.toHaveTextContent('content')
})

toHaveValue

This allows you to check whether the given form element has the specified value. It accepts <input>, <select> and <textarea> elements with the exception of <input type="checkbox"> and <input type="radio">, which can be meaningfully matched only using toBeChecked or toHaveFormValues. For all other form elements, the value is matched using the same algorithm as in toHaveFormValues does.

Example Test :

<input type="text" value="text" data-testid="input-text" />
<input type="number" value=5 data-testid="input-number" />
<input type="text" data-testid="input-empty" />
<select data-testid="select-number" value="second">
  <option value="first">First Value</option>
  <option value="second">Second Value</option>
  <option value="third">Third Value</option>
</select>

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveValue', () => {
  render(<Native />)
  const textInput = screen.getByTestId('input-text')
  const numberInput = screen.getByTestId('input-number')
  const emptyInput = screen.getByTestId('input-empty')
  const selectInput = screen.getByTestId('select-number')
  expect(textInput).toHaveValue('text')
  expect(numberInput).toHaveValue(5)
  expect(emptyInput).not.toHaveValue()
  expect(selectInput).toHaveValue('second')
})

toHaveDisplayValue

This allows you to check whether the given form element has the specified displayed value (the one the end user will see). It accepts <input>, <select> and <textarea> elements with the exception of <input type="checkbox"> and <input type="radio">, which can be meaningfully matched only using toBeChecked or toHaveFormValues.

First nameDescription

Example Test :

<label htmlFor="input-example">First name</label>
<input type="text" id="input-example" value="text" />
<label htmlFor="textarea-example">Description</label>
<textarea id="textarea-example" value="text" />

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toHaveDisplayValue', () => {
  render(<Native />)
  const input = screen.getByLabelText('First name')
  const textarea = screen.getByLabelText('Description')
  expect(input).toHaveDisplayValue('text')
  expect(input).toHaveDisplayValue(/tex/)
  expect(textarea).toHaveDisplayValue('text')
  expect(textarea).toHaveDisplayValue(/tex/)
})

toBeChecked

This allows you to check whether the given element is checked. It accepts an input of type checkbox or radio and elements with a role of checkbox, radio or switch with a valid aria-checked attribute of "true" or "false".

Example Test :

<input type="checkbox" checked=true data-testid="input-checkbox-checked" />
<input type="checkbox" data-testid="input-checkbox-unchecked" />
<input type="radio" checked=true value="foo" data-testid="input-radio-checked" />
<input type="radio" value="foo" data-testid="input-radio-unchecked" />

Example Test :

import { render, screen } from '@testing-library/react'
import '@testing-library/jest-dom'
import Native from '@/pages/native'

test('Test toBeChecked', () => {
  render(<Native />)
  const inputCheckboxChecked = screen.getByTestId('input-checkbox-checked')
  const inputCheckboxUnchecked = screen.getByTestId('input-checkbox-unchecked')
  expect(inputCheckboxChecked).toBeChecked()
  expect(inputCheckboxUnchecked).not.toBeChecked()

  const inputRadioChecked = screen.getByTestId('input-radio-checked')
  const inputRadioUnchecked = screen.getByTestId('input-radio-unchecked')
  expect(inputRadioChecked).toBeChecked()
  expect(inputRadioUnchecked).not.toBeChecked()
})