0
# Report Formatting
1

2
Methods for generating formatted test reports with customizable display options and color schemes.
3

4
## Capabilities
5

6
### Main Report Generation
7

8
Core method for generating complete formatted test reports.
9

10
```typescript { .api }
11
/**
12
 * Print complete test report to stdout
13
 * Generates formatted output including headers, results, counts, and failures
14
 * @param runner - Runner statistics containing test results and configuration
15
 */
16
printReport(runner: RunnerStats): void;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import SpecReporter from "@wdio/spec-reporter";
23

24
// Automatic usage in WebdriverIO
25
// The reporter automatically calls printReport() when tests complete
26

27
// Manual usage
28
const reporter = new SpecReporter({});
29
reporter.onRunnerEnd(runnerStats); // Calls printReport internally
30

31
// Output format:
32
// ------------------------------------------------------------------
33
// [chrome 91 macOS Big Sur #0-0] Running: chrome (v91) on macOS Big Sur  
34
// [chrome 91 macOS Big Sur #0-0] Session ID: abc123
35
// [chrome 91 macOS Big Sur #0-0]
36
// [chrome 91 macOS Big Sur #0-0] » /tests/example.test.js
37
// [chrome 91 macOS Big Sur #0-0] Example Test Suite
38
// [chrome 91 macOS Big Sur #0-0]    ✓ should pass
39
// [chrome 91 macOS Big Sur #0-0]    ✗ should fail
40
// [chrome 91 macOS Big Sur #0-0]
41
// [chrome 91 macOS Big Sur #0-0] 1 passing (2s)
42
// [chrome 91 macOS Big Sur #0-0] 1 failing
43
```
44

45
### Message Color Formatting
46

47
Apply color formatting to messages based on test state.
48

49
```typescript { .api }
50
/**
51
 * Apply color formatting to messages based on state
52
 * @param message - Text message to colorize
53
 * @param state - Test state determining color (passed, failed, skipped, etc.)
54
 * @returns Colorized message string
55
 */
56
setMessageColor(message: string, state?: State): string;
57
```
58

59
**Usage Examples:**
60

61
```typescript
62
const reporter = new SpecReporter({ color: true });
63

64
// Color by state
65
const passedMsg = reporter.setMessageColor('Test passed', State.PASSED);
66
// Returns: 'green Test passed'
67

68
const failedMsg = reporter.setMessageColor('Test failed', State.FAILED);  
69
// Returns: 'red Test failed'
70

71
const skippedMsg = reporter.setMessageColor('Test skipped', State.SKIPPED);
72
// Returns: 'cyan Test skipped'
73

74
// Without color
75
const noColorReporter = new SpecReporter({ color: false });
76
const plainMsg = noColorReporter.setMessageColor('Test message', State.PASSED);
77
// Returns: 'Test message'
78
```
79

80
### Test Results Display
81

82
Generate formatted display of test execution results.
83

84
```typescript { .api }
85
/**
86
 * Generate formatted test results display
87
 * Creates hierarchical output showing suites, tests, and status
88
 * @param prefaceString - Optional prefix for each output line
89
 * @returns Array of formatted result lines
90
 */
91
getResultDisplay(prefaceString?: string): string[];
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
const reporter = new SpecReporter({});
98

99
// Get formatted results
100
const results = reporter.getResultDisplay();
101
// Returns array like:
102
// [
103
//   "» /tests/example.test.js",
104
//   "Example Test Suite", 
105
//   "   ✓ should pass",
106
//   "   ✗ should fail",
107
//   ""
108
// ]
109

110
// With preface
111
const resultsWithPreface = reporter.getResultDisplay("[chrome #0-0]");
112
// Each line prefixed: "[chrome #0-0] » /tests/example.test.js"
113
```
114

115
### Test Count Summary
116

117
Generate summary of test execution counts with duration.
118

