Interface JestAssertion<T>

interface JestAssertion<T> {
    lastCalledWith<E>(...args): void;
    lastReturnedWith<E>(value): void;
    nthCalledWith<E>(nthCall, ...args): void;
    nthReturnedWith<E>(nthCall, value): void;
    toBe<E>(expected): void;
    toBeCalled(): void;
    toBeCalledTimes(times): void;
    toBeCalledWith<E>(...args): void;
    toBeChecked(): void;
    toBeCloseTo(number, numDigits?): void;
    toBeDefined(): void;
    toBeDisabled(): void;
    toBeEmpty(): void;
    toBeEmptyDOMElement(): void;
    toBeEnabled(): void;
    toBeFalsy(): void;
    toBeGreaterThan(num): void;
    toBeGreaterThanOrEqual(num): void;
    toBeInTheDOM(container?): void;
    toBeInTheDocument(): void;
    toBeInstanceOf<E>(expected): void;
    toBeInvalid(): void;
    toBeLessThan(num): void;
    toBeLessThanOrEqual(num): void;
    toBeNaN(): void;
    toBeNull(): void;
    toBePartiallyChecked(): void;
    toBeRequired(): void;
    toBeTruthy(): void;
    toBeUndefined(): void;
    toBeValid(): void;
    toBeVisible(): void;
    toContain<E>(item): void;
    toContainElement(element): void;
    toContainEqual<E>(item): void;
    toContainHTML(htmlText): void;
    toEqual<E>(expected): void;
    toHaveAccessibleDescription(text?): void;
    toHaveAccessibleErrorMessage(text?): void;
    toHaveAccessibleName(text?): void;
    toHaveAttribute(attr, value?): void;
    toHaveBeenCalled(): void;
    toHaveBeenCalledTimes(times): void;
    toHaveBeenCalledWith<E>(...args): void;
    toHaveBeenLastCalledWith<E>(...args): void;
    toHaveBeenNthCalledWith<E>(n, ...args): void;
    toHaveClass(...classNames): void;
    toHaveClass(classNames, options?): void;
    toHaveDescription(text?): void;
    toHaveDisplayValue(value): void;
    toHaveErrorMessage(text?): void;
    toHaveFocus(): void;
    toHaveFormValues(expectedValues): void;
    toHaveLastReturnedWith<E>(value): void;
    toHaveLength(length): void;
    toHaveNthReturnedWith<E>(nthCall, value): void;
    toHaveProperty<E>(property, value?): void;
    toHaveReturned(): void;
    toHaveReturnedTimes(times): void;
    toHaveReturnedWith<E>(value): void;
    toHaveStyle(css): void;
    toHaveTextContent(text, options?): void;
    toHaveValue(value?): void;
    toMatch(expected): void;
    toMatchObject<E>(expected): void;
    toReturn(): void;
    toReturnTimes(times): void;
    toReturnWith<E>(value): void;
    toStrictEqual<E>(expected): void;
    toThrow(expected?): void;
    toThrowError(expected?): void;
}

Type Parameters

  • T = any

Hierarchy (view full)

Methods

lastCalledWith lastReturnedWith nthCalledWith nthReturnedWith toBe toBeCalled toBeCalledTimes toBeCalledWith toBeChecked toBeCloseTo toBeDefined toBeDisabled toBeEmpty toBeEmptyDOMElement toBeEnabled toBeFalsy toBeGreaterThan toBeGreaterThanOrEqual toBeInTheDOM toBeInTheDocument toBeInstanceOf toBeInvalid toBeLessThan toBeLessThanOrEqual toBeNaN toBeNull toBePartiallyChecked toBeRequired toBeTruthy toBeUndefined toBeValid toBeVisible toContain toContainElement toContainEqual toContainHTML toEqual toHaveAccessibleDescription toHaveAccessibleErrorMessage toHaveAccessibleName toHaveAttribute toHaveBeenCalled toHaveBeenCalledTimes toHaveBeenCalledWith toHaveBeenLastCalledWith toHaveBeenNthCalledWith toHaveClass toHaveDescription toHaveDisplayValue toHaveErrorMessage toHaveFocus toHaveFormValues toHaveLastReturnedWith toHaveLength toHaveNthReturnedWith toHaveProperty toHaveReturned toHaveReturnedTimes toHaveReturnedWith toHaveStyle toHaveTextContent toHaveValue toMatch toMatchObject toReturn toReturnTimes toReturnWith toStrictEqual toThrow toThrowError

Methods

lastCalledWith

  • lastCalledWith<E>(...args): void

  • Type Parameters

    • E extends any[]

    Parameters

    • Rest ...args: E

    Returns void

