Lupa API Reference / assert/dom / AssertDom
Class: AssertDom
Defined in: src/assert/dom.ts:8
DOM-specific assertion methods
Constructors
Constructor
new AssertDom(
assertInstance):AssertDom
Defined in: src/assert/dom.ts:11
Parameters
assertInstance
Returns
AssertDom
Methods
equal()
equal(
element,expectedHtml,options?,message?):void
Defined in: src/assert/dom.ts:243
Asserts that an element's outer DOM matches the expected HTML string semantically.
See SemanticDomOptions for options on how to control the comparison.
Parameters
element
Element
The element whose DOM should be compared
expectedHtml
string | Element
The expected HTML string or Element
options?
Optional options to control the comparison
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const btn = document.querySelector('button')
assert.dom.equal(btn, '<button class="primary" disabled>Submit</button>')Use When
You need to assert the entire HTML structure (including the wrapper element itself), ensuring order and attributes match without worrying about whitespace formatting.
hasAttribute()
hasAttribute(
element,name,value?,message?):void
Defined in: src/assert/dom.ts:86
Asserts that an element has a specific attribute. If the value argument is provided, it will also assert that the attribute equals that value.
Parameters
element
Element
The DOM element to check
name
string
The attribute name
value?
string
Optional expected value of the attribute
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const input = document.querySelector('input')
assert.dom.hasAttribute(input, 'required')
assert.dom.hasAttribute(input, 'type', 'email')Use When
Validating ARIA roles, input types, custom data attributes, or disabled states.
hasClass()
hasClass(
element,className,message?):void
Defined in: src/assert/dom.ts:58
Asserts that an element has the specified class name.
Parameters
element
Element
The DOM element to check
className
string
The expected class name
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const alert = document.querySelector('.alert')
assert.dom.hasClass(alert, 'alert-danger')Use When
Verifying state changes applied via CSS classes (e.g., active, disabled, error states).
hasStyle()
hasStyle(
element,property,value,message?):void
Defined in: src/assert/dom.ts:209
Asserts that an element has the specified computed style property and value.
Parameters
element
Element
The DOM element to check
property
string
The CSS property name (e.g. 'color', 'background-color')
value
string
The expected computed style value
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const box = document.querySelector('.box')
assert.dom.hasStyle(box, 'display', 'flex')Use When
Verifying that CSS rules have been successfully applied and computed by the browser, rather than just checking raw class names.
hasTagName()
hasTagName(
element,tag,message?):void
Defined in: src/assert/dom.ts:181
Asserts that an element has the specified tag name (case-insensitive).
Parameters
element
Element
The DOM element to check
tag
string
The expected tag name (e.g. 'div', 'button')
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const link = document.querySelector('.custom-link')
assert.dom.hasTagName(link, 'a')Use When
Verifying the semantic HTML structure (e.g., ensuring a component renders an <h1> rather than a <div>).
hasText()
hasText(
element,text,message?):void
Defined in: src/assert/dom.ts:33
Asserts that an element contains the specified text content. Traverses all child nodes to extract text content, trims whitespace, and checks for substring inclusion.
Parameters
element
Element
The DOM element to check
text
string
The text string expected to be contained
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const btn = document.querySelector('button')
assert.dom.hasText(btn, 'Submit')Use When
Validating that expected text appears anywhere inside an element's DOM tree, regardless of inner nested tags.
isFocused()
isFocused(
element,message?):void
Defined in: src/assert/dom.ts:154
Asserts that an element is currently focused (i.e. document.activeElement).
Parameters
element
Element
The DOM element to check
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const input = document.querySelector('#username')
input.focus()
assert.dom.isFocused(input)Use When
Testing keyboard navigation, accessibility features, and autofocus behaviors.
isVisible()
isVisible(
element,message?):void
Defined in: src/assert/dom.ts:129
Asserts that an element is visible in the DOM. Visibility is determined by offsetParent (for layout visibility) or having getBoundingClientRect dimensions. Note: This does not account for opacity: 0 or visibility: hidden.
Parameters
element
HTMLElement
The DOM element to check
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const modal = document.querySelector('.modal')
assert.dom.isVisible(modal)Use When
You need to verify that an element is actually rendered and taking up space in the layout hierarchy (e.g., checking if a dropdown opened).
lightEqual()
lightEqual(
element,expectedHtml,options?,message?):void
Defined in: src/assert/dom.ts:304
Asserts that an element's Light DOM (innerHTML) matches the expected HTML string semantically.
Parameters
element
Element
The element whose DOM should be compared
expectedHtml
string | Element
The expected HTML string or Element
options?
Optional options to control the comparison
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const list = document.querySelector('ul')
assert.dom.lightEqual(list, '<li>Item 1</li><li>Item 2</li>')Use When
You only care about the children/contents of an element and want to ignore its wrapper tag.
notEqual()
notEqual(
element,expectedHtml,options?,message?):void
Defined in: src/assert/dom.ts:271
Asserts that an element's outer DOM does NOT match the expected HTML string semantically.
Parameters
element
Element
The element whose DOM should be compared
expectedHtml
string | Element
The expected HTML string or Element
options?
Optional options to control the comparison
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const btn = document.querySelector('button')
assert.dom.notEqual(btn, '<button disabled>Submit</button>')Use When
You want to ensure an element has mutated or changed from a baseline state.
notLightEqual()
notLightEqual(
element,expectedHtml,options?,message?):void
Defined in: src/assert/dom.ts:336
Asserts that an element's Light DOM (innerHTML) does NOT match the expected HTML string semantically.
Parameters
element
Element
The element whose DOM should be compared
expectedHtml
string | Element
The expected HTML string or Element
options?
Optional options to control the comparison
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const list = document.querySelector('ul')
assert.dom.notLightEqual(list, '<li>Loading...</li>')Use When
You are verifying that a component has finished loading and replaced its placeholder children.
notShadowEqual()
notShadowEqual(
element,expectedHtml,options?,message?):void
Defined in: src/assert/dom.ts:401
Asserts that an element's Shadow DOM does NOT match the expected HTML string semantically.
Parameters
element
Element
The element whose DOM should be compared
expectedHtml
string | Element
The expected HTML string or Element
options?
Optional options to control the comparison
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const customEl = document.querySelector('my-element')
assert.dom.notShadowEqual(customEl, '<slot name="fallback"></slot>')Use When
Verifying that a Web Component has updated its internal shadow root after a state change.
shadowEqual()
shadowEqual(
element,expectedHtml,options?,message?):void
Defined in: src/assert/dom.ts:369
Asserts that an element's Shadow DOM matches the expected HTML string semantically.
Parameters
element
Element
The element whose DOM should be compared
expectedHtml
string | Element
The expected HTML string or Element
options?
Optional options to control the comparison
message?
string
Optional message to display when the assertion fails
Returns
void
Example
const customEl = document.querySelector('my-element')
assert.dom.shadowEqual(customEl, '<style>...</style><div class="wrapper">...</div>')Use When
You are testing Web Components and need to verify their encapsulated internal template.