viddy
v2.2.3
Published
Find DOM elements using an expressive query syntax, extract text and monitor changes.
Downloads
1,725
Maintainers
shucksterReadme
Find DOM selectors using an expressive query syntax, extract text and monitor changes. Viddy was written to help write E2E UI tests that reflect user-behaviour, and there's a handy integration for Puppeteer.
<body>
<h1>A Strange Fella</h1>
<p>"Munchy-wunching lomticks of toast"</p>
</body>
viddy.for('lomticks of toast', { near: 'a strange fella' })
// => 'body p'Search by text, regular-expression, relative visual position, containment, and target parent nodes.
viddy.forCta(/click here/i, { leftOf: 'heading' })
viddy.forInput('last name:', { below: 'first name' })You can match/extract text, too:
viddy.hasContent('lorum ipsum') // => false
viddy.matchText(/\d+\.\d+/, { rightOf: 'total' }) // => '1.99'There's a helper that will resolve a Promise when DOM-updates have idled for a moment:
viddy.waitForDomToIdle({ withinMs: 500 })Since v2.2.0 the when* APIs enable declarative branching logic:
viddy.when('Munchy-wunching')
.exists(sel => `found: ${sel}`)
.absent(() => 'sorry, not found')
.valueOf()
// => 'found: body p'Overview
viddy API methods accept objects in the following format:
Query {
pattern: String|RegExp
selector: CSSSelectorString
pickParent: CSSSelectorString
near: Query
above: Query
below: Query
leftOf: Query
rightOf: Query
containedBy: Query
}Most methods have a shorthand for { pattern: String|RegExp }, which is to specify the String|RegExp as the first argument. You can then extend this using a Query object for the second argument:
// The following queries are identical:
let sel = viddy.for('lomticks of toast', { near: 'a man' })
let sel = viddy.for({ pattern: 'lomticks of toast', near: 'a man' })Target a parent element like so:
let sel = viddy.for({
pattern: /open/,
near: 'your account',
pickParent: 'button'
})
// The above will return the selector for the button:
// div > button > span > "Open"
// ^^^^^^
// ...instead of the span.The positional and containment options (near, above, below, rightOf, leftOf, containedBy) can be combined and/or compounded:
let sels = viddyWell.for({
pattern: /open/,
near: {
pattern: 'your account',
rightOf: 'blog title',
near: 'settings'
}
})
// viddyWell returns an array of all matching selectorsMore detail in the query specification and index.d.ts file.
Install / Use
$ pnpm i viddy// ESM:
import { viddy, viddyWell } from 'viddy'
// CJS:
const { viddy, viddyWell } = require('viddy')<!-- Browser/UMD: -->
<script src="https://unpkg.com/viddy/dist/browser/viddy.browser.js"></script>
<script>
const { viddy, viddyWell } = libViddy
</script>Credits
viddy was written by Conan Theobald.
I hope you found it useful! If so, I like coffee ☕️ :)
License
MIT licensed: See LICENSE