Implementation:Webdriverio Webdriverio XPath Converter

Knowledge Sources	Webdriverio_Webdriverio
Domains	Mobile_Testing, Selector_Optimization
Last Updated	2026-02-12 00:00 GMT

Overview

The XPath Converter is the main conversion API that transforms XPath selectors into optimized native iOS selectors using page source analysis and a priority-based selection strategy.

Description

The convertXPathToOptimizedSelector function is the top-level conversion entry point. It first detects any unmappable XPath features, then retrieves the page source from the browser, executes the XPath against the page source DOM to find the target element, and delegates to buildSelectorFromElementData to construct the optimal native selector. The priority order is: Accessibility ID (fastest), Predicate String (native predicate evaluation), and Class Chain (native hierarchy traversal). If the XPath matches multiple elements, the function returns a warning with the suggestion rather than a definitive selector. If page source is unavailable or analysis fails, appropriate warnings are returned.

Usage

This function is called by the optimizer module to find the best native selector replacement for a given XPath expression during live test execution.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-appium-service/src/mobileSelectorPerformanceOptimizer/utils/xpath-converter.ts
Lines: 21-91

Signature

export async function convertXPathToOptimizedSelector(
    xpath: string,
    options: XPathConversionOptions
): Promise<XPathConversionResult | null>

Import

import { convertXPathToOptimizedSelector } from './utils/xpath-converter.js'

I/O Contract

Inputs

Name	Type	Required	Description
xpath	`string`	Yes	XPath expression to convert to a native iOS selector
options	`XPathConversionOptions`	Yes	Options containing the browser instance used for page source retrieval

Outputs

Name	Type	Description
return	null>	Object with `selector` (the native selector string or null), optional `warning` message, and optional `suggestion` for non-unique matches; returns null if xpath is empty or not a string

Usage Examples

Converting an XPath to Native Selector

import { convertXPathToOptimizedSelector } from './xpath-converter.js'

const result = await convertXPathToOptimizedSelector(
    '//XCUIElementTypeButton[@name="Login"]',
    { browser }
)

if (result && result.selector) {
    // result.selector might be '~Login' (accessibility ID)
    console.log(`Optimized: ${result.selector}`)
} else if (result?.warning) {
    console.warn(result.warning)
}

Handling Non-Unique Matches

const result = await convertXPathToOptimizedSelector(
    '//XCUIElementTypeCell',
    { browser }
)

// If multiple elements match:
// result = {
//     selector: null,
//     warning: 'XPath matched 5 elements. The suggested selector may not be unique.',
//     suggestion: '-ios class chain:**/XCUIElementTypeCell'
// }

Handling Unmappable Features

const result = await convertXPathToOptimizedSelector(
    '//XCUIElementTypeButton/preceding-sibling::XCUIElementTypeStaticText',
    { browser }
)

// result = {
//     selector: null,
//     warning: 'XPath contains unmappable features: preceding-sibling axis. Element not found in page source.'
// }

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment