0
# WebdriverIO Types
1

2
WebdriverIO Types is a comprehensive TypeScript type definition package that provides type safety and IntelliSense support for the entire WebdriverIO ecosystem. It includes type definitions for browser capabilities, test runner configuration, service extensions, framework integrations, reporter options, and worker communication, enabling type-safe development for browser automation and testing.
3

4
## Package Information
5

6
- **Package Name**: @wdio/types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @wdio/types`
10

11
## Core Imports
12

13
```typescript
14
import type { Automation, Capabilities, Options, Services, Frameworks, Reporters, Workers, Network } from "@wdio/types";
15
import { MESSAGE_TYPES } from "@wdio/types";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { MESSAGE_TYPES } = require("@wdio/types");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import type { Capabilities, Options } from "@wdio/types";
28

29
// Define WebDriver capabilities with type safety
30
const capabilities: Capabilities.W3CCapabilities = {
31
  alwaysMatch: {
32
    browserName: "chrome",
33
    "goog:chromeOptions": {
34
      args: ["--headless"]
35
    }
36
  },
37
  firstMatch: []
38
};
39

40
// Configure WebdriverIO options
41
const config: Options.Testrunner = {
42
  specs: ["./test/**/*.spec.ts"],
43
  capabilities: [capabilities],
44
  framework: "mocha",
45
  reporters: ["spec"]
46
};
47
```
48

49
## Architecture
50

51
WebdriverIO Types is organized around key WebdriverIO ecosystem components:
52

53
- **Capabilities Module**: Browser and device configuration types for WebDriver sessions
54
- **Options Module**: Configuration types for WebdriverIO client and test runner
55
- **Services Module**: Extension point types for WebdriverIO services and lifecycle hooks
56
- **Frameworks Module**: Test framework integration types (Mocha, Jasmine, Cucumber)
57
- **Reporters Module**: Test result reporting configuration types
58
- **Workers Module**: Test execution and inter-process communication types
59
- **Automation Module**: Generic driver interfaces for WebDriver implementations
60
- **Network Module**: Network request and cookie types for WebDriver Bidi
61

62
## Capabilities
63

64
### Browser Capabilities
65

66
WebDriver capabilities and browser-specific configuration options for Chrome, Firefox, Safari, Edge, and mobile devices.
67

68
```typescript { .api }
69
namespace Capabilities {
70
  interface W3CCapabilities {
71
    alwaysMatch?: WebdriverIO.Capabilities;
72
    firstMatch?: WebdriverIO.Capabilities[];
73
  }
74
  
75
  type RequestedStandaloneCapabilities = W3CCapabilities | WebdriverIO.Capabilities;
76
}
77
```
78

79
[Browser Capabilities](./capabilities.md)
80

81
### Configuration Options  
82

83
WebdriverIO client and test runner configuration including connection settings, logging, and test execution options.
84

85
```typescript { .api }
86
namespace Options {
87
  interface Testrunner extends Hooks, WebdriverIO {
88
    specs?: string[];
89
    exclude?: string[];
90
    suites?: Record<string, string[]>;
91
    capabilities: TestrunnerCapabilities;
92
    framework: string;
93
    reporters?: ReporterEntry[];
94
  }
95
}
96
```
97

98
[Configuration Options](./options.md)
99

100
### Services and Hooks
101

102
Service extension interfaces and comprehensive lifecycle hook definitions for extending WebdriverIO functionality.
103

104
```typescript { .api }
105
namespace Services {
106
  interface HookFunctions {
107
    onPrepare?(config: Options.Testrunner, capabilities: TestrunnerCapabilities): void | Promise<void>;
108
    onComplete?(exitCode: number, config: Options.Testrunner, capabilities: TestrunnerCapabilities): void | Promise<void>;
109
    before?(capabilities: WebdriverIO.Capabilities, specs: string[], browser: WebdriverIO.Browser): void | Promise<void>;
110
    after?(result: number, capabilities: WebdriverIO.Capabilities, specs: string[]): void | Promise<void>;
111
  }
112
}
113
```
114

115
[Services and Hooks](./services.md)
116

117
### Test Frameworks
118

119
Test framework integration types supporting Mocha, Jasmine, and Cucumber with test execution results and metadata.
120

121
```typescript { .api }
122
namespace Frameworks {
123
  interface Test extends Suite {
124
    fullName: string;
125
    fn?: Function;
126
    body?: string;
127
    async?: number;
128
    sync?: boolean;
129
  }
130
  
131
  interface TestResult {
132
    error?: any;
133
    result?: any;
134
    passed: boolean;
135
    duration: number;
136
    retries: TestRetries;
137
  }
138
}
139
```
140

141
[Test Frameworks](./frameworks.md)
142

143
### Reporters
144

145
Test result reporting configuration with output formatting and custom reporter support.
146

147
```typescript { .api }
148
namespace Reporters {
149
  interface Options {
150
    outputDir?: string;
151
    logFile?: string;
152
    outputFileFormat?: (options: OutputFileFormatOptions) => string;
153
    stdout?: boolean;
154
  }
155
  
156
  type ReporterEntry = string | ReporterClass | [string, WebdriverIO.ReporterOption] | [ReporterClass, WebdriverIO.ReporterOption];
157
}
158
```
159

160
[Reporters](./reporters.md)
161

162
### Workers and Messaging
163

164
Worker process management and inter-process communication for test execution in parallel environments.
165

166
```typescript { .api }
167
namespace Workers {
168
  interface Worker extends EventEmitter {
169
    capabilities: WebdriverIO.Capabilities;
170
    config: Options.Testrunner;
171
    cid: string;
172
    postMessage: (command: string, args: WorkerMessageArgs) => void;
173
  }
174
  
175
  enum MESSAGE_TYPES {
176
    consoleMessage = 0,
177
    commandRequestMessage,
178
    commandResponseMessage
179
  }
180
}
181
```
182

183
[Workers and Messaging](./workers.md)
184

185
### Automation Drivers
186

187
Generic driver interfaces for WebDriver implementations and session management.
188

189
```typescript { .api }
190
namespace Automation {
191
  interface Driver<T> {
192
    newSession(options: T, modifier?: (...args: unknown[]) => unknown, userPrototype?: Record<string, unknown>, customCommandWrapper?: (...args: unknown[]) => unknown): unknown;
193
    attachToSession(options: unknown, modifier?: (...args: unknown[]) => unknown, userPrototype?: Record<string, unknown>, customCommandWrapper?: (...args: unknown[]) => unknown): unknown;
194
    reloadSession(client: unknown, newCapabilities: WebdriverIO.Capabilities): unknown;
195
  }
196
}
197
```
198

199
### Network Requests
200

201
Network request and cookie types for WebDriver Bidi protocol.
202

203
```typescript { .api }
204
namespace Network {
205
  interface Request {
206
    id?: string;
207
    url: string;
208
    timestamp: number;
209
    navigation?: string;
210
    redirectChain?: string[];
211
    headers: Record<string, string>;
212
    cookies?: NetworkCookie[];
213
    error?: string;
214
    response?: {
215
      fromCache: boolean;
216
      headers: Record<string, string>;
217
      mimeType: string;
218
      status: number;
219
    };
220
    children?: Request[];
221
  }
222
  
223
  interface NetworkCookie {
224
    name: string;
225
    value: string;
226
    domain: string;
227
    path: string;
228
    size: number;
229
    httpOnly: boolean;
230
    secure: boolean;
231
    sameSite: 'strict' | 'lax' | 'none';
232
    expiry?: number;
233
  }
234
}
235
```
236

237
## Utility Types
238

239
Core utility types for JSON serialization, function property extraction, and Promise resolution:
240

241
```typescript { .api }
242
type JsonPrimitive = string | number | boolean | null;
243
type JsonObject = { [x: string]: JsonPrimitive | JsonObject | JsonArray };
244
type JsonArray = Array<JsonPrimitive | JsonObject | JsonArray>;
245
type JsonCompatible = JsonObject | JsonArray;
246

247
type FunctionPropertyNames<T> = { [K in keyof T]: T[K] extends Function ? K : never }[keyof T];
248
type FunctionProperties<T> = Pick<T, FunctionPropertyNames<T>>;
249
type ThenArg<T> = T extends PromiseLike<infer U> ? U : T;
250
```
251

252
## Global Namespace Extensions
253

254
The package extends the global `WebdriverIO` namespace, allowing ecosystem packages to augment interfaces:
255

256
```typescript { .api }
257
declare global {
258
  namespace WebdriverIO {
259
    interface ServiceOption extends Services.ServiceOption {}
260
    interface ReporterOption extends Reporters.Options {}
261
    interface Browser {
262
      requestedCapabilities?: any;
263
    }
264
    interface MultiRemoteBrowser {}
265
    interface Element {
266
      parent: WebdriverIO.Element | WebdriverIO.Browser;
267
    }
268
    interface MultiRemoteElement {}
269
    interface ElementArray {}
270
    interface Request extends Network.Request {}
271
    interface MochaOpts { [key: string]: any }
272
    interface JasmineOpts { [key: string]: any }
273
    interface CucumberOpts { [key: string]: any }
274
    interface Config extends Options.Testrunner, Capabilities.WithRequestedTestrunnerCapabilities {}
275
    interface RemoteConfig extends Options.WebdriverIO, Capabilities.WithRequestedCapabilities {}
276
    interface MultiremoteConfig extends Options.Testrunner, Capabilities.WithRequestedMultiremoteCapabilities {}
277
    interface HookFunctionExtension {}
278
    interface WDIOVSCodeServiceOptions {}
279
    interface BrowserRunnerOptions {}
280
    interface ChromedriverOptions {}
281
    interface GeckodriverOptions {}
282
    interface EdgedriverOptions {}
283
    interface SafaridriverOptions {}
284
  }
285
}
286
```