lastReturnedWith

  • lastReturnedWith<E>(value): void

  • Type Parameters

    • E

    Parameters

    • value: E

    Returns void

nthCalledWith

  • nthCalledWith<E>(nthCall, ...args): void

  • Type Parameters

    • E extends any[]

    Parameters

    • nthCall: number
    • Rest ...args: E

    Returns void

nthReturnedWith

  • nthReturnedWith<E>(nthCall, value): void

  • Type Parameters

    • E

    Parameters

    • nthCall: number
    • value: E

    Returns void

toBe

  • toBe<E>(expected): void

  • Type Parameters

    • E

    Parameters

    • expected: E

    Returns void

toBeCalled

  • toBeCalled(): void

  • Returns void

toBeCalledTimes

  • toBeCalledTimes(times): void

  • Parameters

    • times: number

    Returns void

toBeCalledWith

  • toBeCalledWith<E>(...args): void

  • Type Parameters

    • E extends any[]

    Parameters

    • Rest ...args: E

    Returns void

toBeChecked

  • toBeChecked(): void

  • Returns void

    Description

    Assert whether the given element is checked.

    It accepts an input of type checkbox or radio and elements with a role of radio with a valid aria-checked attribute of "true" or "false".

    Example

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

    const inputCheckbox = getByTestId('input-checkbox')
    const inputRadio = getByTestId('input-radio')
    expect(inputCheckbox).toBeChecked()
    expect(inputRadio).not.toBeChecked()

    See

    testing-library/jest-dom#tobechecked

toBeCloseTo

  • toBeCloseTo(number, numDigits?): void

  • Parameters

    • number: number
    • Optional numDigits: number

    Returns void

toBeDefined

  • toBeDefined(): void

  • Returns void

toBeDisabled

  • toBeDisabled(): void

  • Returns void

    Description

    Allows 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.

    Example

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

    expect(getByTestId('button')).toBeDisabled()

    See

    testing-library/jest-dom#tobedisabled

toBeEmpty

  • toBeEmpty(): void

  • Returns void

    Deprecated

    since v5.9.0

    Description

    Assert whether an element has content or not.

    Example

    <span data-testid="not-empty">
      <span data-testid="empty"></span>
    </span>

    expect(getByTestId('empty')).toBeEmpty()
    expect(getByTestId('not-empty')).not.toBeEmpty()

    See

    testing-library/jest-dom#tobeempty

toBeEmptyDOMElement

  • toBeEmptyDOMElement(): void

  • Returns void

    Description

    Assert whether an element has content or not.

    Example

    <span data-testid="not-empty">
      <span data-testid="empty"></span>
    </span>

    expect(getByTestId('empty')).toBeEmptyDOMElement()
    expect(getByTestId('not-empty')).not.toBeEmptyDOMElement()

    See

    testing-library/jest-dom#tobeemptydomelement

toBeEnabled

  • toBeEnabled(): void

  • Returns void

    Description

    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.

    Example

    <button
      data-testid="button"
      type="submit"
    >
      submit
    </button>

    expect(getByTestId('button')).toBeEnabled()

    See

    testing-library/jest-dom#tobeenabled

toBeFalsy

  • toBeFalsy(): void

  • Returns void

toBeGreaterThan

  • toBeGreaterThan(num): void

  • Parameters

    • num: number | bigint

    Returns void

toBeGreaterThanOrEqual

  • toBeGreaterThanOrEqual(num): void

  • Parameters

    • num: number | bigint

    Returns void

toBeInTheDOM

  • toBeInTheDOM(container?): void

  • Parameters

    Returns void

    Deprecated

    since v1.9.0

    Description

    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.

    See

    testing-library/jest-dom#toBeInTheDom

toBeInTheDocument

  • toBeInTheDocument(): void

  • Returns void

    Description

    Assert whether an element is present in the document or not.

    Example

    <svg data-testid="svg-element"></svg>

    expect(queryByTestId('svg-element')).toBeInTheDocument()
    expect(queryByTestId('does-not-exist')).not.toBeInTheDocument()

    See

    testing-library/jest-dom#tobeinthedocument

toBeInstanceOf

  • toBeInstanceOf<E>(expected): void

  • Type Parameters

    • E

    Parameters

    • expected: E

    Returns void

toBeInvalid

  • toBeInvalid(): void

  • Returns void

    Description

    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.

    Example

    <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()

    See

    testing-library/jest-dom#tobeinvalid

toBeLessThan

  • toBeLessThan(num): void

  • Parameters

    • num: number | bigint

    Returns void

toBeLessThanOrEqual

  • toBeLessThanOrEqual(num): void

  • Parameters

    • num: number | bigint

    Returns void

