API.md

Table of Contents

• assert.dom()
• DOMAssertions
  • exists
    • Parameters
    • Examples
  • doesNotExist
    • Parameters
    • Examples
  • isChecked
    • Parameters
    • Examples
  • isNotChecked
    • Parameters
    • Examples
  • isFocused
    • Parameters
    • Examples
  • isNotFocused
    • Parameters
    • Examples
  • isRequired
    • Parameters
    • Examples
  • isNotRequired
    • Parameters
    • Examples
  • isValid
    • Parameters
    • Examples
  • isNotValid
    • Parameters
    • Examples
  • isVisible
    • Parameters
    • Examples
  • isNotVisible
    • Parameters
    • Examples
  • hasAttribute
    • Parameters
    • Examples
  • doesNotHaveAttribute
    • Parameters
    • Examples
  • hasAria
    • Parameters
    • Examples
  • doesNotHaveAria
    • Parameters
    • Examples
  • hasProperty
    • Parameters
    • Examples
  • isDisabled
    • Parameters
    • Examples
  • isNotDisabled
    • Parameters
    • Examples
  • hasClass
    • Parameters
    • Examples
  • doesNotHaveClass
    • Parameters
    • Examples
  • hasStyle
    • Parameters
    • Examples
  • hasPseudoElementStyle
    • Parameters
    • Examples
  • doesNotHaveStyle
    • Parameters
    • Examples
  • doesNotHavePseudoElementStyle
    • Parameters
    • Examples
  • hasText
    • Parameters
    • Examples
  • hasAnyText
    • Parameters
    • Examples
  • hasNoText
    • Parameters
    • Examples
  • includesText
    • Parameters
    • Examples
  • doesNotIncludeText
    • Parameters
    • Examples
  • hasValue
    • Parameters
    • Examples
  • hasAnyValue
    • Parameters
    • Examples
  • hasNoValue
    • Parameters
    • Examples
  • matchesSelector
    • Parameters
    • Examples
  • doesNotMatchSelector
    • Parameters
    • Examples
  • hasTagName
    • Parameters
    • Examples
  • doesNotHaveTagName
    • Parameters
    • Examples

assert.dom()

Once installed the DOM element assertions are available at assert.dom(...).*:

Parameters

• target (string | HTMLElement) A CSS selector that can be used to find elements using querySelector(), or an [HTMLElement][] (Not all assertions support both target types.) (optional, default rootElement or document)
• rootElement (HTMLElement | Document | ShadowRoot | null)? The root element of the DOM in which to search for the target (optional, defaults document when null or not provided)

Examples

test('the title exists', function(assert) {
  assert.dom('#title').exists();
});

DOMAssertions

exists

• See: #doesNotExist

Assert an HTMLElement (or multiple) matching the selector exists.

Parameters

• options object?

  • options.count number?

• message string?

Examples

assert.dom('#title').exists();
assert.dom('.choice').exists({ count: 4 });

doesNotExist

• See: #exists

Assert an HTMLElement matching the selector does not exists.

Parameters

• message string?

Examples

assert.dom('.should-not-exist').doesNotExist();

isChecked

• See: #isNotChecked

Assert that the HTMLElement or an HTMLElement matching the selector is currently checked.

Note: This also supports aria-checked="true/false".

Parameters

• message string?

Examples

assert.dom('input.active').isChecked();

isNotChecked

• See: #isChecked

Assert that the HTMLElement or an HTMLElement matching the selector is currently unchecked.

Note: This also supports aria-checked="true/false".

Parameters

• message string?

Examples

assert.dom('input.active').isNotChecked();

isFocused

• See: #isNotFocused

Assert that the HTMLElement or an HTMLElement matching the selector is currently focused.

Parameters

• message string?

Examples

assert.dom('input.email').isFocused();

isNotFocused

• See: #isFocused

Assert that the HTMLElement or an HTMLElement matching the selector is not currently focused.

Parameters

• message string?

Examples

assert.dom('input[type="password"]').isNotFocused();

isRequired

• See: #isNotRequired

Assert that the HTMLElement or an HTMLElement matching the selector is currently required.

Parameters

• message string?

Examples

assert.dom('input[type="text"]').isRequired();

isNotRequired

• See: #isRequired

Assert that the HTMLElement or an HTMLElement matching the selector is currently not required.

Parameters

• message string?

Examples

assert.dom('input[type="text"]').isNotRequired();

isValid

• See: #isValid

Assert that the HTMLElement passes validation

Validity is determined by asserting that:

