0
# Services and Hooks
1

2
Service extension interfaces and comprehensive lifecycle hook definitions for extending WebdriverIO functionality with custom behaviors and integrations.
3

4
## Capabilities
5

6
### Service Definition
7

8
Service class and plugin interfaces for extending WebdriverIO functionality.
9

10
```typescript { .api }
11
/**
12
 * Service options interface - extended by individual services
13
 */
14
interface ServiceOption {
15
  [key: string]: any;
16
}
17

18
/**
19
 * Service class constructor
20
 */
21
interface ServiceClass {
22
  new(
23
    options: WebdriverIO.ServiceOption,
24
    capabilities: ResolvedTestrunnerCapabilities,
25
    config: WebdriverIOOptions
26
  ): ServiceInstance;
27
}
28

29
/**
30
 * Service plugin with optional launcher
31
 */
32
interface ServicePlugin extends ServiceClass {
33
  /** Default service class */
34
  default: ServiceClass;
35
  /** Optional launcher service */
36
  launcher?: ServiceClass;
37
}
38

39
/**
40
 * Service instance interface
41
 */
42
interface ServiceInstance extends HookFunctions {
43
  /** Service configuration options */
44
  options?: Record<string, any>;
45
  /** Associated capabilities */
46
  capabilities?: WebdriverIO.Capabilities;
47
  /** WebdriverIO configuration */
48
  config?: TestrunnerOptions;
49
}
50
```
51

52
### Service Entry Types
53

54
Different ways to configure services in WebdriverIO.
55

56
```typescript { .api }
57
/**
58
 * Service configuration options
59
 */
60
type ServiceEntry = 
61
  /** Service name as string */
62
  | string
63
  /** Service as hook functions object */
64
  | HookFunctions
65
  /** Service class */
66
  | ServiceClass
67
  /** Service name with options */
68
  | [string, WebdriverIO.ServiceOption]
69
  /** Service class with options */
70
  | [ServiceClass, WebdriverIO.ServiceOption];
71
```
72

73
### Hook Functions
74

75
Comprehensive lifecycle hook definitions for WebdriverIO test execution.
76

77
```typescript { .api }
78
/**
79
 * Complete hook function interface
80
 */
81
interface HookFunctions {
82
  /**
83
   * Executed before a test run starts. Has access to all config options and capabilities.
84
   */
85
  onPrepare?(
86
    config: Options.Testrunner,
87
    capabilities: TestrunnerCapabilities
88
  ): void | Promise<void>;
89

90
  /**
91
   * Executed after all tests are completed. Has access to exit code and config.
92
   */
93
  onComplete?(
94
    exitCode: number,
95
    config: Options.Testrunner,
96
    capabilities: TestrunnerCapabilities,
97
    results: Results
98
  ): void | Promise<void>;
99

100
  /**
101
   * Executed when a worker process starts.
102
   */
103
  onWorkerStart?(
104
    cid: string,
105
    caps: WebdriverIO.Capabilities,
106
    specs: string[],
107
    args: WorkerMessageArgs,
108
    execArgv: string[]
109
  ): void | Promise<void>;
110

111
  /**
112
   * Executed when a worker process ends.
113
   */
114
  onWorkerEnd?(
115
    cid: string,
116
    exitCode: number,
117
    specs: string[],
118
    retries: number
119
  ): void | Promise<void>;
120

121
  /**
122
   * Executed before a WebDriver session starts.
123
   */
124
  before?(
125
    capabilities: WebdriverIO.Capabilities,
126
    specs: string[],
127
    browser: WebdriverIO.Browser
128
  ): void | Promise<void>;
129

130
  /**
131
   * Executed after a WebDriver session ends.
132
   */
133
  after?(
134
    result: number,
135
    capabilities: WebdriverIO.Capabilities,
136
    specs: string[]
137
  ): void | Promise<void>;
138

139
  /**
140
   * Executed before session starts (WebDriver level).
141
   */
142
  beforeSession?(
143
    config: Options.Testrunner,
144
    capabilities: WebdriverIO.Capabilities,
145
    specs: string[],
146
    cid: string
147
  ): void | Promise<void>;
148

149
  /**
150
   * Executed after session ends (WebDriver level).
151
   */
152
  afterSession?(
153
    config: Options.Testrunner,
154
    capabilities: WebdriverIO.Capabilities,
155
    specs: string[]
156
  ): void | Promise<void>;
157

158
  /**
159
   * Executed when a session is reloaded.
160
   */
161
  onReload?(
162
    oldSessionId: string,
163
    newSessionId: string
164
  ): void | Promise<void>;
165

166
  /**
167
   * Executed before a test suite starts.
168
   */
169
  beforeSuite?(suite: Suite): void | Promise<void>;
170

171
  /**
172
   * Executed after a test suite ends.
173
   */
174
  afterSuite?(suite: Suite): void | Promise<void>;
175

176
  /**
177
   * Executed before a test starts.
178
   */
179
  beforeTest?(
180
    test: Test,
181
    context: any
182
  ): void | Promise<void>;
183

184
  /**
185
   * Executed after a test ends.
186
   */
187
  afterTest?(
188
    test: Test,
189
    context: any,
190
    result: TestResult
191
  ): void | Promise<void>;
192

193
  /**
194
   * Executed before a hook starts.
195
   */
196
  beforeHook?(
197
    test: Test,
198
    context: any,
199
    stepData?: any,
200
    world?: World
201
  ): void | Promise<void>;
202

203
  /**
204
   * Executed after a hook ends.
205
   */
206
  afterHook?(
207
    test: Test,
208
    context: any,
209
    result: TestResult,
210
    stepData?: any,
211
    world?: World
212
  ): void | Promise<void>;
213

214
  /**
215
   * Executed before a WebDriver command.
216
   */
217
  beforeCommand?(
218
    commandName: string,
219
    args: any[]
220
  ): void | Promise<void>;
221

222
  /**
223
   * Executed after a WebDriver command.
224
   */
225
  afterCommand?(
226
    commandName: string,
227
    args: any[],
228
    result: any,
229
    error?: Error
230
  ): void | Promise<void>;
231

232
  /**
233
   * Executed before an assertion/expectation.
234
   */
235
  beforeAssertion?(params: AssertionHookParams): void | Promise<void>;
236

237
  /**
238
   * Executed after an assertion/expectation.
239
   */
240
  afterAssertion?(params: AfterAssertionHookParams): void | Promise<void>;
241
}
242
```
243

