Implementation:Webdriverio Webdriverio FirefoxProfileLauncher Class

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

Overview

Service launcher class that configures Firefox profiles with custom preferences, extensions, and proxy settings before WebdriverIO test sessions begin.

Description

FirefoxProfileLauncher is the default export class from the wdio-firefox-profile-service package. It implements the WebdriverIO service lifecycle by providing an onPrepare hook that runs before test execution. The class creates or copies a Firefox profile using the firefox-profile library, sets user preferences (iterating over all non-reserved option keys), configures proxy settings, installs extensions from .xpi files or directories, and encodes the resulting profile as a base64 zip. The zipped profile is then injected into each Firefox capability's moz:firefoxOptions.profile property, supporting both standard capability arrays and multiremote capability objects.

Usage

Use this service when tests require a customized Firefox profile with specific preferences (e.g., disabling notifications, setting a homepage), proxy configurations, or pre-installed extensions. Register it as a service in the WebdriverIO configuration with the desired FirefoxProfileOptions.

Code Reference

Source Location

• Repository: Webdriverio_Webdriverio
• File: packages/wdio-firefox-profile-service/src/launcher.ts

Signature

export default class FirefoxProfileLauncher {
    private _profile?: Profile
    constructor(private _options: FirefoxProfileOptions) {}

    async onPrepare(
        config: never,
        capabilities: Capabilities.TestrunnerCapabilities
    ): Promise<void>

    _setPreferences(): void

    async _buildExtension(
        capabilities: Capabilities.TestrunnerCapabilities
    ): Promise<void>

    _setProfile(
        capability: Capabilities.RequestedStandaloneCapabilities,
        zippedProfile: string
    ): void
}

Import

import FirefoxProfileLauncher from '@wdio/firefox-profile-service/launcher'

I/O Contract

Inputs

Name	Type	Required	Description
_options	FirefoxProfileOptions	Yes	Configuration object containing Firefox preferences, extensions, profileDirectory, proxy, and legacy flag
config	never	Yes	WebdriverIO config object (unused in this service)
capabilities	Capabilities.TestrunnerCapabilities	Yes	Test runner capabilities; supports both array and multiremote object formats

Outputs

Name	Type	Description
void	void	The method mutates the capabilities object in place, setting moz:firefoxOptions.profile on each Firefox capability

Methods

onPrepare(config, capabilities)

Entry point called by the WebdriverIO test runner before tests start. It creates or copies a Firefox profile based on profileDirectory, applies preferences and proxy via _setPreferences(), installs extensions if provided, and then calls _buildExtension() to encode and inject the profile into capabilities.

_setPreferences()

Iterates over all keys in _options except reserved keys (extensions, proxy, legacy, profileDirectory) and sets each as a Firefox preference via profile.setPreference(). If a proxy option is present, it calls profile.setProxy(). Finally calls profile.updatePreferences() to persist the changes.

_buildExtension(capabilities)

Encodes the profile to a base64 zip string using profile.encoded(). Then iterates over capabilities to find those with browserName === 'firefox' and calls _setProfile() for each. Handles both array-format capabilities (including nested multiremote structures) and object-format multiremote capabilities.

_setProfile(capability, zippedProfile)

Sets the moz:firefoxOptions.profile property on a single capability object. Handles both W3C alwaysMatch wrapper format and direct capability objects.

Usage Examples

// wdio.conf.ts
export const config = {
    services: [
        ['firefox-profile', {
            extensions: ['/path/to/extension.xpi'],
            'browser.startup.homepage': 'https://webdriver.io',
            proxy: {
                proxyType: 'manual',
                httpProxy: '127.0.0.1:8080',
                sslProxy: '127.0.0.1:8080'
            }
        }]
    ],
    capabilities: [{
        browserName: 'firefox'
    }]
}

// Programmatic usage
import FirefoxProfileLauncher from '@wdio/firefox-profile-service/launcher'

const launcher = new FirefoxProfileLauncher({
    'browser.download.dir': '/tmp/downloads',
    'browser.helperApps.neverAsk.saveToDisk': 'application/pdf',
    profileDirectory: '/path/to/existing/profile'
})

await launcher.onPrepare(config, capabilities)

Related Pages

• Principle:Webdriverio_Webdriverio_Service_Lifecycle