dom

Helpers for working with the DOM, useful for tests.

Read the docs

install

npm i -D @bicycle-codes/dom

use

import

import { dom } from '@bicycle-codes/dom'

// or import individual functions
import { waitFor } from '@bicycle-codes/dom'

require

const dom = require('@bicycle-codes/dom').dom

API

convenient shortcuts

dom.qs points to document.querySelector

dom.qsa is equal to document.querySelectorAll

dom.byId is equal to document.getElementById

waitFor

Look for a DOM element by slector. Default timeout is 5 seconds. Throws if the element is not found.

function waitFor (selector?:string|null, args?:{
    visible?:boolean,
    timeout?:number
}|null, lambda?):Promise<Element|null>

waitFor example

import { waitFor } from '@bicycle-codes/dom'

// or pass in a query selector string
const el = await waitFor('#my-element')

// example of using a lambda function only
const el2 = dom.waitFor(null, null, () => {
    return document.querySelector('p')
})

waitForText

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>

waitForText example

import { waitForText } from '@bicycle-codes/dom'

// by default will search the document.body
const el = await waitForText({
    regex: /bar/
})

Pass in a string selector

Can pass in a string to search for. Will search the document.body by default.

import { waitForText } from '@bicycle-codes/dom'

const el = await dom.waitForText('bar')

Pass in a parent element and timeout.

const found = await waitForText({
    element: dom.qs('#test-two'),
    multipleTags: true,
    text: 'bbb',
    timeout: 10000  // 10 seconds
})

click

Dispatch a click event from the given element.

async function click (selector:Element|string):Promise<void>

click example

import { dom } from '@bicycle-codes/dom'
// or import { click } from '@bicycle-codes/dom'

dom.click(dom.qs('#my-element'))

// or pass a selector
dom.click('#my-element')

event

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

event example

import { dom } from '@bicycle-codes/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')
)

sleep

Wait for the given milliseconds.

async function sleep (ms:number):Promise<void>

sleep example

import { sleep } from '@bicycle-codes/dom'

await sleep(3000)  // wait 3 seconds

type

Enter text into an input. This will simulate typing by dispatching input events.

async function type (
    selector:string|HTMLElement|Element,
    value:string,
):Promise<void>

type example

import { type } from '@bicycle-codes/dom'

// this will dispatch 5 `input` events,
// one for each character
await type('#test', 'hello')

credits

Thanks @raynos for writing this originally.