Principle:Webdriverio Webdriverio Test Spec Authoring

Overview

A methodology for writing structured, behavior-driven test specifications using describe/it blocks and browser automation globals.

Metadata

Field	Value
Page Type	Principle
Repository	webdriverio/webdriverio
Knowledge Sources	Repo (GitHub), Doc (Frameworks), Doc (Mocha)
Domains	Testing, BDD
Related Implementations	Implementation: Mocha_BDD_Globals

Description

Test Spec Authoring in the WDIO testrunner uses BDD-style syntax (describe for suites, it for individual tests) combined with globally injected browser automation objects (browser, $, $$, expect). This approach structures tests around user behaviors and expected outcomes. The describe/it syntax comes from Mocha (or Jasmine), while the globals provide direct access to the automated browser session within each test worker.

Tests are written as .spec.ts or .spec.js files that are discovered via glob patterns defined in the configuration file's specs property. Each spec file is executed in an isolated worker process, ensuring test independence. The worker process receives a fully-initialized browser object connected to a real browser session, enabling direct DOM interaction, navigation, and assertion.

The BDD approach separates what the system should do from how the test infrastructure works. Test authors interact exclusively with high-level abstractions: browser.url() for navigation, $(selector) for element location, and expect(element).toBeDisplayed() for assertion. The framework, runner, and browser driver machinery are entirely hidden.

Usage

Use when writing test files (.spec.ts/.spec.js) for the WDIO testrunner with the Mocha or Jasmine framework. Each spec file contains describe blocks grouping related tests, with it blocks defining individual test cases that use browser/$/$$/expect for automation and assertion.

A typical spec file:

describe('Login Page', () => {
    beforeEach(async () => {
        await browser.url('/login')
    })

    it('should display the login form', async () => {
        const form = await $('#login-form')
        await expect(form).toBeDisplayed()
    })

    it('should login with valid credentials', async () => {
        await $('#username').setValue('testuser')
        await $('#password').setValue('password123')
        await $('button[type="submit"]').click()
        await expect(browser).toHaveUrl('/dashboard')
    })

    it('should show error for invalid credentials', async () => {
        await $('#username').setValue('invalid')
        await $('#password').setValue('wrong')
        await $('button[type="submit"]').click()
        const error = await $('.error-message')
        await expect(error).toHaveText('Invalid credentials')
    })
})

No imports are needed for describe, it, browser, $, $$, or expect -- they are all injected by the testrunner.

Theoretical Basis

BDD Structure

BDD (Behavior-Driven Development) structures tests as specifications of behavior: "describe X, it should Y." This creates a natural language hierarchy:

describe blocks define a subject (a component, page, or feature)
it blocks define an expected behavior of that subject
before/after hooks define setup and teardown at the suite or test level

Mocha's BDD interface provides: describe, it, specify, before, beforeEach, after, afterEach. Mocha also supports TDD (test, suite) and QUnit interfaces, configured via mochaOpts.ui.

Global Injection

The WDIO testrunner injects globals into each worker process's scope, making browser, $, $$, and expect available without explicit imports. This is accomplished through two mechanisms:

The @wdio/globals package exports proxy objects that delegate to a global Map (globalThis._wdioGlobals). Each proxy intercepts property access and forwards it to the real browser instance registered by the testrunner.
The MochaAdapter (@wdio/mocha-framework) wraps Mocha's test runner, hooks into its event system via the EVENTS mapping, and routes test lifecycle events (suite:start, test:pass, test:fail, etc.) back to WDIO reporters.

The proxy pattern allows the globals to be imported as static ESM exports while still being lazily bound to the actual browser session created at runtime. If accessed outside the testrunner context, the proxies throw a descriptive error.

Async/Await Model

All browser interactions in WDIO are asynchronous and return Promises. Spec authors use async/await syntax in every it block and hook. This reflects the underlying WebDriver protocol, which involves HTTP calls to the browser driver process.

Implemented by: Implementation: Mocha_BDD_Globals
Depends on: Principle: Test_Configuration_Parsing
Orchestrated by: Principle: Test_Execution_Orchestration

Page Connections

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

Principle

Implementation

Heuristic

Environment