2.2.3 • Published 2 years ago

viddy v2.2.3

Weekly downloads
-
License
MIT
Repository
github
Last release
2 years ago

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

2.2.3

2 years ago

2.2.1

2 years ago

2.2.0

2 years ago

2.2.2

2 years ago

2.1.1

2 years ago

2.1.0

2 years ago

2.0.3

3 years ago

2.0.2

3 years ago

2.0.1

3 years ago

2.0.0

3 years ago

1.5.0

3 years ago

1.4.1

3 years ago

1.4.0

3 years ago

1.3.4

3 years ago

1.3.3

3 years ago

1.3.2

3 years ago

1.3.1

3 years ago

1.3.0

3 years ago

1.2.2

3 years ago

1.2.1

3 years ago

1.2.0

3 years ago

1.1.2

3 years ago

1.1.1

3 years ago

1.1.0

3 years ago

1.0.2

3 years ago

1.0.1

3 years ago

1.0.0

3 years ago

0.0.44

7 years ago

0.0.43

7 years ago

0.0.42

7 years ago

0.0.41

7 years ago

0.0.40

7 years ago

0.0.39

7 years ago

0.0.38

7 years ago

0.0.36

7 years ago

0.0.35

7 years ago

0.0.34

7 years ago

0.0.33

7 years ago

0.0.32

7 years ago

0.0.31

7 years ago

0.0.30

7 years ago

0.0.29

7 years ago

0.0.28

7 years ago

0.0.27

7 years ago

0.0.26

7 years ago

0.0.25

7 years ago

0.0.24

7 years ago

0.0.23

7 years ago

0.0.22

7 years ago

0.0.21

7 years ago

0.0.20

7 years ago

0.0.19

7 years ago

0.0.18

7 years ago

0.0.17

7 years ago

0.0.16

7 years ago

0.0.15

7 years ago

0.0.14

7 years ago

0.0.13

7 years ago

0.0.12

7 years ago

0.0.11

7 years ago

0.0.10

7 years ago

0.0.8

7 years ago

0.0.7

7 years ago

0.0.6

7 years ago

0.0.5

7 years ago

0.0.4

7 years ago

0.0.3

7 years ago

0.0.2

7 years ago

0.0.1

7 years ago