Implementation:Webdriverio Webdriverio Browser Runner Config

Metadata

Field	Value
Page ID	Browser_Runner_Config
Wiki	Webdriverio_Webdriverio
Type	Implementation (API Doc)
Domains	Testing, Configuration, Frontend
Knowledge Sources	Repo (https://github.com/webdriverio/webdriverio), Doc (https://webdriver.io/docs/component-testing/vue)
Related Principles	Principle: Browser_Runner_Configuration

Overview

Concrete tool for configuring the Vite-based browser runner provided by the @wdio/browser-runner package. The browser runner configuration is specified as the runner property in wdio.conf.ts. It configures Vite dev server settings, framework presets, and project paths. The PRESET_DEPENDENCIES constant maps framework names to their required Vite plugins. The DEFAULT_VITE_CONFIG provides sensible defaults for testing.

Description

The browser runner configuration controls how Vite serves test files to the browser. It consists of three layers:

User configuration -- The BrowserRunnerOptions interface in wdio.conf.ts specifying preset, viteConfig, rootDir, and other options.
Preset resolution -- The PRESET_DEPENDENCIES constant that maps preset names to Vite plugin packages and their export names.
Default Vite config -- The DEFAULT_VITE_CONFIG that provides sensible defaults including CJS dependency optimization, source maps, and logging.

Source

File	Lines	Description
`packages/wdio-browser-runner/src/types.ts`	L75-125	`BrowserRunnerOptions` interface definition
`packages/wdio-browser-runner/src/vite/constants.ts`	L14-31	`PRESET_DEPENDENCIES` mapping framework presets to Vite plugins
`packages/wdio-browser-runner/src/vite/constants.ts`	L33-80	`DEFAULT_VITE_CONFIG` with optimized defaults
`packages/wdio-browser-runner/src/vite/frameworks/index.ts`	L7-26	`updateViteConfig` function for framework-specific optimizations
`packages/wdio-browser-runner/src/types.ts`	L13	`FrameworkPreset` type definition
`examples/wdio/vite-vue-example/wdio.conf.ts`	L1-300	Full example wdio.conf.ts with browser runner

Configuration Format

The browser runner is configured via the runner property in wdio.conf.ts:

runner: ['browser', BrowserRunnerOptions]

BrowserRunnerOptions Interface

// packages/wdio-browser-runner/src/types.ts
export interface BrowserRunnerOptions {
    rootDir?: string                    // Project root directory (default: process.cwd())
    preset?: FrameworkPreset            // Framework preset for auto-configuration
    viteConfig?: string | InlineConfig | ((env: ConfigEnv) => InlineConfig | Promise<InlineConfig>)
    headless?: boolean                  // Run in headless mode (default: false, true in CI)
    coverage?: CoverageOptions          // Test coverage settings
    automock?: boolean                  // Auto-mock dependencies in automockDir (default: true)
    automockDir?: string                // Path to auto-mock directory (default: ./__mocks__)
    host?: string                       // Custom hostname for remote grids (default: http://0.0.0.0)
}

I/O Contract:

Property	Type	Default	Description
`rootDir`	`string`	`process.cwd()`	Project root for file resolution
`preset`	`FrameworkPreset`	`undefined`	Auto-configures Vite plugin for framework
`viteConfig`	InlineConfig \| Function	`undefined`	Custom Vite configuration (merged with defaults)
`headless`	`boolean`	`false` (CI: `true`)	Headless browser mode
`coverage`	`CoverageOptions`	`undefined`	Istanbul coverage settings
`automock`	`boolean`	`true`	Auto-mock from `automockDir`
`automockDir`	`string`	`./__mocks__`	Directory for auto-mock files
`host`	`string`	`http://0.0.0.0`	Server hostname for remote grids

FrameworkPreset Type

// packages/wdio-browser-runner/src/types.ts
export type FrameworkPreset = 'react' | 'preact' | 'vue' | 'svelte' | 'lit' | 'solid' | 'stencil'

PRESET_DEPENDENCIES Mapping

// packages/wdio-browser-runner/src/vite/constants.ts
export const PRESET_DEPENDENCIES: Record<FrameworkPreset, [string, string, unknown] | undefined> = {
    react: ['@vitejs/plugin-react', 'default', {
        babel: {
            assumptions: { setPublicClassFields: true },
            parserOpts: { plugins: ['decorators-legacy', 'classProperties'] }
        }
    }],
    preact: ['@preact/preset-vite', 'default', undefined],
    vue: ['@vitejs/plugin-vue', 'default', undefined],
    svelte: ['@sveltejs/vite-plugin-svelte', 'svelte', undefined],
    solid: ['vite-plugin-solid', 'default', undefined],
    stencil: undefined,
    lit: undefined
}

Mapping structure: Each entry is a tuple [packageName, exportName, pluginOptions] or undefined (for frameworks that do not need a Vite plugin).

DEFAULT_VITE_CONFIG

// packages/wdio-browser-runner/src/vite/constants.ts
export const DEFAULT_VITE_CONFIG: Partial<InlineConfig> = {
    configFile: false,
    server: { host: 'localhost' },
    logLevel: 'info',
    plugins: [topLevelAwait()],
    build: {
        sourcemap: 'inline',
        commonjsOptions: { include: [/node_modules/] }
    },
    optimizeDeps: {
        include: [
            'expect', 'minimatch', 'css-shorthand-properties', 'lodash.merge',
            'lodash.zip', 'ws', 'lodash.clonedeep', 'lodash.pickby',
            'lodash.flattendeep', 'aria-query', 'grapheme-splitter',
            'css-value', 'rgb2hex', 'p-iteration', 'deepmerge-ts',
            'jest-util', 'jest-matcher-utils', 'split2'
        ],
        esbuildOptions: {
            logLevel: 'silent',
            define: { global: 'globalThis' },
            plugins: [
                esbuildCommonjs(['@testing-library/vue']),
                codeFrameFix()
            ]
        }
    }
}

Framework-Specific Optimizations

The updateViteConfig function in packages/wdio-browser-runner/src/vite/frameworks/index.ts auto-detects and applies optimizations for specific project types:

// packages/wdio-browser-runner/src/vite/frameworks/index.ts
export default async function updateViteConfig (
    options: WebdriverIO.BrowserRunnerOptions,
    config: WebdriverIO.Config
) {
    const optimizations: InlineConfig = {}
    const rootDir = options.rootDir || config.rootDir || process.cwd()

    if (await isNuxtFramework(rootDir)) {
        Object.assign(optimizations, await optimizeForNuxt(options, config))
    }
    if (await isUsingTailwindCSS(rootDir)) {
        Object.assign(optimizations, await optimizeForTailwindCSS(rootDir))
    }
    if (await isUsingStencilJS(rootDir, options)) {
        Object.assign(optimizations, await optimizeForStencil(rootDir))
    }

    return optimizations
}

Full Example: wdio.conf.ts for Vue Component Testing

// examples/wdio/vite-vue-example/wdio.conf.ts
import url from 'node:url'
import viteConfig from './vite.config.js'

const __dirname = url.fileURLToPath(new URL('.', import.meta.url))

export const config: WebdriverIO.Config = {
    runner: ['browser', {
        viteConfig,
        rootDir: __dirname
    }],
    specs: ['./src/**/*.test.ts'],
    maxInstances: 10,
    capabilities: [{
        maxInstances: 5,
        browserName: 'chrome'
    }],
    logLevel: 'info',
    bail: 0,
    baseUrl: '',
    waitforTimeout: 10000,
    connectionRetryTimeout: 120000,
    connectionRetryCount: 3,
    services: [],
    framework: 'mocha',
    reporters: ['spec'],
    mochaOpts: {
        ui: 'bdd',
        timeout: 60000
    }
}

Usage Examples

Minimal Vue setup

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    runner: ['browser', { preset: 'vue' }],
    specs: ['./src/**/*.test.ts'],
    capabilities: [{ browserName: 'chrome' }],
    framework: 'mocha'
}

React with coverage

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    runner: ['browser', {
        preset: 'react',
        coverage: {
            enabled: true,
            reportsDirectory: './coverage',
            reporter: ['text', 'html', 'json-summary'],
            lines: 80,
            functions: 80,
            branches: 80,
            statements: 80
        }
    }],
    specs: ['./src/**/*.test.tsx'],
    capabilities: [{ browserName: 'chrome' }],
    framework: 'mocha'
}

Svelte with headless mode

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    runner: ['browser', {
        preset: 'svelte',
        headless: true
    }],
    specs: ['./src/**/*.test.ts'],
    capabilities: [{ browserName: 'chrome' }],
    framework: 'mocha'
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment