New Research: Supply Chain Attack on Axios Pulls Malicious Dependency from npm.Details → →

Book a Demo Sign in

viddy

Package Overview

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

viddy

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

latest

Source

npm

Version: 3.0.2

Version published: 11 months ago

Weekly downloads: 7

Maintainers: 1

Weekly downloads

Created: 4 years ago

Source

`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 are handy integrations for Puppeteer and PlayWright.

<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

Keywords

FAQs

What is viddy?

Is viddy popular?

Is viddy well maintained?

Package last updated on 24 May 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install