119
```typescript { .api }
120
/**
121
 * Generate formatted test count summary
122
 * Shows counts of passed, failed, skipped, pending, and retried tests
123
 * @param duration - Test execution duration string
124
 * @returns Array of formatted count summary lines
125
 */
126
getCountDisplay(duration: string): string[];
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
const reporter = new SpecReporter({});
133

134
// Generate count summary
135
const counts = reporter.getCountDisplay('(2.5s)');
136
// Returns array like:
137
// [
138
//   "green 5 passing (2.5s)",
139
//   "red 2 failing", 
140
//   "cyan 1 skipped"
141
// ]
142

143
// Only showing relevant counts:
144
// - If only passing tests: ["green 5 passing (2.5s)"]
145
// - If only failures: ["red 2 failing (2.5s)"]
146
// - Mixed results show all non-zero counts
147
```
148

149
### Failure Details Display
150

151
Generate detailed failure output with stack traces.
152

153
```typescript { .api }
154
/**
155
 * Generate detailed failure display with stack traces
156
 * Shows error messages and stack traces for all failed tests
157
 * @returns Array of formatted failure detail lines
158
 */
159
getFailureDisplay(): string[];
160
```
161

162
**Usage Examples:**
163

164
```typescript
165
const reporter = new SpecReporter({});
166

167
// Generate failure details
168
const failures = reporter.getFailureDisplay();
169
// Returns array like:
170
// [
171
//   "",
172
//   "1) Login Suite should authenticate user",
173
//   "red Expected login to succeed but got error",
174
//   "gray   at Object.test (/tests/login.test.js:25:5)",
175
//   "gray   at runTest (/node_modules/...)",
176
//   "",
177
//   "2) Login Suite should validate password", 
178
//   "red Password validation failed",
179
//   "gray   at Object.validate (/tests/login.test.js:40:10)"
180
// ]
181
```
182

183
### Header Information Display
184

185
Generate test runner header information.
186

187
```typescript { .api }
188
/**
189
 * Get formatted header display for the test report
190
 * Shows browser/environment information and session details
191
 * @param runner - Runner statistics and configuration
192
 * @returns Array of formatted header lines
193
 */
194
getHeaderDisplay(runner: RunnerStats): string[];
195
```
196

197
**Usage Examples:**
198

199
```typescript
200
const reporter = new SpecReporter({});
201

202
// Generate header information
203
const header = reporter.getHeaderDisplay(runnerStats);
204
// Returns array like:
205
// [
206
//   "Running: chrome (v91) on macOS Big Sur",
207
//   "Session ID: abc123def456"
208
// ]
209

210
// For mobile:
211
// [
212
//   "Running: iPhone 12 on iOS 14.5 executing Safari"
213
// ]
214

215
// For multiremote:
216
// [
217
//   "Running: MultiremoteBrowser on chrome, firefox"
218
// ]
219
```
220

221
### Symbol and Color Management
222

223
Utility methods for managing test state symbols and colors.
224

225
```typescript { .api }
226
/**
227
 * Get symbol for a specific test state
228
 * @param state - Test state (passed, failed, skipped, etc.)
229
 * @returns Symbol string for the state
230
 */
231
getSymbol(state?: keyof Symbols): string;
232

233
/**
234
 * Get color name for a specific test state  
235
 * @param state - Test state string
236
 * @returns Color name for terminal formatting
237
 */
238
getColor(state?: string): ChalkColors;
239
```
240

241
**Usage Examples:**
242

243
```typescript
244
const reporter = new SpecReporter({
245
  symbols: {
246
    passed: '✅',
247
    failed: '❌', 
248
    skipped: '⏭️'
249
  }
250
});
251

252
// Get symbols
253
const passSymbol = reporter.getSymbol('passed'); // '✅'
254
const failSymbol = reporter.getSymbol('failed'); // '❌'
255
const unknownSymbol = reporter.getSymbol(); // '?'
256

257
// Get colors
258
const passColor = reporter.getColor('passed'); // 'green'
259
const failColor = reporter.getColor('failed'); // 'red'
260
const skipColor = reporter.getColor('skipped'); // 'cyan'
261
```
262

263
### Environment Information Formatting
264

265
Format browser and environment information for display.
266