• element.reportValidity() === true

Parameters

• message string?

Examples

assert.dom('.input').isValid();

isNotValid

• See: #isValid

Assert that the HTMLElement does not pass validation

Validity is determined by asserting that:

• element.reportValidity() === true

Parameters

• message string?

Examples

assert.dom('.input').isNotValid();

isVisible

• See: #isNotVisible

Assert that the HTMLElement or an HTMLElement matching the selector exists and is visible.

Visibility is determined by asserting that:

• the element's offsetWidth and offsetHeight are non-zero
• any of the element's DOMRect objects have a non-zero size

Additionally, visibility in this case means that the element is visible on the page, but not necessarily in the viewport.

Parameters

• options object?

  • options.count number?

• message string?

Examples

assert.dom('#title').isVisible();
assert.dom('.choice').isVisible({ count: 4 });

isNotVisible

• See: #isVisible

Assert that the HTMLElement or an HTMLElement matching the selector does not exist or is not visible on the page.

Visibility is determined by asserting that:

• the element's offsetWidth or offsetHeight are zero
• all of the element's DOMRect objects have a size of zero

Additionally, visibility in this case means that the element is visible on the page, but not necessarily in the viewport.

Parameters

• message string?

Examples

assert.dom('.foo').isNotVisible();

hasAttribute

• See: #doesNotHaveAttribute

Assert that the HTMLElement has an attribute with the provided name and optionally checks if the attribute value matches the provided text or regular expression.

Parameters

• name string
• value (string | RegExp | object?)
• message string?

Examples

assert.dom('input.password-input').hasAttribute('type', 'password');

doesNotHaveAttribute

• See: #hasAttribute

Assert that the HTMLElement has no attribute with the provided name.

Aliases: hasNoAttribute, lacksAttribute

Parameters

• name string
• message string?

Examples

assert.dom('input.username').doesNotHaveAttribute('disabled');

hasAria

• See: #doesNotHaveAria

Assert that the HTMLElement has an ARIA attribute with the provided name and optionally checks if the attribute value matches the provided text or regular expression.

Parameters

• name string
• value (string | RegExp | object?)
• message string?

Examples

assert.dom('button').hasAria('pressed', 'true');

doesNotHaveAria

• See: #hasAria

Assert that the HTMLElement has no ARIA attribute with the provided name.

Aliases: hasNoAria, lacksAria

Parameters

• name string
• message string?

Examples

assert.dom('button').doesNotHaveAria('pressed');

hasProperty

• See: #doesNotHaveProperty

Assert that the HTMLElement has a property with the provided name and checks if the property value matches the provided text or regular expression.

Parameters

• name string
• value (RegExp | any)
• message string?

Examples

assert.dom('input.password-input').hasProperty('type', 'password');

isDisabled

• See: #isNotDisabled

Assert that the HTMLElement or an HTMLElement matching the selector is disabled.

Parameters

• message string?

Examples

assert.dom('.foo').isDisabled();

isNotDisabled

• See: #isDisabled

Assert that the HTMLElement or an HTMLElement matching the selector is not disabled.

Aliases: isEnabled

Parameters

• message string?

Examples

assert.dom('.foo').isNotDisabled();

hasClass

• See: #doesNotHaveClass

Assert that the HTMLElement has the expected CSS class using classList.

expected can also be a regular expression, and the assertion will return true if any of the element's CSS classes match.

Parameters

• expected (string | RegExp)
• message string?

Examples

assert.dom('input[type="password"]').hasClass('secret-password-input');

assert.dom('input[type="password"]').hasClass(/.*password-input/);

doesNotHaveClass

• See: #hasClass

Assert that the HTMLElement does not have the expected CSS class using classList.

expected can also be a regular expression, and the assertion will return true if none of the element's CSS classes match.

Aliases: hasNoClass, lacksClass

Parameters

• expected (string | RegExp)
• message string?

Examples

assert.dom('input[type="password"]').doesNotHaveClass('username-input');

assert.dom('input[type="password"]').doesNotHaveClass(/username-.*-input/);

hasStyle

• See: #hasClass

Assert that the [HTMLElement][] has the expected style declarations using window.getComputedStyle.

Parameters

• expected object
• message string?

Examples

assert.dom('.progress-bar').hasStyle({
  opacity: 1,
  display: 'block'
});

hasPseudoElementStyle

• See: #hasClass

Assert that the pseudo element for selector of the [HTMLElement][] has the expected style declarations using window.getComputedStyle.

