Optional message: stringAllows you to check whether an element is disabled from the user's perspective.
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.
<button
data-testid="button"
type="submit"
disabled
>
submit
</button>
expect(getByTestId('button')).toBeDisabled()
Allows you to check whether an element is not disabled from the user's perspective.
Works like not.toBeDisabled().
Use this matcher to avoid double negation in your tests.
<button
data-testid="button"
type="submit"
>
submit
</button>
expect(getByTestId('button')).toBeEnabled()
Optional container: HTMLElement | SVGElementsince v1.9.0
Assert whether a value is a DOM element, or not. Contrary to what its name implies, this matcher only checks that you passed to it a valid DOM element.
It does not have a clear definition of what "the DOM" is. Therefore, it does not check whether that element is contained anywhere.
Check if a form element, or the entire form, is currently invalid.
An input, select, textarea, or form 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.
<input data-testid="no-aria-invalid" />
<form data-testid="invalid-form">
<input required />
</form>
expect(getByTestId('no-aria-invalid')).not.toBeInvalid()
expect(getByTestId('invalid-form')).toBeInvalid()
This allows you to check whether the given element is partially checked. It accepts an input of type checkbox and elements with a role of checkbox with a aria-checked="mixed", or input of type checkbox with indeterminate set to true
<input type="checkbox" aria-checked="mixed" data-testid="aria-checkbox-mixed" />
<input type="checkbox" checked data-testid="input-checkbox-checked" />
<input type="checkbox" data-testid="input-checkbox-unchecked" />
<div role="checkbox" aria-checked="true" data-testid="aria-checkbox-checked" />
<div
role="checkbox"
aria-checked="false"
data-testid="aria-checkbox-unchecked"
/>
<input type="checkbox" data-testid="input-checkbox-indeterminate" />
const ariaCheckboxMixed = getByTestId('aria-checkbox-mixed')
const inputCheckboxChecked = getByTestId('input-checkbox-checked')
const inputCheckboxUnchecked = getByTestId('input-checkbox-unchecked')
const ariaCheckboxChecked = getByTestId('aria-checkbox-checked')
const ariaCheckboxUnchecked = getByTestId('aria-checkbox-unchecked')
const inputCheckboxIndeterminate = getByTestId('input-checkbox-indeterminate')
expect(ariaCheckboxMixed).toBePartiallyChecked()
expect(inputCheckboxChecked).not.toBePartiallyChecked()
expect(inputCheckboxUnchecked).not.toBePartiallyChecked()
expect(ariaCheckboxChecked).not.toBePartiallyChecked()
expect(ariaCheckboxUnchecked).not.toBePartiallyChecked()
inputCheckboxIndeterminate.indeterminate = true
expect(inputCheckboxIndeterminate).toBePartiallyChecked()
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.
<input data-testid="required-input" required />
<div
data-testid="supported-role"
role="tree"
required />
expect(getByTestId('required-input')).toBeRequired()
expect(getByTestId('supported-role')).not.toBeRequired()
Allows you to check if a form element is currently required.
An input, select, textarea, or form element is invalid if it has an aria-invalid attribute with no
value or a value of "false", or if the result of checkValidity() is true.
<input data-testid="aria-invalid" aria-invalid />
<form data-testid="valid-form">
<input />
</form>
expect(getByTestId('no-aria-invalid')).not.toBeValid()
expect(getByTestId('invalid-form')).toBeInvalid()
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:
<details /> it has the open attribute<div
data-testid="zero-opacity"
style="opacity: 0"
>
Zero Opacity
</div>
<div data-testid="visible">Visible Example</div>
expect(getByTestId('zero-opacity')).not.toBeVisible()
expect(getByTestId('visible')).toBeVisible()
Allows you to assert whether an element contains another element as a descendant or not.
<span data-testid="ancestor">
<span data-testid="descendant"></span>
</span>
const ancestor = getByTestId('ancestor')
const descendant = getByTestId('descendant')
const nonExistantElement = getByTestId('does-not-exist')
expect(ancestor).toContainElement(descendant)
expect(descendant).not.toContainElement(ancestor)
expect(ancestor).not.toContainElement(nonExistantElement)
Assert whether a string representing a HTML element is contained in another element.
<span data-testid="parent"><span data-testid="child"></span></span>
expect(getByTestId('parent')).toContainHTML('<span data-testid="child"></span>')
Optional text: anyThis allows to assert that an element has the expected accessible description.
You can pass the exact string of the expected accessible description, or you can make a partial match passing a regular expression, or by using either expect.stringContaining or expect.stringMatching.
<a data-testid="link" href="/" aria-label="Home page" title="A link to start over">Start</a>
<a data-testid="extra-link" href="/about" aria-label="About page">About</a>
<img src="avatar.jpg" data-testid="avatar" alt="User profile pic" />
<img src="logo.jpg" data-testid="logo" alt="Company logo" aria-describedby="t1" />
<span id="t1" role="presentation">The logo of Our Company</span>
expect(getByTestId('link')).toHaveAccessibleDescription()
expect(getByTestId('link')).toHaveAccessibleDescription('A link to start over')
expect(getByTestId('link')).not.toHaveAccessibleDescription('Home page')
expect(getByTestId('extra-link')).not.toHaveAccessibleDescription()
expect(getByTestId('avatar')).not.toHaveAccessibleDescription()
expect(getByTestId('logo')).not.toHaveAccessibleDescription('Company logo')
expect(getByTestId('logo')).toHaveAccessibleDescription('The logo of Our Company')
Optional text: anyThis allows you to assert that an element has the expected accessible error message.
You can pass the exact string of the expected accessible error message. Alternatively, you can perform a partial match by passing a regular expression or by using either expect.stringContaining or expect.stringMatching.
<input aria-label="Has Error" aria-invalid="true" aria-errormessage="error-message" />
<div id="error-message" role="alert">This field is invalid</div>
<input aria-label="No Error Attributes" />
<input aria-label="Not Invalid" aria-invalid="false" aria-errormessage="error-message" />
// Inputs with Valid Error Messages
expect(getByRole('textbox', {name: 'Has Error'})).toHaveAccessibleErrorMessage()
expect(getByRole('textbox', {name: 'Has Error'})).toHaveAccessibleErrorMessage('This field is invalid')
expect(getByRole('textbox', {name: 'Has Error'})).toHaveAccessibleErrorMessage(/invalid/i)
expect(
getByRole('textbox', {name: 'Has Error'}),
).not.toHaveAccessibleErrorMessage('This field is absolutely correct!')
// Inputs without Valid Error Messages
expect(
getByRole('textbox', {name: 'No Error Attributes'}),
).not.toHaveAccessibleErrorMessage()
expect(
getByRole('textbox', {name: 'Not Invalid'}),
).not.toHaveAccessibleErrorMessage()
Optional text: anyThis allows 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.
You can pass the exact string of the expected accessible name, or you can make a partial match passing a regular expression, or by using either expect.stringContaining or expect.stringMatching.
<img data-testid="img-alt" src="" alt="Test alt" />
<img data-testid="img-empty-alt" src="" alt="" />
<svg data-testid="svg-title"><title>Test title</title></svg>
<button data-testid="button-img-alt"><img src="" alt="Test" /></button>
<p><img data-testid="img-paragraph" src="" alt="" /> Test content</p>
<button data-testid="svg-button"><svg><title>Test</title></svg></p>
<div><svg data-testid="svg-without-title"></svg></div>
<input data-testid="input-title" title="test" />
expect(getByTestId('img-alt')).toHaveAccessibleName('Test alt')
expect(getByTestId('img-empty-alt')).not.toHaveAccessibleName()
expect(getByTestId('svg-title')).toHaveAccessibleName('Test title')
expect(getByTestId('button-img-alt')).toHaveAccessibleName()
expect(getByTestId('img-paragraph')).not.toHaveAccessibleName()
expect(getByTestId('svg-button')).toHaveAccessibleName()
expect(getByTestId('svg-without-title')).not.toHaveAccessibleName()
expect(getByTestId('input-title')).toHaveAccessibleName()
Optional value: unknownAllows you to check if a given element has an attribute or not.
You can also optionally check that the attribute has a specific expected value or partial match using expect.stringContaining or expect.stringMatching.
<button
data-testid="ok-button"
type="submit"
disabled
>
ok
</button>
expect(button).toHaveAttribute('disabled')
expect(button).toHaveAttribute('type', 'submit')
expect(button).not.toHaveAttribute('type', 'button')
Rest ...classNames: (string | RegExp)[]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.
<button
data-testid="delete-button"
class="btn xs btn-danger"
>
delete item
</button>
<div data-testid="no-classes">no classes</div>
const deleteButton = getByTestId('delete-button')
const noClasses = getByTestId('no-classes')
expect(deleteButton).toHaveClass('btn')
expect(deleteButton).toHaveClass('btn-danger xs')
expect(deleteButton).toHaveClass(/danger/, 'xs')
expect(deleteButton).toHaveClass('btn xs btn-danger', {exact: true})
expect(deleteButton).not.toHaveClass('btn xs btn-danger', {exact: true})
expect(noClasses).not.toHaveClass()
Optional options: { Optional text: anysince v5.14.1
Check the accessible description for an element. This allows you to check whether the given element has a description or not.
An element gets its description via the
aria-describedby attribute.
Set this to the id of one or more other elements. These elements may be nested
inside, be outside, or a sibling of the passed in element.
Whitespace is normalized. Using multiple ids will join the referenced elements’ text content separated by a space.
When a string argument is passed through, it will perform a whole
case-sensitive match to the description text.
To perform a case-insensitive match, you can use a RegExp with the /i
modifier.
To perform a partial match, you can pass a RegExp or use
expect.stringContaining("partial string").
<button aria-label="Close" aria-describedby="description-close">
X
</button>
<div id="description-close">
Closing will discard any changes
</div>
<button>Delete</button>
const closeButton = getByRole('button', {name: 'Close'})
expect(closeButton).toHaveDescription('Closing will discard any changes')
expect(closeButton).toHaveDescription(/will discard/) // to partially match
expect(closeButton).toHaveDescription(expect.stringContaining('will discard')) // to partially match
expect(closeButton).toHaveDescription(/^closing/i) // to use case-insensitive match
expect(closeButton).not.toHaveDescription('Other description')
const deleteButton = getByRole('button', {name: 'Delete'})
expect(deleteButton).not.toHaveDescription()
expect(deleteButton).toHaveDescription('') // Missing or empty description always becomes a blank string
Description
Assert whether the given element is checked.
It accepts an
inputof typecheckboxorradioand elements with aroleofradiowith a validaria-checkedattribute of "true" or "false".Example
See
testing-library/jest-dom#tobechecked