267
```typescript { .api }
268
/**
269
 * Format browser and environment combination information
270
 * @param capability - Browser capabilities object
271
 * @param verbose - Whether to use verbose formatting (default: true)
272
 * @param isMultiremote - Whether using multiremote setup (default: false)
273
 * @returns Formatted environment string
274
 */
275
getEnviromentCombo(
276
  capability: Capabilities.ResolvedTestrunnerCapabilities,
277
  verbose?: boolean,
278
  isMultiremote?: boolean
279
): string;
280
```
281

282
**Usage Examples:**
283

284
```typescript
285
const reporter = new SpecReporter({});
286

287
// Desktop browser - verbose
288
const desktop = reporter.getEnviromentCombo({
289
  browserName: 'chrome',
290
  browserVersion: '91',
291
  platformName: 'macOS'
292
});
293
// Returns: "chrome (v91) on macOS"
294

295
// Desktop browser - compact  
296
const desktopCompact = reporter.getEnviromentCombo({
297
  browserName: 'chrome',
298
  browserVersion: '91', 
299
  platformName: 'macOS'
300
}, false);
301
// Returns: "chrome 91 macOS"
302

303
// Mobile device
304
const mobile = reporter.getEnviromentCombo({
305
  'appium:deviceName': 'iPhone 12',
306
  'appium:platformVersion': '14.5',
307
  'appium:platformName': 'iOS',
308
  browserName: 'Safari'
309
});
310
// Returns: "iPhone 12 on iOS 14.5 executing Safari"
311

312
// Multiremote
313
const multiremote = reporter.getEnviromentCombo({
314
  browserA: { browserName: 'chrome' },
315
  browserB: { browserName: 'firefox' }
316
}, true, true);
317
// Returns: "MultiremoteBrowser on chrome and firefox"
318
```
319

320
### Real-time Status Reporting
321

322
Print current test status during execution when realtime reporting is enabled.
323

324
```typescript { .api }
325
/**
326
 * Print current test status in real-time
327
 * Called automatically during test execution if realtimeReporting is enabled
328
 * @param stat - Current test, hook, or suite statistics
329
 */
330
printCurrentStats(stat: TestStats | HookStats | SuiteStats): void;
331
```
332

333
**Usage Examples:**
334

335
```typescript
336
const reporter = new SpecReporter({
337
  realtimeReporting: true
338
});
339

340
// Automatically called during test execution:
341
// [chrome 91 macOS #0-0] ------------------------------------------------------------------
342
// [chrome 91 macOS #0-0] Suite started: 
343
// [chrome 91 macOS #0-0]   » /tests/login.test.js
344
// [chrome 91 macOS #0-0]    ✓ should display login form » [ /tests/login.test.js ]
345
```
346

347
### Suite Event Filtering
348

349
Filter and organize suite events for reporting purposes.
350

351
```typescript { .api }
352
/**
353
 * Get events to report from a suite
354
 * Filters tests and hooks to determine what should be included in output
355
 * @param suite - Suite statistics containing tests and hooks
356
 * @returns Array of events (tests and hooks) to report
357
 */
358
getEventsToReport(suite: SuiteStats): (HookStats | TestStats)[];
359
```
360

361
### Suite Ordering
362

363
Manage suite execution order for consistent report output.
364

365
```typescript { .api }
366
/**
367
 * Get suites in execution order
368
 * Returns suites ordered by their execution sequence
369
 * @returns Array of suites in execution order
370
 */
371
getOrderedSuites(): SuiteStats[];
372
```
373

374
### Indentation Management
375

376
Utility for managing hierarchical test output indentation.
377

378
```typescript { .api }
379
/**
380
 * Calculate indentation for nested suites
381
 * @param uid - Unique suite identifier
382
 * @returns Indentation string (spaces)
383
 */
384
indent(uid: string): string;
385
```
386

387
**Usage Examples:**
388

389
```typescript
390
// Internal usage for nested suite output:
391
// Suite Level 0: "Login Tests"
392
// Suite Level 1: "    Valid Credentials"  
393
// Suite Level 2: "        Admin User"
394
// Test Level:    "           ✓ should login successfully"
395

396
const reporter = new SpecReporter({});
397
// Indentation is managed automatically based on suite nesting
398
```