Helpers for working with the DOM; useful for tests.
npm i -D @substrate-system/domimport { dom } from '@substrate-system/dom'
// or import individual functions
import { waitFor } from '@substrate-system/dom'const dom = require('@substrate-system/dom').domdom.qs points to document.querySelector
dom.qsa is equal to document.querySelectorAll
dom.byId is equal to document.getElementById
Look for a DOM element by slector. Default timeout is 5 seconds. Throws if the element is not found.
function waitFor<K extends keyof HTMLElementTagNameMap> (
selector:K,
args?:{ visible?:boolean; timeout?:number }|null,
lambda?:() => Element|null
):Promise<HTMLElementTagNameMap[K]|null>
function waitFor<E extends Element = HTMLElement> (
selector?:string|null,
args?:{ visible?:boolean; timeout?:number }|null,
lambda?:() => Element|null
):Promise<E|null>A tag name selector resolves to that tag's element type, including custom
elements declared in HTMLElementTagNameMap. Any other selector resolves to
HTMLElement by default, or to the type you pass in.
import { waitFor } from '@substrate-system/dom'
// or pass in a query selector string
const el = await waitFor('#my-element')
// a tag name gets the matching element type (HTMLInputElement here)
const input = await waitFor('input')
// pass the element type for any other selector
const field = await waitFor<HTMLInputElement>('#my-input')
// example of using a lambda function only
const el2 = dom.waitFor(null, null, () => {
return document.querySelector('p')
})Look for an element containing the given text, or that matches a given regex. Return the element if found. Default timeout is 5 seconds. Throws if the element is not found.
Takes either an option object or a string of text.
function waitForText (args:Partial<{
text:string,
timeout:number,
multipleTags:boolean,
regex:RegExp
}>|string, parentElement:Element = document.body):Promise<Element|null>import { waitForText } from '@substrate-system/dom'
// by default will search the document.body
const el = await waitForText({
regex: /bar/
})Can pass in a string to search for. Will search the document.body by default.
import { waitForText } from '@substrate-system/dom'
const el = await dom.waitForText('bar')const found = await waitForText({
element: dom.qs('#test-two'),
multipleTags: true,
text: 'bbb',
timeout: 10000 // 10 seconds
})Dispatch a click event from the given element.
async function click (selector:Element|string):Promise<void>import { dom } from '@substrate-system/dom'
// or import { click } from '@substrate-system/dom'
dom.click(dom.qs('#my-element'))
// or pass a selector
dom.click('#my-element')Dispatch an event from an element. Will dispatch from window if no element is passed in.
function event (
event:CustomEvent|Event|string,
element?:Element|Window|null
):voidimport { dom } from '@substrate-system/dom'
// pass in an event name. Will create a custom event.
dom.event('hello', dom.qs('#test'))
// create an event, then dispatch it
dom.event(
new CustomEvent('test-event', {
bubbles: true,
detail: 'test'
}),
dom.qs('#test-two')
)Wait for the given milliseconds.
async function sleep (ms:number):Promise<void>import { sleep } from '@substrate-system/dom'
await sleep(3000) // wait 3 secondsEnter text into an input. This will simulate typing by dispatching input events.
async function type (
selector:string|HTMLElement|Element,
value:string,
):Promise<void>import { type } from '@substrate-system/dom'
// this will dispatch 5 `input` events,
// one for each character
await type('#test', 'hello')Thanks @raynos for writing this originally.