Parameters

• selector string
• expected object
• message string?

Examples

assert.dom('.progress-bar').hasPseudoElementStyle(':after', {
  content: '";"',
});

doesNotHaveStyle

• See: #hasClass

Assert that the [HTMLElement][] does not have the expected style declarations using window.getComputedStyle.

Parameters

• expected object
• message string?

Examples

assert.dom('.progress-bar').doesNotHaveStyle({
  opacity: 1,
  display: 'block'
});

doesNotHavePseudoElementStyle

• See: #hasClass

Assert that the pseudo element for selector of the [HTMLElement][] does not have the expected style declarations using window.getComputedStyle.

Parameters

• selector string
• expected object
• message string?

Examples

assert.dom('.progress-bar').doesNotHavePseudoElementStyle(':after', {
  content: '";"',
});

hasText

• See: #includesText

Assert that the text of the HTMLElement or an HTMLElement matching the selector matches the expected text, using the textContent attribute and stripping/collapsing whitespace.

expected can also be a regular expression.

Note: This assertion will collapse whitespace if the type you pass in is a string. If you are testing specifically for whitespace integrity, pass your expected text in as a RegEx pattern.

Aliases: matchesText

Parameters

• expected (string | RegExp)
• message string?

Examples

// <h2 id="title">
//   Welcome to <b>QUnit</b>
// </h2>

assert.dom('#title').hasText('Welcome to QUnit');

assert.dom('.foo').hasText(/[12]\d{3}/);

hasAnyText

• See: #hasText

Assert that the textContent property of an HTMLElement is not empty.

Parameters

• message string?

Examples

assert.dom('button.share').hasAnyText();

hasNoText

• See: #hasNoText

Assert that the textContent property of an HTMLElement is empty.

Parameters

• message string?

Examples

assert.dom('div').hasNoText();

includesText

• See: #hasText

Assert that the text of the HTMLElement or an HTMLElement matching the selector contains the given text, using the textContent attribute.

Note: This assertion will collapse whitespace in textContent before searching. If you would like to assert on a string that should contain line breaks, tabs, more than one space in a row, or starting/ending whitespace, use the #hasText selector and pass your expected text in as a RegEx pattern.

Aliases: containsText, hasTextContaining

Parameters

• text string
• message string?

Examples

assert.dom('#title').includesText('Welcome');

doesNotIncludeText

Assert that the text of the HTMLElement or an HTMLElement matching the selector does not include the given text, using the textContent attribute.

Aliases: doesNotContainText, doesNotHaveTextContaining

Parameters

• text string
• message string?

Examples

assert.dom('#title').doesNotIncludeText('Welcome');

hasValue

• See: #hasAnyValue
• See: #hasNoValue

Assert that the value property of an HTMLInputElement matches the expected text or regular expression.

If no expected value is provided, the assertion will fail if the value is an empty string.

Parameters

• expected (string | RegExp | object?)
• message string?

Examples

assert.dom('input.username').hasValue('HSimpson');

hasAnyValue

• See: #hasValue
• See: #hasNoValue

Assert that the value property of an HTMLInputElement is not empty.

Parameters

• message string?

Examples

assert.dom('input.username').hasAnyValue();

hasNoValue

• See: #hasValue
• See: #hasAnyValue

Assert that the value property of an HTMLInputElement is empty.

Aliases: lacksValue

Parameters

• message string?

Examples

assert.dom('input.username').hasNoValue();

matchesSelector

Assert that the target selector selects only Elements that are also selected by compareSelector.

Parameters

• compareSelector string
• message string?

Examples

assert.dom('p.red').matchesSelector('div.wrapper p:last-child')

doesNotMatchSelector

Assert that the target selector selects only Elements that are not also selected by compareSelector.

Parameters

• compareSelector string
• message string?

Examples

assert.dom('input').doesNotMatchSelector('input[disabled]')

hasTagName

Assert that the tagName of the HTMLElement or an HTMLElement matching the selector matches the expected tagName, using the tagName property of the HTMLElement.

Parameters

• tagName
• message string?
• expected string

Examples

// <h1 id="title">
//   Title
// </h1>

assert.dom('#title').hasTagName('h1');

doesNotHaveTagName

Assert that the tagName of the HTMLElement or an HTMLElement matching the selector does not match the expected tagName, using the tagName property of the HTMLElement.

Parameters

• tagName
• message string?
• expected string

Examples

// <section id="block">
//   Title
// </section>

assert.dom('section#block').doesNotHaveTagName('div');