Principle:Webdriverio Webdriverio Browser Runner Configuration

Metadata

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

Overview

A mechanism for configuring in-browser test execution using a Vite-based development server with framework-specific presets. Browser Runner Configuration sets up the WDIO browser runner, which serves test files directly to a real browser via Vite, enabling component testing with native ESM support, fast hot module replacement, and framework-aware compilation.

Description

Browser Runner Configuration sets up the WDIO browser runner, which uses Vite as a development server to serve test files directly to a real browser. Configuration involves selecting a framework preset (react, vue, svelte, etc.), providing custom Vite configuration, and specifying the project root directory. The runner auto-detects and configures framework-specific Vite plugins based on the selected preset.

The configuration is specified as the runner property in wdio.conf.ts, using the tuple format ['browser', options]. The options object accepts:

• preset -- A framework preset string that maps to a Vite plugin. For example, 'vue' maps to @vitejs/plugin-vue, 'react' maps to @vitejs/plugin-react.
• viteConfig -- Custom Vite configuration that merges with the defaults. Can be an inline config object, a path to a config file, or an async function.
• rootDir -- The project root directory for resolving test files and dependencies.
• headless -- Whether to run the browser in headless mode (defaults to true in CI environments).
• coverage -- Test coverage configuration using vite-plugin-istanbul.
• automock -- Whether to automatically mock dependencies found in the automockDir directory.

The browser runner fundamentally changes the test execution model: instead of tests running in Node.js and sending commands to a remote browser via WebDriver protocol, tests run directly inside the browser with Vite providing module resolution, transpilation, and hot module replacement.

Usage

Use Browser Runner Configuration when setting up component testing in a WebdriverIO project. The configuration tells WDIO to use the browser runner instead of the default local runner, and specifies how Vite should serve the test files.

When to apply:

• Setting up a new component testing project.
• Migrating from a jsdom-based testing setup to real browser testing.
• Testing framework-specific components (Vue, React, Svelte, etc.) in isolation.
• When you need fast feedback cycles with HMR during test development.

When to avoid:

• For E2E tests that navigate to full application URLs (use the default local runner).
• When testing Node.js-only code that does not involve browser rendering.

Minimal configuration example:

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

Configuration with custom Vite config:

// wdio.conf.ts
import viteConfig from './vite.config.js'

export const config: WebdriverIO.Config = {
    runner: ['browser', {
        viteConfig,
        rootDir: __dirname
    }],
    specs: ['./src/**/*.test.ts'],
    capabilities: [{ browserName: 'chrome' }],
    framework: 'mocha'
}

Theoretical Basis

The browser runner inverts the traditional WDIO execution model:

Aspect	Traditional (Local Runner)	Browser Runner
Test execution	Tests run in Node.js	Tests run in the browser
Browser control	WebDriver protocol commands	Direct DOM access
Module resolution	Node.js require/import	Vite ESM dev server
HMR support	None	Full Vite HMR
Framework support	N/A (E2E only)	React, Vue, Svelte, Lit, Solid, Preact, Stencil

Vite integration:

Vite serves as the development server for the browser runner. It provides:

• Native ESM -- Test files and component dependencies are served as ES modules, avoiding bundling overhead.
• Fast rebuilds -- Vite's HMR enables sub-second rebuilds when test files change.
• Plugin system -- Framework presets map to Vite plugins that handle framework-specific compilation (e.g., SFC compilation for Vue, JSX transformation for React).
• Dependency optimization -- CJS packages are pre-bundled by Vite's optimizeDeps system into ESM format.

Framework presets:

The PRESET_DEPENDENCIES constant maps framework names to their required Vite plugins:

Preset	Vite Plugin	Export
'react'	@vitejs/plugin-react	default
'preact'	@preact/preset-vite	default
'vue'	@vitejs/plugin-vue	default
'svelte'	@sveltejs/vite-plugin-svelte	svelte
'solid'	vite-plugin-solid	default
'stencil'	Custom integration	N/A
'lit'	No plugin needed	N/A

The runner also auto-detects and optimizes for Nuxt, TailwindCSS, and StencilJS projects by applying additional Vite configuration adjustments through the updateViteConfig function in packages/wdio-browser-runner/src/vite/frameworks/index.ts.

Related Pages

Implementation:Webdriverio_Webdriverio_Browser_Runner_Config

• implemented_by Implementation: Browser_Runner_Config