### Install Robula+ Dependencies - Shell

Source: https://github.com/cyluxx/robula-plus/blob/master/README.md

Navigates into the cloned Robula+ project directory and installs all necessary Node.js dependencies using npm. This command is part of the manual installation process and requires Node.js and npm to be installed.

```shell
cd robula-plus
npm install
```

--------------------------------

### Clone Robula+ Repository - Shell

Source: https://github.com/cyluxx/robula-plus/blob/master/README.md

Clones the Robula+ project repository from GitHub using Git. This command is the first step for manually installing and building the library if a public package is not available. It requires Git to be installed on the system.

```shell
git clone https://github.com/cyluxx/robula-plus.git
```

--------------------------------

### XPath Class for XPath Manipulation

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Provides a helper class for direct manipulation and analysis of XPath expressions. This class offers methods to get the XPath string value, check for starting patterns, extract substrings, and identify various types of predicates (general, position, and text) within an XPath. It also allows for adding predicates to the head element and retrieving the XPath's depth.

```typescript
import { XPath } from 'robula-plus';

// Create XPath instance
const xpath = new XPath('//div');

// Get the XPath string value
console.log(xpath.getValue()); // "//div"

// Check if XPath starts with a pattern
console.log(xpath.startsWith('//*')); // false
console.log(xpath.startsWith('//div')); // true

// Get substring of XPath
console.log(xpath.substring(2)); // "div"

// Check for predicates
const xpathWithPredicate = new XPath("//div[@id='foo']");
console.log(xpathWithPredicate.headHasAnyPredicates()); // true

const xpathNoPredicate = new XPath('//div');
console.log(xpathNoPredicate.headHasAnyPredicates()); // false

// Check for position predicates
const xpathPosition = new XPath('//div[2]');
console.log(xpathPosition.headHasPositionPredicate()); // true

// Check for text predicates
const xpathText = new XPath('//div[text()="foo"]');
console.log(xpathText.headHasTextPredicate()); // true

// Add predicate to head element
const xpathMultiLevel = new XPath('//foo/bar');
xpathMultiLevel.addPredicateToHead('[predicate]');
console.log(xpathMultiLevel.getValue()); // "//foo[predicate]/bar"

// Get XPath depth/length
const xpath1 = new XPath('//*');
console.log(xpath1.getLength()); // 1

const xpath2 = new XPath('//*/*');
console.log(xpath2.getLength()); // 2
```

--------------------------------

### XPath Class

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Provides a helper class for manipulating and analyzing XPath expressions. It offers methods for getting XPath values, checking patterns, and examining predicates.

```APIDOC
## XPath Class

### Description
A helper class for manipulating and analyzing XPath expressions. Used internally by the algorithm but also available for direct use.

### Constructor
- **new XPath(xpathString)**: Initializes a new XPath object with the provided XPath string.

### Methods
#### getValue()
- Returns the XPath string value.

#### startsWith(pattern)
- Checks if the XPath starts with the given pattern.
- Returns: `boolean`

#### substring(start)
- Returns a substring of the XPath starting from the specified index.
- Returns: `string`

#### headHasAnyPredicates()
- Checks if the head of the XPath has any predicates.
- Returns: `boolean`

#### headHasPositionPredicate()
- Checks if the head of the XPath has a position predicate (e.g., `[2]`).
- Returns: `boolean`

#### headHasTextPredicate()
- Checks if the head of the XPath has a text predicate (e.g., `[text()='foo']`).
- Returns: `boolean`

#### addPredicateToHead(predicate)
- Adds a predicate to the head element of the XPath.

#### getLength()
- Returns the depth or number of steps in the XPath.
- Returns: `number`

### Request Example
```typescript
import { XPath } from 'robula-plus';

// Create XPath instance
const xpath = new XPath('//div');

// Get the XPath string value
console.log(xpath.getValue()); // "//div"

// Check if XPath starts with a pattern
console.log(xpath.startsWith('//*')); // false
console.log(xpath.startsWith('//div')); // true

// Get substring of XPath
console.log(xpath.substring(2)); // "div"

// Check for predicates
const xpathWithPredicate = new XPath("//div[@id='foo']");
console.log(xpathWithPredicate.headHasAnyPredicates()); // true

const xpathNoPredicate = new XPath('//div');
console.log(xpathNoPredicate.headHasAnyPredicates()); // false

// Check for position predicates
const xpathPosition = new XPath('//div[2]');
console.log(xpathPosition.headHasPositionPredicate()); // true

