viddy 🍊
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