0
# Statistics Classes
1

2
The WDIO Reporter provides structured data classes that capture and organize test execution metadata for suites, tests, hooks, and test runners. These classes extend the base RunnableStats class and provide timing information and execution state.
3

4
## Capabilities
5

6
### SuiteStats Class
7

8
Class describing statistics about a single test suite execution.
9

10
```typescript { .api }
11
/**
12
 * Class describing statistics about a single test suite
13
 * Captures suite metadata, nested suites, tests, and hooks
14
 */
15
class SuiteStats extends RunnableStats {
16
  // Properties
17
  uid: string;
18
  cid?: string;
19
  file: string;
20
  title: string;
21
  fullTitle: string;
22
  tags?: string[] | Tag[];
23
  tests: TestStats[];
24
  hooks: HookStats[];
25
  suites: SuiteStats[];
26
  parent?: string;
27
  retries: number;
28
  hooksAndTests: (HookStats | TestStats)[];
29
  description?: string;
30
  rule?: string;
31

32
  /**
33
   * Constructor for SuiteStats
34
   * @param suite - Suite configuration and metadata
35
   */
36
  constructor(suite: Suite);
37

38
  /**
39
   * Mark suite as retried and remove previous history
40
   * Increments retry count and clears tests, hooks, and hooksAndTests arrays
41
   */
42
  retry(): void;
43
}
44

45
interface Suite {
46
  type?: string;
47
  title: string;
48
  parent?: string;
49
  fullTitle: string;
50
  pending?: boolean;
51
  file: string;
52
  duration?: number;
53
  cid?: string;
54
  specs?: string[];
55
  uid?: string;
56
  tags?: string[] | Tag[];
57
  description?: string;
58
  rule?: string;
59
  retries?: number;
60
}
61
```
62

63
**Usage Example:**
64

65
```typescript
66
// SuiteStats is typically created internally by WDIOReporter
67
// but you can access the data in event handlers
68
onSuiteStart(suiteStats: SuiteStats) {
69
  console.log(`Suite "${suiteStats.title}" started`);
70
  console.log(`File: ${suiteStats.file}`);
71
  console.log(`Parent: ${suiteStats.parent || 'root'}`);
72
}
73
```
74

75
### TestStats Class
76

77
Class capturing data on individual test execution including state, timing, and output.
78

79
```typescript { .api }
80
/**
81
 * TestStats class captures data on a test execution
82
 * Includes state management, error handling, and output capture
83
 */
84
class TestStats extends RunnableStats {
85
  // Properties
86
  uid: string;
87
  cid: string;
88
  title: string;
89
  currentTest?: string;
90
  fullTitle: string;
91
  output: Output[];
92
  argument?: string | Argument;
93
  retries?: number;
94
  parent: string;
95
  state: 'pending' | 'passed' | 'skipped' | 'failed';
96
  pendingReason?: string;
97
  errors?: Error[];
98
  error?: Error;
99
  body?: string;
100

101
  /**
102
   * Constructor for TestStats
103
   * @param test - Test configuration and metadata
104
   */
105
  constructor(test: Test);
106

107
  /**
108
   * Mark test as passed and complete execution
109
   */
110
  pass(): void;
111

112
  /**
113
   * Mark test as skipped with reason
114
   * @param reason - Reason for skipping the test
115
   */
116
  skip(reason: string): void;
117

118
  /**
119
   * Mark test as failed with optional error information
120
   * Formats assertion errors with diff visualization
121
   * @param errors - Array of errors that caused the failure
122
   */
123
  fail(errors?: Error[]): void;
124
}
125

126
interface Output {
127
  command: string;
128
  params: unknown[];
129
  method: 'PUT' | 'POST' | 'GET' | 'DELETE';
130
  endpoint: string;
131
  body: {};
132
  result: {
133
    value: string | null;
134
  };
135
  sessionId: string;
136
  cid: string;
137
  type: 'command' | 'result';
138
}
139
```
140

141
**Usage Example:**
142

143
```typescript
144
onTestFail(testStats: TestStats) {
145
  console.log(`Test "${testStats.fullTitle}" failed`);
146
  console.log(`State: ${testStats.state}`);
147
  
148
  if (testStats.errors && testStats.errors.length > 0) {
149
    testStats.errors.forEach((error, index) => {
150
      console.log(`Error ${index + 1}: ${error.message}`);
151
    });
152
  }
153
  
154
  // Access WebDriver command output
155
  testStats.output.forEach(output => {
156
    if (output.type === 'command') {
157
      console.log(`Command: ${output.command}`);
158
    }
159
  });
160
}
161
```
162

163
### HookStats Class
164

165
Class capturing statistics about hook execution (before/after hooks).
166

167
```typescript { .api }
168
/**
169
 * Class capturing statistics about hook execution
170
 * Handles hook lifecycle, timing, and error states
171
 */
172
class HookStats extends RunnableStats {
173
  // Properties
174
  uid: string;
175
  cid: string;
176
  title: string;
177
  parent: string;
178
  body?: string;
179
  errors?: Error[];
180
  error?: Error;
181
  state?: 'failed' | 'passed';
182
  currentTest?: string;
183

184
  /**
185
   * Constructor for HookStats
186
   * @param runner - Hook configuration and metadata
187
   */
188
  constructor(runner: Hook);
189

190
  /**
191
   * Complete hook execution with optional error information
192
   * Sets state to 'failed' if errors are provided
193
   * @param errors - Array of errors that occurred during hook execution
194
   */
195
  complete(errors?: Error[]): void;
196
}
197

198
interface Hook {
199
  type?: string;
200
  title: string;
201
  parent: string;
202
  fullTitle?: string;
203
  pending?: boolean;
204
  file?: string;
205
  body?: string;
206
  duration?: number;
207
  cid: string;
208
  specs?: string[];
209
  uid?: string;
210
  errors?: Error[];
211
  error?: Error;
212
  currentTest?: string;
213
}
214
```
215

216
### RunnerStats Class
217

218
Class capturing statistics about a complete test run instance.
219

220
```typescript { .api }
221
/**
222
 * Class to capture statistics about a test run
223
 * A test run is a single instance that runs one or more spec files
224
 */
225
class RunnerStats extends RunnableStats {
226
  // Properties
227
  cid: string;
228
  capabilities: Capabilities.ResolvedTestrunnerCapabilities;
229
  sanitizedCapabilities: string;
230
  config: Options.Testrunner;
231
  specs: string[];
232
  sessionId: string;
233
  isMultiremote: boolean;
234
  instanceOptions: Record<string, Options.WebdriverIO>;
235
  retry?: number;
236
  failures?: number;
237
  retries?: number;
238
  error?: string;
239

240
  /**
241
   * Constructor for RunnerStats
242
   * @param runner - Runner configuration and metadata
243
   */
244
  constructor(runner: Options.RunnerStart);
245
}
246
```
247

248
**Usage Example:**
249

250
```typescript
251
onRunnerStart(runnerStats: RunnerStats) {
252
  console.log(`Runner ${runnerStats.cid} started`);
253
  console.log(`Specs: ${runnerStats.specs.join(', ')}`);
254
  console.log(`Capabilities: ${runnerStats.sanitizedCapabilities}`);
255
  console.log(`Session ID: ${runnerStats.sessionId}`);
256
  console.log(`Multiremote: ${runnerStats.isMultiremote}`);
257
}
258

259
onRunnerEnd(runnerStats: RunnerStats) {
260
  console.log(`Runner ${runnerStats.cid} completed`);
261
  console.log(`Failures: ${runnerStats.failures || 0}`);
262
  console.log(`Retries: ${runnerStats.retries || 0}`);
263
  
264
  if (runnerStats.error) {
265
    console.log(`Runner error: ${runnerStats.error}`);
266
  }
267
}
268
```
269

270
### RunnableStats Base Class
271

272
Abstract base class providing timing functionality for all runnable statistics.
273

274
```typescript { .api }
275
/**
276
 * Base class for runnable statistics (test, suite, hook, runner)
277
 * Provides timing and duration calculation functionality
278
 */
279
abstract class RunnableStats {
280
  // Properties
281
  start: Date;
282
  end?: Date;
283
  type: string;
284

285
  /**
286
   * Constructor for RunnableStats
287
   * @param type - Type of runnable ('test', 'suite', 'hook', 'runner')
288
   */
289
  constructor(type: string);
290

291
  /**
292
   * Mark the runnable as complete and calculate duration
293
   */
294
  complete(): void;
295

296
  /**
297
   * Get duration in milliseconds
298
   * Returns elapsed time if not completed, or total duration if completed
299
   */
300
  get duration(): number;
301

302
  /**
303
   * Get unique identifier for the runnable
304
   * @param runner - Hook, Suite, or Test object
305
   * @returns Unique identifier (uid or title)
306
   */
307
  static getIdentifier(runner: Hook | Suite | Test): string;
308
}
309
```
310

311
## Timing and Duration
312

313
All statistics classes inherit timing functionality from `RunnableStats`:
314

315
- `start`: Date when execution began
316
- `end`: Date when execution completed (set by calling `complete()`)
317
- `duration`: Calculated duration in milliseconds
318

319
**Usage Example:**
320

321
```typescript
322
onTestEnd(testStats: TestStats) {
323
  console.log(`Test "${testStats.title}" took ${testStats.duration}ms`);
324
  console.log(`Started: ${testStats.start.toISOString()}`);
325
  console.log(`Ended: ${testStats.end?.toISOString()}`);
326
}
327
```