// Check for text predicates
const xpathText = new XPath('//div[text()="foo"]');
console.log(xpathText.headHasTextPredicate()); // true

// Add predicate to head element
const xpathMultiLevel = new XPath('//foo/bar');
xpathMultiLevel.addPredicateToHead('[predicate]');
console.log(xpathMultiLevel.getValue()); // "//foo[predicate]/bar"

// Get XPath depth/length
const xpath1 = new XPath('//*');
console.log(xpath1.getLength()); // 1

const xpath2 = new XPath('//*/*');
console.log(xpath2.getLength()); // 2
```

### Response
#### Success Response (Various Types)
- Methods return different types based on their function (string, boolean, number).

#### Response Example (getValue)
```json
{
  "xpathString": "//div"
}
```

#### Response Example (startsWith)
```json
{
  "startsWithPattern": true
}
```
```

--------------------------------

### Build Robula+ Code - Shell

Source: https://github.com/cyluxx/robula-plus/blob/master/README.md

Compiles the Robula+ source code using npm scripts, typically generating JavaScript files in a 'lib' folder. This command is executed after installing dependencies and is necessary for building the library for use in other projects. It requires Node.js and npm.

```shell
npm run build
```

--------------------------------

### Generate Robust XPath Locators with getRobustXPath

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Shows how to use the getRobustXPath method to generate unique and stable XPath locators for a given DOM element. Examples cover identification by tag name, ID, text content, attributes, attribute combinations, position, and DOM hierarchy.

```typescript
import { RobulaPlus } from 'robula-plus';

const robulaPlus = new RobulaPlus();

// Example 1: Element unique by tag name
// HTML: <body><h1>Heading</h1><p>Paragraph</p><div>Content</div></body>
const divElement = document.querySelector('div');
const xpath1 = robulaPlus.getRobustXPath(divElement, document);
// Result: "//div"

// Example 2: Element unique by ID
// HTML: <body><div id="bar"><div id="1"></div></div><div id="42"></div></body>
const targetElement = document.querySelector('#42');
const xpath2 = robulaPlus.getRobustXPath(targetElement, document);
// Result: "//*[@id='42']"

// Example 3: Element unique by text content
// HTML: <body><h1>Not this</h1><h1>Target text</h1><h1>Not this</h1></body>
const textElement = document.querySelectorAll('h1')[1];
const xpath3 = robulaPlus.getRobustXPath(textElement, document);
// Result: "//*[contains(text(),'Target text')]"

// Example 4: Element unique by class attribute
// HTML: <body><h1 class="false"></h1><h1 class="true"></h1><h1 class="false"></h1></body>
const classElement = document.querySelector('.true');
const xpath4 = robulaPlus.getRobustXPath(classElement, document);
// Result: "//*[@class='true']"

// Example 5: Element unique by attribute combination
// HTML: <body><h1 class="foo" title="bar"></h1><h1 class="foo" title="baz"></h1></body>
const attrSetElement = document.querySelectorAll('h1')[1];
const xpath5 = robulaPlus.getRobustXPath(attrSetElement, document);
// Result: "//*[@class='foo' and @title='baz']"

// Example 6: Element unique by position
// HTML: <body><h1></h1><h1></h1><h1></h1></body>
const posElement = document.querySelectorAll('h1')[2];
const xpath6 = robulaPlus.getRobustXPath(posElement, document);
// Result: "//*[3]"

// Example 7: Element unique by DOM level/hierarchy
// HTML: <body><h1></h1><div><h1></h1></div><h1></h1></body>
const nestedElement = document.querySelector('div h1');
const xpath7 = robulaPlus.getRobustXPath(nestedElement, document);
// Result: "//div/*"

// Error handling: Element not in document
try {
  const orphanElement = document.createElement('span');
  robulaPlus.getRobustXPath(orphanElement, document);
} catch (error) {
  console.error(error.message); // "Document does not contain given element!"
}
```

--------------------------------

### Get Element by XPath - JavaScript

Source: https://github.com/cyluxx/robula-plus/blob/master/README.md

Retrieves the first HTML element that matches a given XPath locator string within a specified document. This is a fundamental utility for interacting with DOM elements using XPath. It takes an XPath string and the document object as parameters.

```javascript
import { RobulaPlus } from "robula-plus";

let robulaPlus = new RobulaPlus();
let element = robulaPlus.getElementByXPath('/html/body/div/span/a', document);
```

--------------------------------

### Get Robust XPath from Element - JavaScript

Source: https://github.com/cyluxx/robula-plus/blob/master/README.md

