https://github.com/substrate-system/dom
Helpers for working with the DOM in tests
https://github.com/substrate-system/dom
dom test
Last synced: 8 months ago
JSON representation
Helpers for working with the DOM in tests
- Host: GitHub
- URL: https://github.com/substrate-system/dom
- Owner: substrate-system
- License: other
- Created: 2023-12-20T22:04:00.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-26T05:26:14.000Z (about 1 year ago)
- Last Synced: 2025-03-30T11:34:37.688Z (about 1 year ago)
- Topics: dom, test
- Language: TypeScript
- Homepage: https://substrate-system.github.io/dom/
- Size: 142 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# dom
[](README.md)
[](README.md)
[](package.json)
[](https://semver.org/)
[](https://packagephobia.com/result?p=@substrate-system/dom)
[](https://common-changelog.org)
[](LICENSE)
Helpers for working with the DOM; useful for tests.
[Read the docs](https://substrate-system.github.io/dom/)
## install
```sh
npm i -D @substrate-system/dom
```
## use
### import
```js
import { dom } from '@substrate-system/dom'
// or import individual functions
import { waitFor } from '@substrate-system/dom'
```
### require
```js
const dom = require('@substrate-system/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.
```ts
function waitFor (selector?:string|null, args?:{
visible?:boolean,
timeout?:number
}|null, lambda?):Promise
```
#### `waitFor` example
```js
import { waitFor } from '@substrate-system/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.
```ts
function waitForText (args:Partial<{
text:string,
timeout:number,
multipleTags:boolean,
regex:RegExp
}>|string, parentElement:Element = document.body):Promise
```
#### `waitForText` example
```js
import { waitForText } from '@substrate-system/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.
```js
import { waitForText } from '@substrate-system/dom'
const el = await dom.waitForText('bar')
```
##### Pass in a parent element and timeout.
```js
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.
```ts
async function click (selector:Element|string):Promise
```
#### `click` example
```js
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')
```
### `event`
Dispatch an event from an element. Will dispatch from `window` if no element is passed in.
```ts
function event (
event:CustomEvent|Event|string,
element?:Element|Window|null
):void
```
#### `event` example
```js
import { 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')
)
```
### `sleep`
Wait for the given milliseconds.
```ts
async function sleep (ms:number):Promise
```
#### `sleep` example
```js
import { sleep } from '@substrate-system/dom'
await sleep(3000) // wait 3 seconds
```
### `type`
Enter text into an input. This will simulate typing by dispatching `input` events.
```ts
async function type (
selector:string|HTMLElement|Element,
value:string,
):Promise
```
#### `type` example
```js
import { type } from '@substrate-system/dom'
// this will dispatch 5 `input` events,
// one for each character
await type('#test', 'hello')
```
## credits
Thanks [@raynos](https://github.com/raynos/) for writing this originally.