A port, package and unit testing of Firebug's XPath parsing and processing tools.
npm install potent-toolsPotent Tools for XPath and CSS
==============================
!Potent.js
  
Tools for working with the DOM, CSS selectors and XPath 1.0 expressions. All functionality in this repository is derived from Firebug, and has been modified for readability and to support pseudo-DOM, unit testing and ES6 standards.
This package solves four loosely related problems:
- Evaluating XPath expressions on arbitrary documents (including pseudo-DOM)
- Generating XPath expressions for paths in DOM structures
- Converting CSS selectors to XPath expressions (for evaluation or otherwise)
- Parsing CSS selectors for meaning (e.g. "body.thing" -> { element: body, class: thing }).
Installation
------------yarn add potent-tools
Usage
-----
``js
const {
generators,
evaluators,
cssToXPath
} = require('potent-tools');
{ // generators: generate XPath queries from elements.
/*
* generators.getElementXPath(element)
* Get the XPath string for a given DOM element.
*/
const xPath = generators.getElementXPath(domElement);
// /html/head/body/table/tr[2]/td/strong[@class='title']
console.log(xPath);
/*
* generators.getElementXPath(element, skipId)
* Get the fully qualified XPath string for a DOM element
* that has an ID, ignoring ID.
* e.g.,
*/
const xPath = generators.getElementXPath(
bobElement,
skipId = true
);
console.log(xPath); // /html/body/div[1]
const xPath = generators.getElementXPath(
bobElement,
skipId = false
);
console.log(xPath); // //*[@id='bob']
/*
* generators.getElementAttributes(element)
* Get all the HTML attributes on an element.
* This is exposed, but it is a support method for the XPath
* generator.
*/
const attributes = generators.getElementAttributes(bobElement);
console.log(bobElement); // { id: 'bob' }
}
{ // evaluators: run XPath queries or CSS selectors to find elements
/*
* evaluators.getElementsByXPath(document, xpathQuery)
* Get elements by XPath query.
*/
// element return type...
const elements = evaluators.getElementsByXPath(
document,
'/html/body/div'
);
console.log(elements); // [ DOMElement ]
// string return type...
const elements = evaluators.getElementsByXPath(
document,
'/html/body/div/text()'
);
console.log(elements); // [ "Hello world" ]
/*
* getElementsBySelector(document, rule)
* Get elements by CSS selector.
*/
const elements = evaluators
.getElementsBySelector(
document,
'html > body > div#id'
);
console.log(elements); // [ DOMElement ]
/*
* evaluators.evaluateXPath(doc, xpath, contextNode, resultType)
* Execute a query on a document.
* e.g.,
Hello world
*/
const stringResult = evaluators.evaluateXPath(
document,
'/html/body/div',
document, // optional, defaults to the document
XPathResult.STRING_TYPE, // optional, defaults to ANY_TYPE.
);
console.log(stringResult); // "Hello world"
}{ // cssToXPath: convert CSS queries to XPath queries
console.log(cssToXPath('html > body')); // //html>body
}
We have some tests that document this functionality as well. It should be possible to use our builds on the web as well, as they simply ignore the polyfills if they're already present.
License
-------
As the code in this repository is derived from the Firebug source code, its BSD 3-clause license applies.
Development
-----------
I will accept pull requests which do not deviate from the intent of the original Firebug code, as the intent of this repository is simply to cleanup, standardize and package the Firebug XPath library for reuse.
- In general, readability will be preferred to conciseness.
- Please ensure all unit tests pass (
).
- Please ensure new code has sufficient coverage (yarn run coverage).
- Please ensure code has been linted to meet the formatting standards (I use eslint-config-strawhouse and Prettier).To build a web distribution,
yarn run build should update the files in dist/`.