Generates an optimized, robust XPath locator string for a given HTML element within a document. This method is crucial for creating locators that are less likely to break with website changes. It requires the target element and the document object as input.

```javascript
import { RobulaPlus } from "robula-plus";

let robulaPlus = new RobulaPlus();
let element = robulaPlus.getElementByXPath('/html/body/div/span/a', document);
robulaPlus.getRobustXPath(element, document);
```

--------------------------------

### Instantiate RobulaPlus Class with Options

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Demonstrates how to create an instance of the RobulaPlus class, either with default options or custom configurations for attribute prioritization and blacklisting. This allows fine-tuning of the XPath generation process.

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

// Basic instantiation with default options
const robulaPlus = new RobulaPlus();

// Custom instantiation with specific attribute lists
const options: RobulaPlusOptions = {
  // Attributes to prioritize when building locators (checked first)
  attributePriorizationList: ['name', 'class', 'title', 'alt', 'value', 'data-testid'],
  // Attributes to ignore (too fragile/dynamic)
  attributeBlackList: ['href', 'src', 'onclick', 'onload', 'tabindex', 'width', 'height', 'style', 'size', 'maxlength']
};
const customRobulaPlus = new RobulaPlus(options);
```

--------------------------------

### Configure Robula+ Options in TypeScript

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Demonstrates how to instantiate and configure RobulaPlusOptions in TypeScript. It shows the default attribute prioritization and blacklisting, as well as custom configurations for data attributes and accessibility-focused locators.

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

// Default options (used when no options provided)
const defaultOptions = new RobulaPlusOptions();
console.log(defaultOptions.attributePriorizationList);
// ['name', 'class', 'title', 'alt', 'value']

console.log(defaultOptions.attributeBlackList);
// ['href', 'src', 'onclick', 'onload', 'tabindex', 'width', 'height', 'style', 'size', 'maxlength']

// Custom configuration for data-* attributes
const dataAttrOptions: RobulaPlusOptions = {
  attributePriorizationList: ['data-testid', 'data-cy', 'data-qa', 'id', 'name', 'class'],
  attributeBlackList: ['href', 'src', 'onclick', 'onload', 'style', 'tabindex']
};
const testingRobulaPlus = new RobulaPlus(dataAttrOptions);

// Configuration for accessibility-focused locators
const a11yOptions: RobulaPlusOptions = {
  attributePriorizationList: ['aria-label', 'aria-labelledby', 'role', 'name', 'title'],
  attributeBlackList: ['style', 'class', 'onclick', 'onload', 'tabindex']
};
const a11yRobulaPlus = new RobulaPlus(a11yOptions);
```

--------------------------------

### Robula+ Core Methods

Source: https://github.com/cyluxx/robula-plus/blob/master/README.md

This section details the primary methods provided by the Robula+ library for generating and working with robust XPath locators.

```APIDOC
## Robula+ API

### `getRobustXPath(element, document)`

#### Description
Returns an optimized robust XPath locator string, describing a desired element.

#### Method
`getRobustXPath`

#### Parameters

##### Path Parameters
N/A

##### Query Parameters
N/A

##### Request Body
N/A

#### Request Example
```javascript
// Assuming 'robulaPlus' is an instance of RobulaPlus and 'element' and 'document' are defined
let robustXPath = robulaPlus.getRobustXPath(element, document);
```

#### Response

##### Success Response (200)
- **xpath** (string) - The generated robust XPath locator.

##### Response Example
```json
{
  "xpath": "//div[@id='main']/span/a"
}
```

---

### `getElementByXPath(xPath, document)`

#### Description
Returns the first element in the given document located by the given xPath locator.

#### Method
`getElementByXPath`

#### Parameters

##### Path Parameters
N/A

##### Query Parameters
N/A

##### Request Body
N/A

#### Request Example
```javascript
// Assuming 'robulaPlus' is an instance of RobulaPlus and 'document' is defined
let xPath = "//div[@id='main']/span/a";
let element = robulaPlus.getElementByXPath(xPath, document);
```

#### Response

##### Success Response (200)
- **element** (Element) - The DOM element found by the XPath.

##### Response Example
```json
{
  "element": "<a href='#'>Link Text</a>"
}
```

---

### `uniquelyLocate(xPath, element, document)`

#### Description
Returns _true_, if the xPath describes only the desired element.

#### Method
`uniquelyLocate`

#### Parameters

##### Path Parameters
N/A

##### Query Parameters
N/A

##### Request Body
N/A

#### Request Example
```javascript
// Assuming 'robulaPlus' is an instance of RobulaPlus and 'element', 'document' are defined
let xPath = "//div[@id='main']/span/a";
let isUnique = robulaPlus.uniquelyLocate(xPath, element, document);
```

#### Response

##### Success Response (200)
- **isUnique** (boolean) - True if the XPath uniquely identifies the element, false otherwise.

##### Response Example
```json
{
  "isUnique": true
}
```
```