244
### Assertion Hook Parameters
245

246
Parameters passed to assertion-related hooks.
247

248
```typescript { .api }
249
/**
250
 * Parameters for assertion hooks
251
 */
252
interface AssertionHookParams {
253
  /** Name of the matcher (e.g., 'toHaveText', 'toBeClickable') */
254
  matcherName: string;
255
  /** Value passed by user to the matcher */
256
  expectedValue?: any;
257
  /** Options passed to the matcher */
258
  options: object;
259
}
260

261
/**
262
 * Parameters for after assertion hooks
263
 */
264
interface AfterAssertionHookParams extends AssertionHookParams {
265
  /** Assertion result */
266
  result: {
267
    /** Function returning the assertion message */
268
    message: () => string;
269
    /** Boolean result of the assertion */
270
    result: boolean;
271
  };
272
}
273
```
274

275
### Hook Type Helpers
276

277
Type definitions for hook function arrays and single values.
278

279
```typescript { .api }
280
/**
281
 * Hook functions supporting single or array values
282
 */
283
type Hooks = {
284
  [K in keyof HookFunctions]: HookFunctions[K] | HookFunctions[K][];
285
};
286
```
287

288
### Runner Interface
289

290
Test runner instance and class interfaces.
291

292
```typescript { .api }
293
/**
294
 * Test runner instance
295
 */
296
interface RunnerInstance {
297
  /** Initialize the runner */
298
  initialize(): Promise<void>;
299
  /** Shutdown the runner */
300
  shutdown(): Promise<boolean>;
301
  /** Close a specific session */
302
  closeSession?(cid: number): Promise<void>;
303
  /** Get worker count */
304
  getWorkerCount(): number;
305
  /** Run tests */
306
  run(args: any): Worker;
307
  /** Worker pool */
308
  workerPool: any;
309
  /** Browser pool */
310
  browserPool: any;
311
}
312

313
/**
314
 * Test runner class constructor
315
 */
316
interface RunnerClass {
317
  new(
318
    options: WebdriverIO.BrowserRunnerOptions,
319
    config: Omit<WebdriverIOOptions, 'capabilities' | keyof Hooks>
320
  ): RunnerInstance;
321
}
322

323
/**
324
 * Runner plugin with launcher support
325
 */
326
interface RunnerPlugin extends RunnerClass {
327
  /** Default runner class */
328
  default: RunnerClass;
329
  /** Optional launcher class */
330
  launcher?: RunnerClass;
331
}
332
```
333

334
**Usage Examples:**
335

336
```typescript
337
import type { Services } from "@wdio/types";
338

339
// Custom service implementation
340
class CustomService implements Services.ServiceInstance {
341
  constructor(
342
    private options: Services.ServiceOption,
343
    private capabilities: any,
344
    private config: any
345
  ) {}
346

347
  async onPrepare(config: any, capabilities: any) {
348
    console.log('Setting up custom service...');
349
    // Custom setup logic
350
  }
351

352
  async before(capabilities: any, specs: string[], browser: any) {
353
    console.log('Starting test session...');
354
    // Session initialization
355
  }
356

357
  async beforeTest(test: any, context: any) {
358
    console.log(`Starting test: ${test.title}`);
359
    // Pre-test setup
360
  }
361

362
  async afterTest(test: any, context: any, result: any) {
363
    console.log(`Test completed: ${test.title}, passed: ${result.passed}`);
364
    // Post-test cleanup
365
  }
366

367
  async after(result: number, capabilities: any, specs: string[]) {
368
    console.log('Ending test session...');
369
    // Session cleanup
370
  }
371

372
  async onComplete(exitCode: number, config: any, capabilities: any) {
373
    console.log('Custom service cleanup complete');
374
    // Final cleanup
375
  }
376
}
377

378
// Service configuration
379
const services: Services.ServiceEntry[] = [
380
  'chromedriver',
381
  ['@wdio/selenium-standalone-service', { installArgs: { drivers: { chrome: true } } }],
382
  [CustomService, { customOption: true }],
383
  {
384
    beforeTest: (test, context) => {
385
      console.log(`Running test: ${test.title}`);
386
    },
387
    afterTest: (test, context, result) => {
388
      if (!result.passed) {
389
        console.log(`Test failed: ${test.title}`);
390
      }
391
    }
392
  }
393
];
394
```