0
# WDIO Reporter
1

2
WDIO Reporter is a WebdriverIO utility that provides a comprehensive base class for creating custom test reporters. It offers a complete event-driven architecture with EventEmitter support for capturing various test lifecycle events including runner start/end, suite start/end, hook execution, and test results. The library provides structured data objects for organizing test metadata and includes built-in support for output stream management with configurable file or stdout writing capabilities.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import WDIOReporter from "@wdio/reporter";
15
```
16

17
For named imports:
18

19
```typescript
20
import WDIOReporter, { 
21
  SuiteStats, 
22
  TestStats, 
23
  HookStats, 
24
  RunnerStats, 
25
  getBrowserName 
26
} from "@wdio/reporter";
27
```
28

29
CommonJS:
30

31
```javascript
32
const WDIOReporter = require("@wdio/reporter").default;
33
const { SuiteStats, TestStats, HookStats, RunnerStats, getBrowserName } = require("@wdio/reporter");
34
```
35

36
## Basic Usage
37

38
```typescript
39
import WDIOReporter from "@wdio/reporter";
40
import type { Reporters } from "@wdio/types";
41

42
export class MyCustomReporter extends WDIOReporter {
43
  constructor(options: Partial<Reporters.Options>) {
44
    super(options);
45
    // Custom initialization logic
46
  }
47

48
  onRunnerStart(runnerStats: RunnerStats) {
49
    console.log(`Runner started for ${runnerStats.specs.length} spec(s)`);
50
  }
51

52
  onTestPass(testStats: TestStats) {
53
    this.write(`✓ ${testStats.fullTitle}\n`);
54
  }
55

56
  onTestFail(testStats: TestStats) {
57
    this.write(`✗ ${testStats.fullTitle}\n`);
58
    if (testStats.error) {
59
      this.write(`  Error: ${testStats.error.message}\n`);
60
    }
61
  }
62

63
  onRunnerEnd(runnerStats: RunnerStats) {
64
    console.log(`Runner completed with ${runnerStats.failures} failures`);
65
  }
66
}
67
```
68

69
## Architecture
70

71
The WDIO Reporter system is built around several key components:
72

73
- **Base Reporter Class**: `WDIOReporter` extends EventEmitter and provides the foundation for all custom reporters
74
- **Event System**: Comprehensive event lifecycle covering test execution phases (runner, suite, hook, test events)
75
- **Statistics Classes**: Structured data objects (`SuiteStats`, `TestStats`, `HookStats`, `RunnerStats`) for organizing test metadata
76
- **Output Management**: Configurable output streams supporting both file and stdout writing
77
- **Event Handler Methods**: Override-able methods for each event type providing processed event data
78

79
## Capabilities
80

81
### Reporter Base Class
82

83
The main WDIOReporter class that custom reporters extend, providing event handling infrastructure and output management.
84

85
```typescript { .api }
86
export default class WDIOReporter extends EventEmitter {
87
  constructor(options: Partial<Reporters.Options>);
88
  
89
  // Output management
90
  write(content: unknown): void;
91
  get isSynchronised(): boolean;
92
  
93
  // Event handler methods (overridable)
94
  onRunnerStart(runnerStats: RunnerStats): void;
95
  onSuiteStart(suiteStats: SuiteStats): void;
96
  onHookStart(hookStat: HookStats): void;
97
  onHookEnd(hookStats: HookStats): void;
98
  onTestStart(testStats: TestStats): void;
99
  onTestPass(testStats: TestStats): void;
100
  onTestFail(testStats: TestStats): void;
101
  onTestRetry(testStats: TestStats): void;
102
  onTestSkip(testStats: TestStats): void;
103
  onTestPending(testStats: TestStats): void;
104
  onTestEnd(testStats: TestStats): void;
105
  onSuiteRetry(suiteStats: SuiteStats): void;
106
  onSuiteEnd(suiteStats: SuiteStats): void;
107
  onRunnerEnd(runnerStats: RunnerStats): void;
108
  onBeforeCommand(commandArgs: BeforeCommandArgs): void;
109
  onAfterCommand(commandArgs: AfterCommandArgs): void;
110
  onBeforeAssertion(assertionArgs: unknown): void;
111
  onAfterAssertion(assertionArgs: unknown): void;
112
}
113
```
114

115
[Reporter Base Class](./reporter-base.md)
116

117
### Statistics Classes
118

119
Structured data classes that capture and organize test execution metadata for suites, tests, hooks, and test runners.
120

121
```typescript { .api }
122
class SuiteStats extends RunnableStats {
123
  constructor(suite: Suite);
124
  retry(): void;
125
}
126

127
class TestStats extends RunnableStats {
128
  constructor(test: Test);
129
  pass(): void;
130
  skip(reason: string): void;
131
  fail(errors?: Error[]): void;
132
}
133

134
class HookStats extends RunnableStats {
135
  constructor(runner: Hook);
136
  complete(errors?: Error[]): void;
137
}
138

139
class RunnerStats extends RunnableStats {
140
  constructor(runner: Options.RunnerStart);
141
}
142
```
143

144
[Statistics Classes](./statistics.md)
145

146
### Event System
147

148
Event interfaces and types that define the structure of data passed through the reporter event system.
149

150
```typescript { .api }
151
interface BeforeCommandArgs extends CommandArgs {
152
  body: unknown;
153
}
154

155
interface AfterCommandArgs extends CommandArgs {
156
  result: unknown;
157
  name?: string; // deprecated
158
}
159

160
interface CommandArgs {
161
  sessionId: string;
162
  method?: string;
163
  endpoint?: string;
164
  retries?: number;
165
  command?: string;
166
  params?: unknown;
167
}
168
```
169

170
[Event System](./events.md)
171

172
### Utility Functions
173

174
Helper functions for browser detection, string formatting, and color output.
175

176
```typescript { .api }
177
function getBrowserName(caps: WebdriverIO.Capabilities): string;
178
```
179

180
[Utility Functions](./utilities.md)
181

182
## Types
183

184
```typescript { .api }
185
interface Tag {
186
  name: string;
187
  line: number;
188
}
189

190
interface Test {
191
  type: 'test:start' | 'test:pass' | 'test:fail' | 'test:retry' | 'test:pending' | 'test:end' | 'test:skip';
192
  title: string;
193
  parent: string;
194
  fullTitle: string;
195
  pending: boolean;
196
  file?: string;
197
  body?: string;
198
  duration?: number;
199
  cid: string;
200
  specs: string[];
201
  uid: string;
202
  pendingReason?: string;
203
  error?: Error;
204
  errors?: Error[];
205
  retries?: number;
206
  argument?: string | Argument;
207
  state?: string;
208
}
209

210
interface Argument {
211
  rows?: {
212
    cells: string[];
213
  }[];
214
}
215
```