--------------------------------

### getElementByXPath

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Retrieves the first element in the document that matches the provided XPath string. This is useful for locating elements using XPath expressions.

```APIDOC
## getElementByXPath(xPath, document)

### Description
Returns the first element in the document that matches the given XPath locator string. Useful for locating elements using previously generated XPath expressions.

### Method
`getElementByXPath`

### Parameters
#### Path Parameters
- **xPath** (string) - Required - The XPath expression to locate the element.
- **document** (Document) - Required - The document object to search within.

### Request Example
```typescript
import { RobulaPlus } from 'robula-plus';

const robulaPlus = new RobulaPlus();

// Find element by absolute XPath
const element1 = robulaPlus.getElementByXPath('/html/body/div', document);

// Find element by relative XPath with ID
const element2 = robulaPlus.getElementByXPath("//*[@id='submit-button']", document);

// Find element by class attribute
const element3 = robulaPlus.getElementByXPath("//*[@class='nav-item']", document);

// Find element by text content
const element4 = robulaPlus.getElementByXPath("//*[contains(text(),'Click here')]", document);

// Find element by position
const element5 = robulaPlus.getElementByXPath('//ul/li[3]', document);

// Returns null if element not found
const notFound = robulaPlus.getElementByXPath('/div/span/nonexistent', document);
console.log(notFound); // null

// Practical workflow: Convert absolute XPath to robust XPath
const absoluteXPath = '/html/body/div[2]/form/input[3]';
const element = robulaPlus.getElementByXPath(absoluteXPath, document);
if (element) {
  const robustXPath = robulaPlus.getRobustXPath(element, document);
  console.log(`Robust locator: ${robustXPath}`);
}
```

### Response
#### Success Response (Element)
- **element** (Element) - The first DOM element that matches the XPath, or null if not found.

#### Response Example
```json
{
  "element": "<div id=\"myDiv\">...</div>" 
}
```

#### Error Response (null)
- **null** - Returned when no element matches the provided XPath.

#### Response Example
```json
null
```
```

--------------------------------

### Find Element by XPath using Robula Plus

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Locates the first element in a document that matches a given XPath string. It accepts various XPath formats, including absolute, relative, attribute-based, text-based, and position-based locators. Returns null if no element is found. Useful for finding elements when you have an XPath expression.

```typescript
import { RobulaPlus } from 'robula-plus';

const robulaPlus = new RobulaPlus();

// Find element by absolute XPath
const element1 = robulaPlus.getElementByXPath('/html/body/div', document);

// Find element by relative XPath with ID
const element2 = robulaPlus.getElementByXPath("//*[@id='submit-button']", document);

// Find element by class attribute
const element3 = robulaPlus.getElementByXPath("//*[@class='nav-item']", document);

// Find element by text content
const element4 = robulaPlus.getElementByXPath("//*[contains(text(),'Click here')]", document);

// Find element by position
const element5 = robulaPlus.getElementByXPath('//ul/li[3]', document);

// Returns null if element not found
const notFound = robulaPlus.getElementByXPath('/div/span/nonexistent', document);
console.log(notFound); // null

// Practical workflow: Convert absolute XPath to robust XPath
const absoluteXPath = '/html/body/div[2]/form/input[3]';
const element = robulaPlus.getElementByXPath(absoluteXPath, document);
if (element) {
  const robustXPath = robulaPlus.getRobustXPath(element, document);
  console.log(`Robust locator: ${robustXPath}`);
}
```

--------------------------------

### Verify XPath Uniqueness with Robula Plus

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Determines if a given XPath expression uniquely identifies a specific target element within a document. This function is valuable for validating the specificity of XPath locators. It returns true if the XPath matches only the provided element, and false otherwise, including cases where the XPath matches multiple elements or no elements.

```typescript
import { RobulaPlus } from 'robula-plus';

const robulaPlus = new RobulaPlus();

// Create test document
const doc = document.implementation.createHTMLDocument('');
doc.body.innerHTML = '<span id="first"></span><span id="second"></span><div></div>';

const firstSpan = doc.querySelector('#first');
const secondSpan = doc.querySelector('#second');
const divElement = doc.querySelector('div');

// XPath uniquely identifies the element
const isUnique1 = robulaPlus.uniquelyLocate("//*[@id='first']", firstSpan, doc);
console.log(isUnique1); // true

// XPath uniquely identifies div (only one div in document)
const isUnique2 = robulaPlus.uniquelyLocate('//div', divElement, doc);
console.log(isUnique2); // true

// XPath matches multiple elements (not unique)
const isUnique3 = robulaPlus.uniquelyLocate('//span', firstSpan, doc);
console.log(isUnique3); // false (matches both spans)

// XPath matches wrong element
const isUnique4 = robulaPlus.uniquelyLocate("//*[@id='second']", firstSpan, doc);
console.log(isUnique4); // false (matches secondSpan, not firstSpan)

// XPath matches no elements
const isUnique5 = robulaPlus.uniquelyLocate('//nonexistent', firstSpan, doc);
console.log(isUnique5); // false

// Validate a robust XPath before using it
const targetElement = doc.querySelector('#second');
const robustXPath = robulaPlus.getRobustXPath(targetElement, doc);
if (robulaPlus.uniquelyLocate(robustXPath, targetElement, doc)) {
  console.log(`Verified unique locator: ${robustXPath}`);
}
```

--------------------------------

### Uniquely Locate Element by XPath - JavaScript

Source: https://github.com/cyluxx/robula-plus/blob/master/README.md

Checks if a given XPath locator uniquely identifies a specific target element within a document. This function is useful for ensuring that a generated XPath points to only the intended element, preventing ambiguity. It requires the XPath, the target element, and the document as input.

```javascript
import { RobulaPlus } from "robula-plus";

let robulaPlus = new RobulaPlus();
let element = robulaPlus.getElementByXPath('/html/body/div/span/a', document);
robulaPlus.uniquelyLocate('/html/body/div/span/a', element, document);
```

--------------------------------

### uniquelyLocate

Source: https://context7.com/cyluxx/robula-plus/llms.txt

Determines if a given XPath expression uniquely identifies only the specified element within the document. This is useful for verifying the specificity of XPath locators.

```APIDOC
## uniquelyLocate(xPath, element, document)

### Description
Returns true if the given XPath expression uniquely identifies only the specified element within the document. Useful for validating that an XPath locator is specific enough.

### Method
`uniquelyLocate`

### Parameters
#### Path Parameters
- **xPath** (string) - Required - The XPath expression to validate.
- **element** (Element) - Required - The specific DOM element that the XPath should uniquely identify.
- **document** (Document) - Required - The document object to search within.

### Request Example
```typescript
import { RobulaPlus } from 'robula-plus';

const robulaPlus = new RobulaPlus();

// Create test document
const doc = document.implementation.createHTMLDocument('');
doc.body.innerHTML = '<span id="first"></span><span id="second"></span><div></div>';

const firstSpan = doc.querySelector('#first');
const secondSpan = doc.querySelector('#second');
const divElement = doc.querySelector('div');

// XPath uniquely identifies the element
const isUnique1 = robulaPlus.uniquelyLocate("//*[@id='first']", firstSpan, doc);
console.log(isUnique1); // true

// XPath uniquely identifies div (only one div in document)
const isUnique2 = robulaPlus.uniquelyLocate('//div', divElement, doc);
console.log(isUnique2); // true

// XPath matches multiple elements (not unique)
const isUnique3 = robulaPlus.uniquelyLocate('//span', firstSpan, doc);
console.log(isUnique3); // false (matches both spans)

// XPath matches wrong element
const isUnique4 = robulaPlus.uniquelyLocate("//*[@id='second']", firstSpan, doc);
console.log(isUnique4); // false (matches secondSpan, not firstSpan)

// XPath matches no elements
const isUnique5 = robulaPlus.uniquelyLocate('//nonexistent', firstSpan, doc);
console.log(isUnique5); // false

// Validate a robust XPath before using it
const targetElement = doc.querySelector('#second');
const robustXPath = robulaPlus.getRobustXPath(targetElement, doc);
if (robulaPlus.uniquelyLocate(robustXPath, targetElement, doc)) {
  console.log(`Verified unique locator: ${robustXPath}`);
}
```

### Response
#### Success Response (Boolean)
- **isUnique** (boolean) - True if the XPath uniquely identifies the element, false otherwise.

#### Response Example
```json
{
  "isUnique": true 
}
```

#### Response Example (False)
```json
{
  "isUnique": false 
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.