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? The root element of the DOM in which to search for the target (optional, default document)

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').hasNoAttribute('disabled');

hasAria

• **See: #hasNoAria **

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.

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