0
# Event System
1

2
The WDIO Reporter provides a comprehensive event system based on EventEmitter that captures all aspects of test execution. The system includes event interfaces and types that define the structure of data passed through the reporter event system.
3

4
## Capabilities
5

6
### Command Event Interfaces
7

8
Interfaces for WebDriver command execution events that capture command details, parameters, and results.
9

10
```typescript { .api }
11
/**
12
 * Base interface for WebDriver command arguments
13
 * Contains common properties for all command events
14
 */
15
interface CommandArgs {
16
  sessionId: string;
17
  method?: string;
18
  endpoint?: string;
19
  
20
  // DevTools specific properties
21
  retries?: number;
22
  command?: string;
23
  params?: unknown;
24
}
25

26
/**
27
 * Arguments passed before WebDriver command execution
28
 * Extends CommandArgs with request body information
29
 */
30
interface BeforeCommandArgs extends CommandArgs {
31
  body: unknown;
32
}
33

34
/**
35
 * Arguments passed after WebDriver command execution
36
 * Extends CommandArgs with result information
37
 */
38
interface AfterCommandArgs extends CommandArgs {
39
  result: unknown;
40
  
41
  /**
42
   * @deprecated Use `command` instead
43
   * Custom commands also send along the command name
44
   * Note: onAfterCommand was never called for custom commands in some cases
45
   */
46
  name?: string;
47
}
48
```
49

50
**Usage Example:**
51

52
```typescript
53
export class CommandTrackingReporter extends WDIOReporter {
54
  onBeforeCommand(commandArgs: BeforeCommandArgs) {
55
    console.log(`Executing command: ${commandArgs.command || commandArgs.method}`);
56
    console.log(`Session: ${commandArgs.sessionId}`);
57
    console.log(`Endpoint: ${commandArgs.endpoint}`);
58
    
59
    if (commandArgs.body) {
60
      console.log(`Request body:`, commandArgs.body);
61
    }
62
  }
63

64
  onAfterCommand(commandArgs: AfterCommandArgs) {
65
    console.log(`Command completed: ${commandArgs.command || commandArgs.method}`);
66
    console.log(`Result:`, commandArgs.result);
67
    
68
    if (commandArgs.retries && commandArgs.retries > 0) {
69
      console.log(`Retries: ${commandArgs.retries}`);
70
    }
71
  }
72
}
73
```
74

75
### Test Event Interfaces
76

77
Interfaces defining the structure of test-related events throughout the test lifecycle.
78

79
```typescript { .api }
80
/**
81
 * Test event interface defining test metadata and state
82
 * Used across all test lifecycle events
83
 */
84
interface Test {
85
  type: 'test:start' | 'test:pass' | 'test:fail' | 'test:retry' | 'test:pending' | 'test:end' | 'test:skip';
86
  title: string;
87
  parent: string;
88
  fullTitle: string;
89
  pending: boolean;
90
  file?: string;
91
  body?: string;
92
  duration?: number;
93
  cid: string;
94
  specs: string[];
95
  uid: string;
96
  pendingReason?: string;
97
  error?: Error;
98
  errors?: Error[];
99
  retries?: number;
100
  argument?: string | Argument;
101
  state?: string;
102
}
103

104
/**
105
 * Test argument interface for parameterized tests (Cucumber)
106
 * Contains structured data passed to test scenarios
107
 */
108
interface Argument {
109
  rows?: {
110
    cells: string[];
111
  }[];
112
}
113
```
114

115
### Tag Interface
116

117
Interface for test and suite tagging system used in BDD frameworks.
118

119
```typescript { .api }
120
/**
121
 * Tag interface for test marking and categorization
122
 * Used primarily in Cucumber and similar BDD frameworks
123
 */
124
interface Tag {
125
  name: string;
126
  line: number;
127
}
128
```
129

130
**Usage Example:**
131

132
```typescript
133
export class TaggedReporter extends WDIOReporter {
134
  onSuiteStart(suiteStats: SuiteStats) {
135
    if (suiteStats.tags && suiteStats.tags.length > 0) {
136
      const tagNames = suiteStats.tags.map(tag => 
137
        typeof tag === 'string' ? tag : tag.name
138
      );
139
      console.log(`Suite "${suiteStats.title}" has tags: ${tagNames.join(', ')}`);
140
    }
141
  }
142

143
  onTestStart(testStats: TestStats) {
144
    if (testStats.argument && typeof testStats.argument === 'object' && testStats.argument.rows) {
145
      console.log(`Test "${testStats.title}" has data table:`);
146
      testStats.argument.rows.forEach((row, index) => {
147
        console.log(`  Row ${index + 1}: [${row.cells.join(', ')}]`);
148
      });
149
    }
150
  }
151
}
152
```
153

154
## Event Lifecycle
155

156
The event system follows a predictable lifecycle for test execution:
157

158
### Runner Events
159
1. `runner:start` → `onRunnerStart()`
160
2. `runner:end` → `onRunnerEnd()`
161

162
### Suite Events
163
1. `suite:start` → `onSuiteStart()`
164
2. `suite:retry` → `onSuiteRetry()` (Cucumber only)
165
3. `suite:end` → `onSuiteEnd()`
166

167
### Hook Events
168
1. `hook:start` → `onHookStart()`
169
2. `hook:end` → `onHookEnd()`
170

171
### Test Events
172
1. `test:start` → `onTestStart()`
173
2. `test:pass` | `test:fail` | `test:skip` | `test:pending` → corresponding handler
174
3. `test:retry` → `onTestRetry()` (if retries enabled)
175
4. `test:end` → `onTestEnd()`
176

177
### Command Events
178
1. `client:beforeCommand` → `onBeforeCommand()`
179
2. `client:afterCommand` → `onAfterCommand()`
180

181
### Assertion Events
182
1. `client:beforeAssertion` → `onBeforeAssertion()`
183
2. `client:afterAssertion` → `onAfterAssertion()`
184

185
## Raw Event Access
186

187
In addition to the processed event handler methods, you can register listeners for raw events directly:
188

189
**Usage Example:**
190

191
```typescript
192
export class RawEventReporter extends WDIOReporter {
193
  constructor(options: Partial<Reporters.Options>) {
194
    super(options);
195
    
196
    // Listen to raw events directly
197
    this.on('suite:start', (rawSuiteData) => {
198
      console.log('Raw suite data:', rawSuiteData);
199
    });
200
    
201
    this.on('test:fail', (rawTestData) => {
202
      console.log('Raw test failure data:', rawTestData);
203
    });
204
    
205
    // Custom event handling
206
    this.on('client:beforeCommand', (rawCommandData) => {
207
      if (rawCommandData.body?.script) {
208
        console.log('Script command detected');
209
      }
210
    });
211
  }
212
}
213
```
214

215
## Event Data Processing
216

217
The WDIOReporter automatically processes raw event data before calling the handler methods:
218

219
- **Error Processing**: Extracts errors from events using `getErrorsFromEvent()` utility
220
- **Script Transformation**: Transforms WebDriver execute command scripts using `transformCommandScript()` 
221
- **Statistics Creation**: Creates appropriate statistics objects (SuiteStats, TestStats, etc.)
222
- **State Management**: Maintains current suite stack and test state
223

224
This processing ensures that event handler methods receive clean, structured data objects rather than raw framework events.