API methods - shuckster/viddy GitHub Wiki
import { viddy, viddyWell } from 'viddy'-
viddymethods return a single result, orundefined. -
viddyWellreturns 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:
| 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
| 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'))
})
| 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')
| 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"