Implementation:Webdriverio Webdriverio FirefoxProfile Types

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

Overview

Type definitions for Firefox profile configuration including proxy settings, extensions, and browser preferences used by the wdio-firefox-profile-service.

Description

This module defines the FirefoxProfileOptions interface that extends FirefoxSettings (a Record<string, unknown> representing arbitrary Firefox about:config preferences). It includes typed properties for extensions (array of .xpi file paths or unpacked extension directories), profileDirectory (path to an existing profile to copy), proxy (a discriminated union of four proxy configuration types), and legacy (flag for Firefox v55 and below). The ProxySettings union type covers direct (no proxy), system (OS proxy), pac (automatic via URL), and manual (per-protocol proxy addresses) configurations.

Usage

Use these types when configuring the Firefox profile service in a WebdriverIO project. They provide compile-time type safety for the service options object passed in wdio.conf.ts and are consumed by the FirefoxProfileLauncher class.

Code Reference

Source Location

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

Signature

type FirefoxSettings = Record<string, unknown>

interface NoProxySettings {
    proxyType: 'direct'
}

interface SystemProxySettings {
    proxyType: 'system'
}

interface AutomaticProxySettings {
    proxyType: 'pac'
    autoConfigUrl: string
}

interface ManualProxySettings {
    proxyType: 'manual'
    ftpProxy?: string
    httpProxy?: string
    sslProxy?: string
    socksProxy?: string
}

type ProxySettings = NoProxySettings | SystemProxySettings | AutomaticProxySettings | ManualProxySettings

export interface FirefoxProfileOptions extends FirefoxSettings {
    extensions?: string[]
    profileDirectory?: string
    proxy?: ProxySettings
    legacy?: boolean
}

Import

import type { FirefoxProfileOptions } from '@wdio/firefox-profile-service/types'

I/O Contract

Inputs

Name	Type	Required	Description
extensions	string[]	No	Array of absolute paths to .xpi files or unpacked extension directories (default: [])
profileDirectory	string	No	Absolute path to an existing Firefox profile to copy as the base (default: null)
proxy	ProxySettings	No	Proxy configuration object; discriminated by proxyType field
legacy	boolean	No	Set to true for Firefox v55 or lower (default: false)
[key: string]	unknown	No	Any additional key-value pairs are treated as Firefox about:config preferences

Outputs

Name	Type	Description
FirefoxProfileOptions	interface	Type-safe configuration object consumed by FirefoxProfileLauncher

Type Details

ProxySettings Union

The ProxySettings type is a discriminated union based on the proxyType field:

Variant	proxyType	Additional Fields	Description
NoProxySettings	'direct'	(none)	Direct connection with no proxy
SystemProxySettings	'system'	(none)	Use operating system proxy settings
AutomaticProxySettings	'pac'	autoConfigUrl: string	Automatic proxy via PAC URL
ManualProxySettings	'manual'	ftpProxy?, httpProxy?, sslProxy?, socksProxy?	Per-protocol manual proxy configuration

Usage Examples

// Direct proxy (no proxy)
const options: FirefoxProfileOptions = {
    proxy: { proxyType: 'direct' }
}

// Automatic proxy via PAC URL
const optionsPac: FirefoxProfileOptions = {
    proxy: {
        proxyType: 'pac',
        autoConfigUrl: 'http://myserver/proxy.pac'
    }
}

// Manual HTTP and HTTPS proxy with preferences
const optionsManual: FirefoxProfileOptions = {
    extensions: ['/path/to/adblock.xpi'],
    'browser.startup.homepage': 'https://webdriver.io',
    proxy: {
        proxyType: 'manual',
        httpProxy: '127.0.0.1:8080',
        sslProxy: '127.0.0.1:8080'
    }
}

Related Pages

• Principle:Webdriverio_Webdriverio_Service_Configuration