Implementation:Webdriverio Webdriverio MSPO Optimizer

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

Overview

The MSPO Optimizer provides the core optimization logic that replaces XPath selectors with faster native iOS selectors during live test execution.

Description

The module exposes optimizeSingleSelector and optimizeMultipleSelectors, both of which delegate to a shared optimizeSelector function. The optimization flow follows a five-step process: (1) test the original XPath selector and measure its duration, (2) find an optimized native selector via the converter pipeline, (3) log the potential replacement, (4) test the optimized selector against the live browser, and (5) compare performance, store metrics, and execute the final command with the faster selector. If the optimized selector fails to find elements, the original XPath result is returned as a fallback.

Usage

These functions are called by the overwritten browser commands ($, $$, custom$, custom$$) when an XPath selector is detected in a native mobile context.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-appium-service/src/mobileSelectorPerformanceOptimizer/optimizer.ts
Lines: 36-163

Signature

export async function optimizeSingleSelector(
    commandName: string,
    selector: string,
    originalFunc: (selector: unknown) => Promise<WebdriverIO.Element>,
    browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser,
    options: OptimizationOptions
): Promise<WebdriverIO.Element>

export async function optimizeMultipleSelectors(
    commandName: string,
    selector: string,
    originalFunc: (selector: unknown) => Promise<WebdriverIO.Element[]>,
    browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser,
    options: OptimizationOptions
): Promise<WebdriverIO.Element[]>

Import

import { optimizeSingleSelector, optimizeMultipleSelectors } from './mobileSelectorPerformanceOptimizer/optimizer.js'

I/O Contract

Inputs

Name	Type	Required	Description
commandName	`string`	Yes	The WebdriverIO command name (e.g., '$', '$$', 'custom$', 'custom$$')
selector	`string`	Yes	The original XPath selector string
originalFunc	`(selector: unknown) => Promise<Element>`	Yes	The original command function to call as fallback or for final execution
browser	WebdriverIO.MultiRemoteBrowser	Yes	Browser instance used for page source retrieval and element finding
options	`OptimizationOptions`	Yes	Options including browser reference, isReplacingSelector flag, and pageObjectPaths

Outputs

Name	Type	Description
optimizeSingleSelector return	`Promise<WebdriverIO.Element>`	The found element, either via the optimized or original selector
optimizeMultipleSelectors return	`Promise<WebdriverIO.Element[]>`	The found elements, either via the optimized or original selector

Usage Examples

Internal Usage in Command Overwrite

browserWithOverwrite.overwriteCommand('$', async (
    originalFunc: (selector: unknown) => Promise<WebdriverIO.Element>,
    selector: unknown
) => {
    if (options.isReplacingSelector.value || !isNativeContext(browser) || !isXPathSelector(selector)) {
        return originalFunc.call(browser, selector)
    }

    return optimizeSingleSelector('$', selector, originalFunc, browser, options)
})

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment