Implementation:Webdriverio Webdriverio TestInterfaceWrapper

Knowledge Sources	Webdriverio_Webdriverio
Domains	Test_Framework_Integration, Hook_Management
Last Updated	2026-02-12 00:00 GMT

Overview

Wraps Mocha and Jasmine test interface functions (it, beforeEach, etc.) with WebdriverIO before/after lifecycle hooks.

Description

The TestInterfaceWrapper module provides the bridge between test framework globals and the WebdriverIO hook system. wrapGlobalTestMethod replaces a global function (e.g., it, beforeEach) on the specified scope with a wrapped version that injects WebdriverIO lifecycle hooks around each test or hook execution. It delegates to wrapTestFunction which parses variadic arguments (handling Mocha's [title, fn] and Jasmine's [title, fn, timeout] signatures) and routes to either runSpec (for test functions) or runHook (for before/after hooks). Both runSpec and runHook call testFnWrapper from the testFnWrapper module, passing the spec/hook function along with before and after hook functions and their argument generators. The module also preserves Mocha's .skip and .only modifiers via addMochaCommands. This module is not used by the Cucumber framework, which calls testFnWrapper directly.

Usage

Use wrapGlobalTestMethod during framework adapter initialization to instrument test interface functions with WebdriverIO hooks. This is called by the Mocha and Jasmine framework adapters to ensure that beforeTest, afterTest, beforeHook, and afterHook lifecycle events fire around every test and hook execution.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-utils/src/test-framework/testInterfaceWrapper.ts
Lines: 1-302

Signature

export const runHook: (
    this: unknown,
    hookFn: Function,
    origFn: Function,
    beforeFn: Function | Function[],
    beforeFnArgs: HookFnArgs<unknown>,
    afterFn: Function | Function[],
    afterFnArgs: HookFnArgs<unknown>,
    cid: string,
    repeatTest: number,
    timeout: number
) => any

export const runSpec: (
    this: unknown,
    specTitle: string,
    specFn: Function,
    origFn: Function,
    beforeFn: Function | Function[],
    beforeFnArgs: HookFnArgs<unknown>,
    afterFn: Function | Function[],
    afterFnArgs: HookFnArgs<unknown>,
    cid: string,
    repeatTest: number,
    timeout: number
) => any

export const wrapTestFunction: (
    this: unknown,
    origFn: Function,
    isSpec: boolean,
    beforeFn: Function | Function[],
    beforeArgsFn: HookFnArgs<unknown>,
    afterFn: Function | Function[],
    afterArgsFn: HookFnArgs<unknown>,
    cid: string
) => (...specArguments: SpecArguments) => any

export const wrapGlobalTestMethod: (
    this: unknown,
    isSpec: boolean,
    beforeFn: Function | Function[],
    beforeArgsFn: HookFnArgs<unknown>,
    afterFn: Function | Function[],
    afterArgsFn: HookFnArgs<unknown>,
    fnName: string,
    cid: string,
    scope?: typeof globalThis
) => void

Import

import { wrapGlobalTestMethod } from '@wdio/utils/test-framework/testInterfaceWrapper'

I/O Contract

Inputs

Name	Type	Required	Description
isSpec	boolean	Yes	True if wrapping a spec function (it/test), false for hooks (beforeEach, afterAll, etc.).
beforeFn	Function or Function[]	Yes	WebdriverIO before hook(s) to run before each test/hook (e.g., beforeTest, beforeHook).
beforeArgsFn	HookFnArgs<unknown>	Yes	Function that generates arguments for the before hook, receiving the test context.
afterFn	Function or Function[]	Yes	WebdriverIO after hook(s) to run after each test/hook.
afterArgsFn	HookFnArgs<unknown>	Yes	Function that generates arguments for the after hook, receiving test context; result/error/duration are appended.
fnName	string	Yes (wrapGlobalTestMethod)	Name of the global function to wrap (e.g., "it", "beforeEach", "describe").
cid	string	Yes	The capability ID identifying the worker process.
scope	typeof globalThis	No	The object on which the global function lives; defaults to globalThis.

Outputs

Name	Type	Description
wrapGlobalTestMethod	void	Mutates the global scope by replacing the named function with a wrapped version. No return value.
wrapTestFunction	Function	Returns a new function that can be assigned to global scope, handling argument parsing and hook delegation.
runSpec / runHook	any	Returns the result of calling the original framework function with the wrapped spec/hook function.

Usage Examples

import { wrapGlobalTestMethod } from '@wdio/utils/test-framework/testInterfaceWrapper'

// In a Mocha framework adapter
const cid = '0-0'

// Wrap 'it' to inject beforeTest/afterTest hooks
wrapGlobalTestMethod(
    true,                              // isSpec
    config.beforeTest,                 // beforeFn
    (context) => [context.test, context], // beforeFnArgs
    config.afterTest,                  // afterFn
    (context) => [context.test, context], // afterFnArgs
    'it',                              // fnName
    cid                                // capability id
)

// Wrap 'beforeEach' to inject beforeHook/afterHook hooks
wrapGlobalTestMethod(
    false,                             // isSpec (this is a hook)
    config.beforeHook,                 // beforeFn
    (context) => [context.test, context], // beforeFnArgs
    config.afterHook,                  // afterFn
    (context) => [context.test, context], // afterFnArgs
    'beforeEach',                      // fnName
    cid                                // capability id
)

// it.skip and it.only are automatically preserved
it.skip('skipped test', () => { /* ... */ })
it.only('focused test', () => { /* ... */ })

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment