Implementation:Webdriverio Webdriverio MSPO Overwrite

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

Overview

The MSPO Overwrite module patches WebdriverIO's $, $$, custom$, and custom$$ commands to transparently apply XPath-to-native selector optimization.

Description

The overwriteUserCommands function uses the browser's overwriteCommand API to intercept element-finding commands. For each intercepted call, it checks three guard conditions: whether a replacement is already in progress (to prevent recursion), whether the browser is in a native context, and whether the selector is an XPath expression. If all conditions pass, it delegates to optimizeSingleSelector or optimizeMultipleSelectors from the optimizer module. Single-element commands ($, custom$) and multiple-element commands ($$, custom$$) are handled separately.

Usage

This function is called once during the before hook of SelectorPerformanceService to set up command interception for the browser session.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-appium-service/src/mobileSelectorPerformanceOptimizer/overwrite.ts
Lines: 8-49

Signature

export function overwriteUserCommands(
    browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser,
    options: OptimizationOptions
): void

Import

import { overwriteUserCommands } from './mobileSelectorPerformanceOptimizer/overwrite.js'

I/O Contract

Inputs

Name	Type	Required	Description
browser	WebdriverIO.MultiRemoteBrowser	Yes	Browser instance whose commands will be overwritten; must support `overwriteCommand`
options	`OptimizationOptions`	Yes	Options containing browser reference, isReplacingSelector flag, and pageObjectPaths array

Outputs

Name	Type	Description
return	`void`	No return value; browser commands are mutated in place via overwriteCommand

Usage Examples

Applying Command Overwrites

import { overwriteUserCommands } from './overwrite.js'

// Called in SelectorPerformanceService.before()
overwriteUserCommands(browser, {
    browser: browser,
    isReplacingSelector: { value: false },
    pageObjectPaths: ['./tests/pageobjects']
})

Guard Condition Flow

// When $('//XCUIElementTypeButton[@name="Login"]') is called:
// 1. Check: options.isReplacingSelector.value === false -> continue
// 2. Check: isNativeContext(browser) === true -> continue
// 3. Check: isXPathSelector(selector) === true -> continue
// 4. Delegate to optimizeSingleSelector()
//
// When $('~Login') is called:
// 3. Check: isXPathSelector(selector) === false -> call original function

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment