0
# WDIO Spec Reporter
1

2
WDIO Spec Reporter is a WebdriverIO plugin that provides spec-style test reporting with hierarchical output similar to Mocha and Jasmine. The reporter formats test results in a clean, readable format with customizable symbols, colors, and advanced features like realtime reporting, console log integration, failure-only modes, and Sauce Labs integration.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import SpecReporter from "@wdio/spec-reporter";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const SpecReporter = require("@wdio/spec-reporter").default;
21
```
22

23
Import types:
24

25
```typescript
26
import type { SpecReporterOptions, Symbols, State } from "@wdio/spec-reporter";
27
```
28

29
## Basic Usage
30

31
```typescript
32
// wdio.conf.js
33
export const config = {
34
  reporters: [
35
    'dot',
36
    ['spec', {
37
      sauceLabsSharableLinks: true,
38
      symbols: {
39
        passed: '✓',
40
        failed: '✖'
41
      },
42
      onlyFailures: false,
43
      addConsoleLogs: true,
44
      realtimeReporting: false,
45
      showPreface: true,
46
      color: true
47
    }]
48
  ]
49
};
50

51
// Programmatic usage
52
import SpecReporter from "@wdio/spec-reporter";
53

54
const reporter = new SpecReporter({
55
  symbols: { passed: '[PASS]', failed: '[FAIL]' },
56
  onlyFailures: false,
57
  color: true
58
});
59
```
60

61
## Architecture
62

63
WDIO Spec Reporter is built around several key components:
64

65
- **SpecReporter Class**: Main reporter extending WDIOReporter with lifecycle event handlers
66
- **State Management**: Tracks test execution state, counts, and indentation levels
67
- **Display Engine**: Formats and colorizes output with configurable symbols and prefaces
68
- **Sauce Labs Integration**: Automatic job link generation with authentication tokens
69
- **Console Capture**: Optional real-time console log integration during test execution
70
- **Multi-browser Support**: Handles both standard and multiremote WebDriver configurations
71

72
## Capabilities
73

74
### Reporter Configuration
75

76
Core configuration options for customizing reporter behavior, output formatting, and integration features.
77

78
```typescript { .api }
79
interface SpecReporterOptions {
80
  /** Enable/disable Sauce Labs sharable links */
81
  sauceLabsSharableLinks?: boolean;
82
  /** Custom symbols for test states */
83
  symbols?: Partial<Symbols>;
84
  /** Show only failed test results */
85
  onlyFailures?: boolean;
86
  /** Include console logs in report */
87
  addConsoleLogs?: boolean;
88
  /** Enable real-time test status output */
89
  realtimeReporting?: boolean;
90
  /** Show/hide preface on each line */
91
  showPreface?: boolean;
92
  /** Enable/disable colored terminal output */
93
  color?: boolean;
94
}
95
```
96

97
[Configuration](./configuration.md)
98

99
### Test Lifecycle Handling
100

101
Event-driven lifecycle methods that handle WebdriverIO test execution events and update reporter state.
102

103
```typescript { .api }
104
class SpecReporter extends WDIOReporter {
105
  /** Handle test runner start event */
106
  onRunnerStart(runner: RunnerStats): void;
107
  /** Handle test runner end event */
108
  onRunnerEnd(runner: RunnerStats): void;
109
  /** Handle suite start event */
110
  onSuiteStart(suite: SuiteStats): void;
111
  /** Handle suite end event */
112
  onSuiteEnd(): void;
113
  /** Handle suite retry event */
114
  onSuiteRetry(): void;
115
  /** Handle test start event */
116
  onTestStart(): void;
117
  /** Handle test pass event */
118
  onTestPass(testStat: TestStats): void;
119
  /** Handle test failure event */
120
  onTestFail(testStat: TestStats): void;
121
  /** Handle test skip event */
122
  onTestSkip(testStat: TestStats): void;
123
  /** Handle test pending event */
124
  onTestPending(testStat: TestStats): void;
125
  /** Handle hook end event */
126
  onHookEnd(hook: HookStats): void;
127
}
128
```
129

130
[Lifecycle Events](./lifecycle.md)
131

132
### Report Generation and Formatting
133

134
Methods for generating formatted test reports with customizable display options and color schemes.
135

136
```typescript { .api }
137
class SpecReporter {
138
  /** Print complete test report to stdout */
139
  printReport(runner: RunnerStats): void;
140
  /** Print real-time test status during execution */
141
  printCurrentStats(stat: TestStats | HookStats | SuiteStats): void;
142
  /** Apply color formatting to messages */
143
  setMessageColor(message: string, state?: State): string;
144
  /** Get formatted test results display */
145
  getResultDisplay(prefaceString?: string): string[];
146
  /** Get formatted test count summary */
147
  getCountDisplay(duration: string): string[];
148
  /** Get detailed failure display with stack traces */
149
  getFailureDisplay(): string[];
150
  /** Get formatted header information */
151
  getHeaderDisplay(runner: RunnerStats): string[];
152
  /** Get events to report from a suite */
153
  getEventsToReport(suite: SuiteStats): (HookStats | TestStats)[];
154
  /** Get suites in execution order */
155
  getOrderedSuites(): SuiteStats[];
156
  /** Calculate indentation for nested suites */
157
  indent(uid: string): string;
158
  /** Get symbol for test state */
159
  getSymbol(state?: keyof Symbols): string;
160
  /** Get color name for test state */
161
  getColor(state?: string): ChalkColors;
162
  /** Format browser and environment information */
163
  getEnviromentCombo(capability: Capabilities.ResolvedTestrunnerCapabilities, verbose?: boolean, isMultiremote?: boolean): string;
164
}
165
```
166

167
[Report Formatting](./formatting.md)
168

169
### Sauce Labs Integration
170

171
Advanced integration features for Sauce Labs test execution including job link generation and authentication.
172

173
```typescript { .api }
174
interface TestLink {
175
  capabilities: Capabilities.ResolvedTestrunnerCapabilities;
176
  sessionId: string;
177
  isMultiremote: boolean;
178
  instanceName?: string;
179
}
180

181
class SpecReporter {
182
  /** Generate Sauce Labs job URLs */
183
  getTestLink(options: TestLink): string[];
184
}
185
```
186

187
[Sauce Labs Integration](./sauce-labs.md)
188

189
## Core Types
190

191
```typescript { .api }
192
interface Symbols {
193
  passed: string;
194
  skipped: string;
195
  pending: string;
196
  failed: string;
197
  retried: string;
198
}
199

200
interface StateCount {
201
  passed: number;
202
  failed: number;  
203
  skipped: number;
204
  pending: number;
205
  retried: number;
206
}
207

208
enum State {
209
  FAILED = 'failed',
210
  PASSED = 'passed',
211
  PENDING = 'pending',
212
  SKIPPED = 'skipped',
213
  RETRIED = 'retried'
214
}
215

216
enum ChalkColors {
217
  RED = 'red',
218
  GREEN = 'green',
219
  CYAN = 'cyan',
220
  GRAY = 'gray',
221
  GREY = 'grey',
222
  BLACCK = 'black',
223
  YELLOW = 'yellow',
224
  BLUE = 'blue',
225
  MAGENTA = 'magenta',
226
  WHITE = 'white'
227
}
228
```