Implementation:Webdriverio Webdriverio AppiumLauncher Class

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

Overview

AppiumLauncher is a service class that manages the complete lifecycle of an Appium server process within a WebdriverIO test runner.

Description

The AppiumLauncher class implements the Services.ServiceInstance interface and is responsible for spawning, configuring, and terminating an Appium server process. It handles port assignment (with automatic free-port detection), capability patching to route sessions through the local Appium instance, log redirection, and graceful process termination using tree-kill. It also integrates with the Mobile Selector Performance Optimizer to aggregate performance data on test completion.

Usage

Use this class when you need to automatically start and stop an Appium server as part of the WebdriverIO test lifecycle. It is registered as the default export of the @wdio/appium-service package and is configured via the services array in wdio.conf.ts.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-appium-service/src/launcher.ts
Lines: 34-392

Signature

export default class AppiumLauncher implements Services.ServiceInstance {
    constructor(
        private _options: AppiumServiceConfig,
        private _capabilities: Capabilities.TestrunnerCapabilities,
        private _config?: Options.Testrunner
    )

    async onPrepare(): Promise<void>
    async onComplete(
        exitCode: number,
        config: Options.Testrunner,
        capabilities: Capabilities.TestrunnerCapabilities
    ): Promise<void>

    private _startAppium(
        command: string,
        args: Array<string>,
        timeout?: number
    ): Promise<ChildProcessByStdio<null, Readable, Readable>>

    private _setCapabilities(port: number): boolean
}

Import

import AppiumLauncher from '@wdio/appium-service/launcher'

I/O Contract

Inputs

Name	Type	Required	Description
_options	`AppiumServiceConfig`	Yes	Service configuration including logPath, command, args, appiumStartTimeout, and trackSelectorPerformance
_capabilities	`Capabilities.TestrunnerCapabilities`	Yes	Test runner capabilities to update with Appium connection details
_config	`Options.Testrunner`	No	WebdriverIO test runner configuration with outputDir and other settings

Outputs

Name	Type	Description
onPrepare return	`Promise<void>`	Resolves when Appium server is started and capabilities are updated
onComplete return	`Promise<void>`	Resolves when performance data is aggregated and the Appium process is terminated
_setCapabilities return	`boolean`	Returns true if at least one capability was updated with local Appium connection details

Usage Examples

Basic wdio.conf.ts Configuration

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    services: [
        ['appium', {
            logPath: './logs',
            args: {
                port: 4723,
                basePath: '/'
            }
        }]
    ],
    capabilities: [{
        'appium:platformName': 'iOS',
        'appium:deviceName': 'iPhone 15',
        'appium:app': './app.ipa'
    }]
}

With Selector Performance Tracking

export const config: WebdriverIO.Config = {
    services: [
        ['appium', {
            logPath: './logs',
            trackSelectorPerformance: {
                pageObjectPaths: ['./tests/pageobjects'],
                enableCliReport: true,
                enableMarkdownReport: true
            }
        }]
    ]
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment