Implementation:Webdriverio Webdriverio XPath Parser
| Knowledge Sources | |
|---|---|
| Domains | Mobile_Testing, XPath_Processing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
The XPath Parser module parses XPath expressions into structured segments with axes, element types, conditions, and indices.
Description
The parseXPathToSegments function is the main entry point that transforms an XPath string into an array of XPathSegment objects. Each segment captures the axis type (// for descendant or / for child), the element type (must be XCUIElementType* or wildcard * for iOS compatibility), extracted conditions, and optional positional index. The parser first validates the XPath by checking for unmappable features (parent traversal, sibling axes, unsupported functions) and union operators, then splits the path into raw segments while respecting bracket depth and quote boundaries, and finally parses each segment with condition extraction. Grouped expressions like (//Element[@attr="val"])[1] are supported by transforming the index into the last segment.
Usage
This function is called by the class chain converter to decompose multi-step XPath paths into individual segments that can each be converted to class chain syntax.
Code Reference
Source Location
- Repository: Webdriverio_Webdriverio
- File: packages/wdio-appium-service/src/mobileSelectorPerformanceOptimizer/utils/xpath-parser.ts
- Lines: 348-381
Signature
export function parseXPathToSegments(xpath: string): XPathSegment[] | null
Import
import { parseXPathToSegments } from './utils/xpath-parser.js'
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| xpath | string |
Yes | XPath expression to parse; must start with // or / and use iOS-compatible element types
|
Outputs
| Name | Type | Description |
|---|---|---|
| return | null | Array of parsed segments each containing axis, element, conditions, and optional index; returns null if the XPath contains unmappable features, union operators, non-iOS element types, or cannot be parsed |
Usage Examples
Parsing a Simple XPath
import { parseXPathToSegments } from './xpath-parser.js'
const segments = parseXPathToSegments('//XCUIElementTypeButton[@name="Login"]')
// Result:
// [{
// axis: '//',
// element: 'XCUIElementTypeButton',
// conditions: [{ attribute: 'name', operator: '=', value: 'Login' }],
// index: undefined
// }]
Parsing a Multi-Step XPath
const segments = parseXPathToSegments(
'//XCUIElementTypeTable/XCUIElementTypeCell[2]//XCUIElementTypeStaticText[@label="Title"]'
)
// Result:
// [
// { axis: '//', element: 'XCUIElementTypeTable', conditions: [], index: undefined },
// { axis: '/', element: 'XCUIElementTypeCell', conditions: [], index: 2 },
// { axis: '//', element: 'XCUIElementTypeStaticText',
// conditions: [{ attribute: 'label', operator: '=', value: 'Title' }], index: undefined }
// ]
Handling Unmappable XPath
// Returns null for XPath with parent traversal
const result = parseXPathToSegments('//XCUIElementTypeButton/../XCUIElementTypeCell')
// null
// Returns null for non-iOS element types
const result2 = parseXPathToSegments('//div[@class="container"]')
// null