toBeNaN

  • toBeNaN(): void

  • Returns void

toBeNull

  • toBeNull(): void

  • Returns void

toBePartiallyChecked

  • toBePartiallyChecked(): void

  • Returns void

    Description

    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

    Example

    <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()

    See

    testing-library/jest-dom#tobepartiallychecked

toBeRequired

  • toBeRequired(): void

  • Returns void

    Description

    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

    <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()

    See

    testing-library/jest-dom#toberequired

toBeTruthy

  • toBeTruthy(): void

  • Returns void

toBeUndefined

  • toBeUndefined(): void

  • Returns void

toBeValid

  • toBeValid(): void

  • Returns void

    Description

    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.

    Example

    <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()

    See

    testing-library/jest-dom#tobevalid

toBeVisible

  • toBeVisible(): void

  • Returns void

    Description

    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 <details /> it has the open attribute

    Example

    <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()

    See

    testing-library/jest-dom#tobevisible

toContain

  • toContain<E>(item): void

  • Type Parameters

    • E

    Parameters

    • item: E

    Returns void

toContainElement

  • toContainElement(element): void

  • Parameters

    Returns void

    Description

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

    Example

    <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)

    See

    testing-library/jest-dom#tocontainelement

toContainEqual

  • toContainEqual<E>(item): void

  • Type Parameters

    • E

    Parameters

    • item: E

    Returns void

toContainHTML

  • toContainHTML(htmlText): void

  • Parameters

    • htmlText: string

    Returns void

    Description

    Assert whether a string representing a HTML element is contained in another element.

    Example

    <span data-testid="parent"><span data-testid="child"></span></span>

    expect(getByTestId('parent')).toContainHTML('<span data-testid="child"></span>')

    See

    testing-library/jest-dom#tocontainhtml

toEqual

  • toEqual<E>(expected): void

  • Type Parameters

    • E

    Parameters

    • expected: E

    Returns void

toHaveAccessibleDescription

  • toHaveAccessibleDescription(text?): void

  • Parameters

    • Optional text: any

    Returns void

    Description

    This 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.

    Example

    <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')

    See

    testing-library/jest-dom#tohaveaccessibledescription

toHaveAccessibleErrorMessage

  • toHaveAccessibleErrorMessage(text?): void

  • Parameters

    • Optional text: any

    Returns void

    Description

    This 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.

    Example

    <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()

    See

    testing-library/jest-dom#tohaveaccessibleerrormessage

toHaveAccessibleName

  • toHaveAccessibleName(text?): void

  • Parameters

    • Optional text: any

    Returns void

    Description

    This 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.

    Example

    <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()

    See

    testing-library/jest-dom#tohaveaccessiblename

toHaveAttribute

  • toHaveAttribute(attr, value?): void

  • Parameters

    • attr: string
    • Optional value: unknown

    Returns void

    Description

    Allows 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.

    Example

    <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')

    See

    testing-library/jest-dom#tohaveattribute

toHaveBeenCalled

  • toHaveBeenCalled(): void

  • Returns void

toHaveBeenCalledTimes

  • toHaveBeenCalledTimes(times): void

  • Parameters

    • times: number

    Returns void

toHaveBeenCalledWith

  • toHaveBeenCalledWith<E>(...args): void

  • Type Parameters

    • E extends any[]

    Parameters

    • Rest ...args: E

    Returns void

toHaveBeenLastCalledWith

  • toHaveBeenLastCalledWith<E>(...args): void

  • Type Parameters

    • E extends any[]

    Parameters

    • Rest ...args: E

    Returns void

toHaveBeenNthCalledWith

  • toHaveBeenNthCalledWith<E>(n, ...args): void

  • Type Parameters

    • E extends any[]

    Parameters

    • n: number
    • Rest ...args: E

    Returns void

toHaveClass

  • toHaveClass(...classNames): void

  • Parameters

    • Rest ...classNames: (string | RegExp)[]

    Returns void

    Description

    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

    <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()

    See

    testing-library/jest-dom#tohaveclass

  • toHaveClass(classNames, options?): void

  • Parameters

    • classNames: string
    • Optional options: {
          exact: boolean;
      }
      • exact: boolean

    Returns void

toHaveDescription

  • toHaveDescription(text?): void

  • Parameters

    • Optional text: any

    Returns void

    Deprecated

    since v5.14.1

    Description

    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").

    Example

    <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

    See

    testing-library/jest-dom#tohavedescription

toHaveDisplayValue

  • toHaveDisplayValue(value): void

  • Parameters

    Returns void

    Description

    This allows you to check whether the given form element has the specified displayed value (the one the end user will see). It accepts ,