Skip to content

Find DOM elements using an expressive query syntax, extract text and monitor changes.

License

Notifications You must be signed in to change notification settings

shuckster/viddy

Repository files navigation

viddy 🍊

MIT license npm bundle size Version

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>

Credits

viddy was written by Conan Theobald.

I hope you found it useful! If so, I like coffee ☕️ :)

License

MIT licensed: See LICENSE

About

Find DOM elements using an expressive query syntax, extract text and monitor changes.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published