Custom Jasmine matchers for testing DOM elements
npm install @testing-library/jasmine-domCustom Jasmine matchers to test the state of the DOM
---
[![Build Status][build-badge]][build]
[![Code Coverage][coverage-badge]][coverage]
[![semantic-release][semantic-release-badge]][semantic-release]
[![version][version-badge]][package]
[![downloads][downloads-badge]][npmtrends]
[![MIT License][license-badge]][license]

[![PRs Welcome][prs-badge]][prs]
[![Code of Conduct][coc-badge]][coc]
[![Discord][discord-badge]][discord]
[![Watch on GitHub][github-watch-badge]][github-watch]
[![Star on GitHub][github-star-badge]][github-star]
[![Tweet][twitter-badge]][twitter]
You want to use [Jasmine][jasmine] to write tests that assert various things about the state of the DOM. As part of that goal, you want to avoid all the repetitive patterns that arise in doing so. Checking for an element's attributes, its text content, its css classes, you name it.
The jasmine-dom library provides a set of custom Jasmine matchers that you can use to extend Jasmine. These will make your tests more declarative, clear to read and to maintain.
- Installation
- Usage
- Custom matchers
- toBeDisabled
- toBeEnabled
- toBeEmptyDOMElement
- toBeInTheDocument
- toBeInvalid
- toBeRequired
- toBeValid
- toBeVisible
- toContainHTML
- toContainElement
- toHaveAccessibleDescription
- toHaveAccessibleName
- toHaveAttribute
- toHaveClassName
- toHaveFocus
- toHaveFormValues
- toHaveStyle
- toHaveTextContent
- toHaveValue
- toHaveDisplayValue
- toBeChecked
- toBePartiallyChecked
- toHaveErrorMessage
- toHaveDescription
- Inspiration
- Other Solutions
- Guiding Principles
- Contributors
- LICENSE
This module is distributed via [npm][npm] which is bundled with [node][node] and should be installed as one of your project's devDependencies.
Using npm:
```
npm install --save-dev @testing-library/jasmine-dom
or for installation using [yarn][yarn] package manager:
``
yarn add --dev @testing-library/jasmine-dom
You should have a directory for helpers specified inside the helpers array in your jasmine.json file.
Example:
`json`
{
"spec_dir": "src/__tests__",
"spec_files": ["*/.test.js"],
"helpers": ["helpers/*/.js"],
"stopSpecOnExpectationFailure": false,
"random": false
}
Make a new file inside that directory, import @testing-library/jasmine-dom and add the matchers like so:
`javascript
import JasmineDOM from '@testing-library/jasmine-dom';
beforeAll(() => {
jasmine.getEnv().addMatchers(JasmineDOM);
});
`
Add "@testing-library/jasmine-dom" to types in the tests tsconfig (e.g. tsconfig.spec.json in an Angular project).
Example:
`json`
{
"compilerOptions": {
"types": ["jasmine", "node", "@testing-library/jasmine-dom"]
}
}
In your tests setup file, (test.ts in an Angular project) import jasmine-dom and add the matchers like so:
`typescript
import JasmineDOM from '@testing-library/jasmine-dom/dist';
beforeAll(() => {
jasmine.getEnv().addMatchers(JasmineDOM);
});
`
This library is meant to be a Jasmine version of @testing-library/jest-dom library. As such, it provides the same set of matchers and the same functionality for each one, with a couple of minor diferences:
- toBeEmpty() is not included, in favor of toBeEmptyDOMElement()toBeInTheDOM()
- is not included, since it's deprecatedtoHaveClass()
- is renamed as toHaveClassName() to prevent name collision with Jasmine's toHaveClass()
`typescript`
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 isdisabled
specified on this element or the element is a descendant of a form element with
a attribute.
According to the specification, the following elements can be
actually disabled:
button, input, select, textarea, optgroup, option, fieldset.
#### Examples
`html`
link
`javascript`
expect(getByTestId('button')).toBeDisabled();
expect(getByTestId('input')).toBeDisabled();
expect(getByText('link')).not.toBeDisabled();
`typescript`
toBeEnabled();
This allows you to check whether an element is not disabled from the user's
perspective.
It works like not.toBeDisabled(). Use this matcher to avoid double negation in
your tests.
`typescript`
toBeEmptyDOMElement();
This allows you to assert whether an element has content or not.
#### Examples
`html`
`javascript`
expect(getByTestId('empty')).toBeEmptyDOMElement();
expect(getByTestId('not-empty')).not.toBeEmptyDOMElement();
`typescript`
toBeInTheDocument();
This allows you to assert whether an element is present in the document or not.
#### Examples
`html`
Html Element
`javascript`
expect(getByTestId(document.documentElement, 'html-element')).toBeInTheDocument();
expect(getByTestId(document.documentElement, 'svg-element')).toBeInTheDocument();
expect(queryByTestId(document.documentElement, 'does-not-exist')).not.toBeInTheDocument();
> Note: This matcher does not find detached elements. The element must be added
> to the document to be found by toBeInTheDocument. If you desire to search in a
> detached element please use: toContainElement
`typescript`
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 ofcheckValidity()false
is .
#### Examples
`html
`javascript
expect(getByTestId('no-aria-invalid')).not.toBeInvalid();
expect(getByTestId('aria-invalid')).toBeInvalid();
expect(getByTestId('aria-invalid-value')).toBeInvalid();
expect(getByTestId('aria-invalid-false')).not.toBeInvalid();expect(getByTestId('valid-form')).not.toBeInvalid();
expect(getByTestId('invalid-form')).toBeInvalid();
`
$3
`typescript
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.#### Examples
`html
``javascript
expect(getByTestId('required-input')).toBeRequired();
expect(getByTestId('aria-required-input')).toBeRequired();
expect(getByTestId('conflicted-input')).toBeRequired();
expect(getByTestId('aria-not-required-input')).not.toBeRequired();
expect(getByTestId('optional-input')).not.toBeRequired();
expect(getByTestId('unsupported-type')).not.toBeRequired();
expect(getByTestId('select')).toBeRequired();
expect(getByTestId('textarea')).toBeRequired();
expect(getByTestId('supported-role')).not.toBeRequired();
expect(getByTestId('supported-role-aria')).toBeRequired();
`
$3
`typescript
toBeValid();
`This allows you to check if the value of an element, is currently valid.
aria-invalid attributes
or an attribute value of "false". The result of
checkValidity()
must also be true if it's a form element.#### Examples
`html
``javascript
expect(getByTestId('no-aria-invalid')).toBeValid();
expect(getByTestId('aria-invalid')).not.toBeValid();
expect(getByTestId('aria-invalid-value')).not.toBeValid();
expect(getByTestId('aria-invalid-false')).toBeValid();expect(getByTestId('valid-form')).toBeValid();
expect(getByTestId('invalid-form')).not.toBeValid();
`
$3
`typescript
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 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 it has the open attribute#### Examples
`html
Zero Opacity Example
Hidden Parent Example
Visible Example
Hidden Attribute Example
``javascript
expect(getByText('Zero Opacity Example')).not.toBeVisible();
expect(getByText('Visibility Hidden Example')).not.toBeVisible();
expect(getByText('Display None Example')).not.toBeVisible();
expect(getByText('Hidden Parent Example')).not.toBeVisible();
expect(getByText('Visible Example')).toBeVisible();
expect(getByText('Hidden Attribute Example')).not.toBeVisible();
`
$3
`typescript
toContainHTML(htmlText: string)
`Assert whether a string representing a HTML element is contained in another
element. The string should contain valid html, and not any incomplete html.
#### Examples
`html
``javascript
// These are valid uses
expect(getByTestId('parent')).toContainHTML('');
expect(getByTestId('parent')).toContainHTML('');
expect(getByTestId('parent')).not.toContainHTML('
');// These won't work
expect(getByTestId('parent')).toContainHTML('data-testid="child"');
expect(getByTestId('parent')).toContainHTML('data-testid');
expect(getByTestId('parent')).toContainHTML('');
`> Chances are you probably do not need to use this matcher. We encourage testing
> from the perspective of how the user perceives the app in a browser. That's
> why testing against a specific DOM structure is not advised.
>
> It could be useful in situations where the code being tested renders html that
> was obtained from an external source, and you want to validate that that html
> code was used as intended.
>
> It should not be used to check DOM structure that you control. Please use
>
toContainElement instead.
$3
`typescript
toContainElement(element: HTMLElement | SVGElement | null)
`This allows you to assert whether an element contains another element as a
descendant or not.
#### Examples
`html
``javascript
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);
`
$3
`typescript
toHaveAccessibleDescription(expectedAccessibleDescription?: string | RegExp)
`This allows you 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
jasmine.stringContaining/jasmine.stringMatching.
#### Examples
`html
Start
About


The logo of Our Company
``js
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');
`
$3
`typescript
toHaveAccessibleName(expectedAccessibleName?: string | RegExp)
`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.
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
jasmine.stringContaining/jasmine.stringMatching.
#### Examples
`html
![Test alt]()
![]()
Test content
``javascript
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();
`
$3
`typescript
toHaveAttribute(attr: string, value?: any)
`This allows you to check whether the given element has an attribute or not. You
can also optionally check that the attribute has a specific expected value or
partial match using a RegExp.
#### Examples
`html
``javascript
const button = getByTestId('ok-button')expect(button).toHaveAttribute('disabled')
expect(button).toHaveAttribute('type', 'submit')
expect(button).not.toHaveAttribute('type', 'button')
expect(button).toHaveAttribute('type', /sub/))
expect(button).toHaveAttribute('type', /but/))
`
$3
`typescript
toHaveClassName(...classNames: string[], options?: {exact: boolean})
`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.
#### Examples
`html
``javascript
const deleteButton = getByTestId('delete-button');
const noClasses = getByTestId('no-classes');expect(deleteButton).toHaveClassName('extra');
expect(deleteButton).toHaveClassName('btn-danger btn');
expect(deleteButton).toHaveClassName('btn-danger', 'btn');
expect(deleteButton).not.toHaveClassName('btn-link');
expect(deleteButton).toHaveClassName('btn-danger extra btn', { exact: true }); // to check if the element has EXACTLY a set of classes
expect(deleteButton).not.toHaveClassName('btn-danger extra', { exact: true }); // if it has more than expected it is going to fail
expect(noClasses).not.toHaveClassName();
`
$3
`typescript
toHaveFocus();
`This allows you to assert whether an element has focus or not.
#### Examples
`html
``javascript
const input = getByTestId('element-to-focus');input.focus();
expect(input).toHaveFocus();
input.blur();
expect(input).not.toHaveFocus();
`
$3
`typescript
toHaveFormValues(expectedValues: {
[name: string]: any
})
`This allows you to check if a form or fieldset contains form controls for each
given name, and having the specified value.
> It is important to stress that this matcher can only be invoked on a [form][]
> or a [fieldset][] element.
>
> This allows it to take advantage of the [.elements][] property in
form and
> fieldset to reliably fetch all form controls within them.
>
> This also avoids the possibility that users provide a container that contains
> more than one form, thereby intermixing form controls that are not related,
> and could even conflict with one another.This matcher abstracts away the particularities with which a form control value
is obtained depending on the type of form control. For instance,
elements have a value attribute, but