@medv/finder

What is @medv/finder?

@medv/finder is an npm package that provides a utility for generating unique CSS selectors for DOM elements. This can be particularly useful for tasks such as automated testing, web scraping, and browser automation where you need to reliably identify and interact with specific elements on a web page.

What are @medv/finder's main functionalities?

Generate Unique CSS Selectors

This feature allows you to generate a unique CSS selector for a given DOM element. The generated selector can be used to reliably identify the element in various contexts such as automated tests or web scraping.

const finder = require('@medv/finder');
const element = document.querySelector('your-element-selector');
const selector = finder(element);
console.log(selector);

Customizable Options

This feature allows you to customize the options for generating the CSS selector. You can specify the root element, and control the inclusion of IDs, class names, tag names, and attributes in the generated selector.

const finder = require('@medv/finder');
const element = document.querySelector('your-element-selector');
const selector = finder(element, {
  root: document.body,
  idName: (name) => true,
  className: (name) => true,
  tagName: (name) => true,
  attr: (name, value) => false,
  seedMinLength: 1,
  optimizedMinLength: 2,
});
console.log(selector);

Other packages similar to @medv/finder

css-selector-generator

css-selector-generator is another npm package that generates unique CSS selectors for DOM elements. It offers similar functionality to @medv/finder but with a different API and customization options. It allows for more granular control over the selector generation process, including options for ignoring certain elements and attributes.

unique-selector

unique-selector is a package that also generates unique CSS selectors for DOM elements. It focuses on simplicity and ease of use, providing a straightforward API for generating selectors. While it may not offer as many customization options as @medv/finder, it is a good alternative for simpler use cases.

README

finder

CSS Selector Generator

Features

• Generates shortest selectors
• Unique selectors per page
• Stable and robust selectors
• 2.1 kB gzip and minify size

Install

npm install @medv/finder

Finder can be used via modules:

<script type="module">
  import {finder} from 'https://medv.io/finder/finder.js'
</script>

Usage

import {finder} from '@medv/finder'

document.addEventListener('click', event => {
  const selector = finder(event.target)
  console.log(selector)  
})

Example

Example of generated selector:

.blog > article:nth-child(3) .add-comment

Configuration

finder takes configuration object as second parameters. Here is example of all params with default values:

const selector = finder(event.target, {
  root: document.body,
  className: (name) => true,
  tagName: (name) => true,
  attr: (name, value) => false,
  seedMinLength: 1,
  optimizedMinLength: 2,
  threshold: 1000,
  maxNumberOfTries: 10_000,
})

root: Element

Root of search, defaults to document.body.

idName: (name: string) => boolean

Check if this ID can be used. For example you can restrict using framework specific IDs:

const selector = finder(event.target, {
  idName: name => !name.startsWith('ember')
})

className: (name: string) => boolean

Check if this class name can be used. For example you can restrict using is-* class names:

const selector = finder(event.target, {
  className: name => !name.startsWith('is-')
})

tagName: (name: string) => boolean

Check if tag name can be used, same as className.

attr: (name: string, value: string) => boolean

Check if attr name can be used.

seedMinLength: number

Minimum length of levels in fining selector. Starts from 1. For more robust selectors give this param value around 4-5 depending on depth of you DOM tree. If finder hits root this param is ignored.

optimizedMinLength: number

Minimum length for optimising selector. Starts from 2. For example selector body > div > div > p can be optimized to body p.

threshold: number

Max number of selectors to check before falling into nth-child usage. Checking for uniqueness of selector is very costs operation, if you have DOM tree depth of 5, with 5 classes on each level, that gives you more than 3k selectors to check. finder uses two step approach so it's reaching this threshold in some cases twice. Default 1000 is good enough in most cases.

maxNumberOfTries: number

Max number of tries when we do the optimization. It is a trade-off between optimization and efficiency. Default 10_000 is good enough in most cases.

Google Chrome Extension

Generate the unique selectors in your browser by using Chrome Extension

License

MIT