@wdio/browser-runner

WebdriverIO Browser Runner

A WebdriverIO runner to run unit and component tests within the browser.

As opposed to the Local Runner the Browser Runner initiates and executes the framework within the browser. This allows you to run unit tests or component tests in an actual browser rather than in a JSDOM like many other test frameworks.

While JSDOM is widely used for testing purposes, it is in the end not an actual browser nor can you emulate mobile environments with it. With this runner WebdriverIO enables you to easily run your tests in the browser and use WebDriver commands to interact with elements rendered on the page.

Here is an overview of running tests within JSDOM vs. WebdriverIOs Browser Runner

	JSDOM	WebdriverIO Browser Runner
1.	Runs your tests within Node.js using a re-implementation of web standards, notably the WHATWG DOM and HTML Standards	Executes your test in an actual browser and runs the code in an environment that your users use
2.	Interactions with components can only be imitated via JavaScript	You can use the WebdriverIO API to interact with elements through the WebDriver protocol
3.	Canvas support requires additional dependencies and has limitations	You have access to the real Canvas API
4.	JSDOM has some caveats and unsupported Web APIs	All Web APIs are supported as test run in an actual browser
5.	Impossible to detect errors cross browser	Support for all browsers including mobile browser
6.	Can not test for element pseudo states	Support for pseudo states such as :hover or :active

This runner uses Vite to compile your test code and load it in the browser. It comes with presets for the following component frameworks:

• React
• Preact
• Vue.js
• Svelte
• SolidJS

Every test file / test file group runs within a single page which means that between each test the page is being reloaded to guarantee isolation between tests.

Install

To use the Browser Runner you can install it via:

npm install --save-dev @wdio/browser-runner

Setup

To use the Browser runner, you have to define a runner property within your wdio.conf.js file, e.g.:

// wdio.conf.js
export const {
    // ...
    runner: 'browser',
    // ...
}

Runner Options

The Browser runner allows following configurations:

preset

If you test components using one of the mentioned frameworks above, you can define a preset that ensures everything is configured out of the box. This option can't be used together with viteConfig.

Type: vue | svelte | solid | react | preact | stencil
Example:

export const {
    // ...
    runner: ['browser', {
        preset: 'svelte'
    }],
    // ...
}

viteConfig

Define your own Vite configuration. You can either pass in a custom object or import an existing vite.conf.ts file if you use Vite.js for development. Note that WebdriverIO merges custom configurations to set up framework and runner objects. This option can't be used together with preset.

Type: UserConfig
Example:

import viteConfig from '../vite.config.ts'

export const {
    // ...
    runner: ['browser', { viteConfig }],
    // ...
}

headless

If set to true the runner will update capabilities to run tests headless. By default this is enabled within CI environments where a CI environment variable is set to '1' or 'true'.

Type: boolean
Default: false, set to true if CI environment variable is set

rootDir

Project root directory.

Type: string
Default: process.cwd()

coverage

WebdriverIO supports test coverage reporting through istanbul. See Coverage Options for more details.

Type: object
Default: undefined

Coverage Options

The following options allow to configure coverage reporting.

enabled

Enables coverage collection.

Type: boolean
Default: false

include

List of files included in coverage as glob patterns.

Type: string[]
Default: [**]

exclude

List of files excluded in coverage as glob patterns.

Type: string[]
Default:

[
  'coverage/**',
  'dist/**',
  'packages/*/test{,s}/**',
  '**/*.d.ts',
  'cypress/**',
  'test{,s}/**',
  'test{,-*}.{js,cjs,mjs,ts,tsx,jsx}',
  '**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx}',
  '**/*{.,-}spec.{js,cjs,mjs,ts,tsx,jsx}',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*',
  '**/.{eslint,mocha,prettier}rc.{js,cjs,yml}',
]

extension

List of file extensions the report should include.

Type: string | string[]
Default: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.vue', '.svelte']

reportsDirectory

Directory to write coverage report to.

Type: string
Default: ./coverage

reporter

Coverage reporters to use. See istanbul documentation for detailed list of all reporters.

Type: string[]
Default: ['text', 'html', 'clover', 'json-summary']

perFile

Check thresholds per file. See lines, functions, branches and statements for the actual thresholds.

Type: boolean
Default: false

clean

Clean coverage results before running tests.

Type: boolean
Default: true

lines

Threshold for lines.

Type: number
Default: undefined

functions

Threshold for functions.

Type: number
Default: undefined

branches

Threshold for branches.

Type: number
Default: undefined

statements

Threshold for statements.

Type: number
Default: undefined

Examples

Make sure to check out the docs around component testing and have a look into the example repository for examples using these and various other frameworks.

---

For more information on WebdriverIO runner, check out the documentation.

Changelog

v9.4.2 (2024-12-12)

:bug: Bug Fix

• wdio-cli
  • #13963 Remove unused cli-spinners dependency (@alexparish)
  • #13944 fix(@wdio/cli): use require to import json file (@christian-bromann)
  • #13932 fix(@wdio/cli): ensure onComplete hooks is executed (@christian-bromann)
• wdio-utils, webdriverio
  • #13960 fix(webdriverio): support opening file urls (@christian-bromann)
• wdio-utils
  • #13949 fix(@wdio/utils): properly detect Appium browser sessions (@christian-bromann)
• wdio-runner
  • #13958 fix(@wdio/runner): Continue emitting event on the runner even when a reporter throws an error (@dprevost-LMI)
• webdriverio
  • #13941 fix(webdriverio): add 'appium:options' when checking for native context (@ricardorlg)
• wdio-allure-reporter, webdriver
  • #13922 fix: Catch requests failure to trigger the result and onAfterCommand event (@dprevost-LMI)

:nail_care: Polish

• wdio-cli
  • #13970 fix(@wdio/cli): Serenity/JS supports WebdriverIO 9 (@jan-molak)
• wdio-utils, webdriverio
  • #13950 fix(webdriverio): don't fail if getContext is not supported (@christian-bromann)
• wdio-browserstack-service, wdio-types
  • #13951 Changes to send SDK instrumentation in capabilities v9 (@jainam-bs)

:memo: Documentation

• #13965 Update Emulation.md - device emulation (@jochen-testingbot)

Committers: 7

• Alex Parish (@alexparish)
• Christian Bromann (@christian-bromann)
• David Prevost (@dprevost-LMI)
• Jainam Shah (@jainam-bs)
• Jan Molak (@jan-molak)
• Jochen (@jochen-testingbot)
• ricardo larrahondo (@ricardorlg)