Implementation:Webdriverio Webdriverio XPath ClassChain

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

Overview

The XPath ClassChain module converts XPath expressions to iOS Class Chain selectors, supporting multi-step hierarchies, conditions, and indices.

Description

The convertXPathToClassChain function uses the XPath parser to decompose an expression into segments and then builds an iOS class chain string. Each segment is converted based on its axis (// becomes **/ for descendant, / becomes direct child), element type, conditions (converted to backtick-delimited predicate expressions using double-quoted values), and optional positional index. OR conditions are grouped with parentheses, and last() index is preserved. Internal helpers segmentToClassChain and conditionsToClassChainPredicate handle per-segment conversion and condition grouping.

Usage

This function is called as the third-priority conversion strategy (after Accessibility ID and Predicate String) in the selector builder pipeline.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-appium-service/src/mobileSelectorPerformanceOptimizer/utils/xpath-class-chain.ts
Lines: 82-121

Signature

export function convertXPathToClassChain(xpath: string): XPathConversionResult | null

Import

import { convertXPathToClassChain } from './utils/xpath-class-chain.js'

I/O Contract

Inputs

Name	Type	Required	Description
xpath	`string`	Yes	XPath expression to convert; must use iOS-compatible element types (XCUIElementType* or wildcard *)

Outputs

Name	Type	Description
return	null	Object with `selector` property containing the `-ios class chain:` prefixed string; returns null if the XPath cannot be parsed or contains unmappable features

Usage Examples

Simple Class Chain Conversion

import { convertXPathToClassChain } from './xpath-class-chain.js'

const result = convertXPathToClassChain('//XCUIElementTypeButton[@name="Login"]')
// { selector: '-ios class chain:**/XCUIElementTypeButton[`name == "Login"`]' }

Multi-Step Hierarchy

const result = convertXPathToClassChain(
    '//XCUIElementTypeTable/XCUIElementTypeCell[2]//XCUIElementTypeStaticText[@label="Title"]'
)
// { selector: '-ios class chain:**/XCUIElementTypeTable/XCUIElementTypeCell[2]/**/XCUIElementTypeStaticText[`label == "Title"`]' }

With OR Conditions

const result = convertXPathToClassChain(
    '//XCUIElementTypeButton[@name="OK" or @name="Cancel"]'
)
// { selector: '-ios class chain:**/XCUIElementTypeButton[`(name == "OK" OR name == "Cancel")`]' }

Unmappable XPath Returns Null

const result = convertXPathToClassChain('//div[@class="container"]')
// null (non-iOS element type)

const result2 = convertXPathToClassChain('//XCUIElementTypeButton/../XCUIElementTypeCell')
// null (parent traversal is unmappable)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment