Viddy NPM | npm.io

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 selectors

More 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>