Robula+ XPath Locator Generator

Robula+ does not currently have a public npm package due to licensing clarifications. To use it, you must clone the repository, install dependencies, and build it locally to generate a lib folder for use in your projects.

Follow these steps:

1. Ensure Node.js is installed.
2. Clone the repository.
3. Install dependencies using npm install.
4. Build the project using npm run build.
5. Include the resulting lib folder in your JavaScript or TypeScript project.

git clone https://github.com/cyluxx/robula-plus.git
cd robula-plus
npm install
npm run build

This example demonstrates how to use RobulaPlus to take an existing absolute XPath, locate the corresponding element, and then generate a more robust version of that XPath.

import { RobulaPlus } from "robula-plus";

let robulaPlus = new RobulaPlus();
// 1. Locate the element using an absolute XPath
let element = robulaPlus.getElementByXPath('/html/body/div/span/a', document);

// 2. Generate the robust version
let robustXPath = robulaPlus.getRobustXPath(element, document);

The getRobustXPath(element, document) method returns an optimized, robust XPath locator string for a specific element. This locator is designed to be less fragile than absolute XPaths or Selenium IDE locators when web applications are updated.

Parameters:

• element (Element): The target element you want to describe.
• document (Document): The document containing the element to be analyzed.

import { RobulaPlus } from "robula-plus";

let robulaPlus = new RobulaPlus();
// Assuming 'element' and 'document' are available in your context
let robustXPath = robulaPlus.getRobustXPath(element, document);

The uniquelyLocate(xPath, element, document) method checks if a specific XPath describes only the provided element within the document. It returns true if the element is unique for that XPath, and false otherwise.

Parameters:

• xPath (string): The XPath string to test.
• element (Element): The element to verify.
• document (Document): The document to analyze.

The getElementByXPath(xPath, document) method returns the first element in the provided document that matches the given XPath locator.

Parameters:

• xPath (string): The XPath string describing the desired element.
• document (Document): The document to analyze.

When instantiating RobulaPlus, you can pass a RobulaPlusOptions object to control the algorithm's behavior:

• attributePriorizationList: A list of HTML attributes considered in a specific order when building predicates.
• attributeBlackList: A list of attributes considered too fragile (e.g., dynamic styles or event handlers) and ignored by the algorithm.

Defaults:

• attributePriorizationList: ['name', 'class', 'title', 'alt', 'value']
• attributeBlackList: ['href', 'src', 'onclick', 'onload', 'tabindex', 'width', 'height', 'style', 'size', 'maxlength']

import { RobulaPlus, RobulaPlusOptions } from 'robula-plus';

const options: RobulaPlusOptions = {
  attributePriorizationList: ['id', 'data-testid', 'role'],
  attributeBlackList: ['style', 'class']
};

const robula = new RobulaPlus(options);

The getElementByXPath method allows you to locate an Element within a Document using a standard XPath string.

const element = robula.getElementByXPath("//div[@id='container']", document);

The uniquelyLocate(xPath, element, document) method checks whether a given XPath string describes exactly one node and whether that node is the specific element provided. It returns true if the XPath is unique to that element, and false otherwise.

const isUnique = robula.uniquelyLocate("//button[@id='login']", targetElement, document);
if (isUnique) {
  console.log("The XPath is robust and unique!");
}

The RobulaPlus class implements an algorithm for generating robust XPath locators for web testing. You can instantiate it with optional configuration to customize which attributes are prioritized or blacklisted during the generation process.

Use getRobustXPath(element, document) to find the most optimized, unique XPath for a specific element within a document.

import { RobulaPlus } from 'robula-plus';

const robula = new RobulaPlus();
const robustXPath = robula.getRobustXPath(targetElement, document);
console.log(robustXPath); // e.g., "//button[@id='submit-btn']"