Implementation:Webdriverio Webdriverio Selector Utils
| Knowledge Sources | |
|---|---|
| Domains | Mobile_Testing, Selector_Processing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
The Selector Utils module provides core utility functions for classifying, extracting, and parsing selectors used in element-finding commands.
Description
This module contains four utility functions. isElementFindCommand checks whether a given command name is an element-finding command (e.g., $, $$, findElement, shadow$, etc.). extractSelectorFromArgs extracts a selector string from command arguments, handling string, object, and other types. isXPathSelector determines if a selector is an XPath expression by checking for patterns like /, //, ./, ../, and grouped expressions with (, while excluding CSS pseudo-selectors. parseOptimizedSelector converts optimized selector strings into WebDriver protocol format, mapping ~ prefix to accessibility id, -ios predicate string: prefix to iOS predicate strategy, and -ios class chain: prefix to iOS class chain strategy.
Usage
These functions are used throughout the MSPO system to determine when to track and optimize selectors, and to convert between selector formats.
Code Reference
Source Location
- Repository: Webdriverio_Webdriverio
- File: packages/wdio-appium-service/src/mobileSelectorPerformanceOptimizer/utils/selector-utils.ts
- Lines: 8-105
Signature
export function isElementFindCommand(commandName: string): boolean
export function extractSelectorFromArgs(args: unknown[]): string | null
export function isXPathSelector(selector: unknown): selector is string
export function parseOptimizedSelector(optimizedSelector: string): { using: string, value: string } | null
Import
import { isElementFindCommand, extractSelectorFromArgs, isXPathSelector, parseOptimizedSelector } from './utils/selector-utils.js'
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| commandName | string |
Yes | WebdriverIO command name to check (for isElementFindCommand) |
| args | unknown[] |
Yes | Command arguments array (for extractSelectorFromArgs) |
| selector | unknown |
Yes | Selector value to check (for isXPathSelector) |
| optimizedSelector | string |
Yes | Optimized selector string with strategy prefix (for parseOptimizedSelector) |
Outputs
| Name | Type | Description |
|---|---|---|
| isElementFindCommand return | boolean |
True if the command is an element-finding command ($, $$, findElement, findElements, custom$, custom$$, shadow$, shadow$$, etc.) |
| extractSelectorFromArgs return | null | Extracted selector string from the first argument, or null if args is empty |
| isXPathSelector return | boolean |
True if the selector matches XPath patterns (type guard narrowing to string) |
| parseOptimizedSelector return | null | WebDriver protocol using/value pair, or null if the selector format is not recognized |
Usage Examples
Checking XPath Selectors
import { isXPathSelector } from './selector-utils.js'
isXPathSelector('//XCUIElementTypeButton[@name="Login"]') // true
isXPathSelector('//*[@name="Submit"]') // true
isXPathSelector('~Login') // false
isXPathSelector('.my-class') // false
isXPathSelector('(:has(.child))') // false (CSS pseudo)
Parsing Optimized Selectors
import { parseOptimizedSelector } from './selector-utils.js'
parseOptimizedSelector('~Login')
// { using: 'accessibility id', value: 'Login' }
parseOptimizedSelector("-ios predicate string:type == 'XCUIElementTypeButton' AND name == 'Login'")
// { using: '-ios predicate string', value: "type == 'XCUIElementTypeButton' AND name == 'Login'" }
parseOptimizedSelector('-ios class chain:**/XCUIElementTypeButton[`name == "Login"`]')
// { using: '-ios class chain', value: '**/XCUIElementTypeButton[`name == "Login"`]' }
parseOptimizedSelector('#someId')
// null (not a recognized native selector)