Skip to content

API methods

Jump to bottom
Conan edited this page Mar 18, 2023 · 10 revisions

viddy 🍊 docs

import { viddy, viddyWell } from 'viddy'

API methods

  • viddy methods return a single result, or undefined.
  • viddyWell returns an array of results in order of likeliness.

In the following tables, asterisk * refers to one of these namespaces.

Nearly all API methods share the same function signature:

 

🔍 Methods returning CSS selectors as string (viddy) or string[] (viddyWell)

method returns
*.for(Query) a unique CSS selector as a string
*.forCta(Query) as *.for, but prefers button and a (anchor) elements
*.forInput(Query) as *.for, but prefers input (non-buttons), select, and textarea elements 
<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'
// The following queries are equivalent:
let sel = viddy.for('lomticks of toast', { near: 'fella' })
let sel = viddy.for({ pattern: 'lomticks of toast', near: 'fella' })
// Return an ancestor using `pickParent`:
viddy.for('text', { pickParent: 'button' })
// body > button > span with "text"
//        \__returns the button

 

🌳 Methods for branching logic

method returns
*.when(Query) an object with exists, absent and valueOf. See examples below
*.whenCta(Query) as *.when, but prefers button and a (anchor) elements
*.whenInput(Query) as *.when, but prefers input (non-buttons), select, and textarea elements 
let result = viddy
  .when('a strange fella')
  .exists((sel) => `found: ${sel}`)
  .absent(() => 'sorry, not found')
  .valueOf()

For the Puppeteer integration:

let result = (await viddy.when('a strange fella'))
  .exists((sel) => `found: ${sel}`)
  .absent(() => 'sorry, not found')
  .valueOf()

// Or...
await viddy.when('a strange fella').then(({ exists, absent }) => {
  exists((sel) => console.log(`found: ${sel}`))
  absent(() => console.log('sorry, not found'))
})

 

🤞 Methods returning CSS selectors as Promise<string> (viddy) or Promise<string[]> (viddyWell)

method returns
*.waitFor(Query) Promise that returns a CSS selector, waiting first for the element to appear in the DOM if necessary, within a timeout set with option { timeoutInMs } that defaults to 5 seconds
*.waitForCta(Query) as *.waitFor, but prefers button and anchor elements
*.waitForValue(value,Query) Waits for a form input (non-buttons), select, or textarea with the specified value, resolves a Promise with its CSS selector if found
*.waitForDomToIdle(Query) Waits for the DOM to stop updating within 500ms, timing out after 5 seconds. Change these with { withinMs: 500, timeoutInMs: 5000 } options. Unlike the other waitFor* methods, this one returns void 
let result = await viddy
  .waitFor('a strange fella')
  .then((sel) => `found: ${sel}`)
  .catch(() => 'sorry, not found')

 

📄 Methods for querying and returning DOM content as string, boolean

method returns
*.valueOf(Query) uses *.forInput to find an input and return its value
*.innerText(Query) Extract the full innerText of an element
*.matchText(needle,Query) Searches innerText of query for needle. If needle is a string, all innerText is returned. If needle is a RegExp, the portion of text matching it will be returned. If capture-groups are specified in the RegExp, the full match-array will be returned
*.hasContent(Query) true/false (for both viddy/viddyWell)

 

(Read about the Query spec.)

Note that the viddy.waitForValue() and viddy.matchText() signatures differ in that a string/RegExp is expected as the first argument, eg:

const result = viddy.matchText(/uk/i, { near: 'Country:' })
// "UK"

const css = await viddy.waitForValue('uk', 'Country:')
// "select#country"

viddy 🍊 | on npm | docs home | top of page

Clone this wiki locally