Workflow:Webdriverio Webdriverio WDIO Testrunner Setup
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, E2E_Testing, Test_Runner |
| Last Updated | 2026-02-12 01:30 GMT |
Overview
End-to-end process for setting up and running browser-based end-to-end tests using the WebdriverIO testrunner with the Mocha framework.
Description
This workflow covers the standard way to use WebdriverIO for structured test suites. The WDIO testrunner is a CLI-based orchestrator that reads a configuration file (wdio.conf.ts), launches browser sessions, distributes test specs across parallel workers, and reports results. It integrates with test frameworks like Mocha to provide describe/it blocks, supports lifecycle hooks at multiple levels (suite, test, command), and enables extensibility through services and reporters. This is the primary "Golden Path" for most WebdriverIO users.
Usage
Execute this workflow when setting up a new end-to-end test suite or adding WebdriverIO to an existing project. This is the recommended approach for teams running structured test suites with assertions, parallel execution, reporting, and CI/CD integration.
Execution Steps
Step 1: Initialize Project
Create a new Node.js project or navigate to an existing one. Run the WebdriverIO configuration wizard using npm init wdio@latest or npx create-wdio@latest. The wizard interactively guides through framework selection (Mocha, Jasmine, Cucumber), runner type, reporter selection, and service installation.
Key considerations:
- The wizard generates a wdio.conf.ts (or .js) configuration file
- It installs all required dependencies automatically
- Alternatively, install packages manually: @wdio/cli, @wdio/local-runner, @wdio/mocha-framework, @wdio/spec-reporter
Step 2: Configure Test Suite
Edit the generated wdio.conf.ts file to define test specs, browser capabilities, framework options, and service integrations. The configuration file controls every aspect of test execution including parallelism, timeouts, base URL, and lifecycle hooks.
Key considerations:
- specs array defines glob patterns for test file locations
- capabilities array defines which browsers to test against, each running in parallel
- framework selects the test framework (mocha, jasmine, or cucumber)
- reporters configures output formats (spec, dot, junit, allure)
- services enables integrations (appium, browserstack, sauce)
- Hooks like onPrepare, before, beforeTest, afterTest, after, onComplete provide lifecycle control
Step 3: Write Test Specs
Create test files using Mocha's describe/it syntax with WebdriverIO's global browser object and expect assertions from @wdio/globals. Each test file receives its own browser session. Tests use $() and $$() to find elements and interact with the page.
Key considerations:
- Import browser, $, $$, and expect from @wdio/globals
- The browser object is preconfigured and session-managed by the testrunner
- Use expect-webdriverio matchers like toHaveTitle(), toBeDisplayed(), toHaveText()
- Tests are async by default; all commands must be awaited
Step 4: Run Tests
Execute the test suite using the npx wdio run wdio.conf.ts command (or just npx wdio). The CLI reads the configuration, starts browser drivers, spawns worker processes for each capability, and runs the test specs. Results are streamed to configured reporters.
Key considerations:
- Workers run in parallel across capabilities by default
- Use --spec flag to run a specific test file
- Use --suite flag to run a named suite
- The maxInstances config option limits parallelism
- Exit code indicates pass (0) or failure (non-zero) for CI integration
Step 5: Review Results
After test execution, review results from configured reporters. The spec reporter outputs a hierarchical pass/fail summary to the terminal. JUnit reporter generates XML files for CI systems. Allure reporter creates interactive HTML reports. Failed tests include error messages, stack traces, and optionally screenshots.
Key considerations:
- spec reporter provides immediate terminal output
- junit reporter generates XML compatible with Jenkins and other CI tools
- allure reporter creates detailed HTML reports with screenshots and steps
- Failed commands are logged with full request/response details