0
# Lifecycle Events
1

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

4
## Capabilities
5

6
### Runner Lifecycle Events
7

8
Methods for handling test runner start and end events.
9

10
```typescript { .api }
11
/**
12
 * Handle test runner start event
13
 * Sets up preface and initializes runner-level state
14
 * @param runner - Runner statistics and configuration
15
 */
16
onRunnerStart(runner: RunnerStats): void;
17

18
/**
19
 * Handle test runner end event  
20
 * Triggers final report generation and output
21
 * @param runner - Final runner statistics
22
 */
23
onRunnerEnd(runner: RunnerStats): void;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import SpecReporter from "@wdio/spec-reporter";
30

31
class CustomReporter extends SpecReporter {
32
  onRunnerStart(runner) {
33
    console.log(`Starting tests on ${runner.capabilities.browserName}`);
34
    super.onRunnerStart(runner);
35
  }
36
  
37
  onRunnerEnd(runner) {
38
    super.onRunnerEnd(runner);
39
    console.log(`Tests completed in ${runner._duration}ms`);
40
  }
41
}
42
```
43

44
### Suite Lifecycle Events
45

46
Methods for handling test suite start, end, and retry events.
47

48
```typescript { .api }
49
/**
50
 * Handle suite start event
51
 * Manages indentation levels and suite tracking
52
 * @param suite - Suite statistics and metadata
53
 */
54
onSuiteStart(suite: SuiteStats): void;
55

56
/**
57
 * Handle suite end event
58
 * Decreases indentation and resets suite-level state
59
 */
60
onSuiteEnd(): void;
61

62
/**
63
 * Handle suite retry event
64
 * Updates retry counts and manages suite retry state
65
 */
66
onSuiteRetry(): void;
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
// Suite events are called automatically by WebdriverIO
73
// Internal state management:
74
// - Tracks suite indentation levels for nested output
75
// - Maintains suite execution order
76
// - Handles retry logic and count updates
77

78
class DebugReporter extends SpecReporter {
79
  onSuiteStart(suite) {
80
    console.log(`Suite started: ${suite.title}`);
81
    super.onSuiteStart(suite);
82
  }
83
  
84
  onSuiteRetry() {
85
    console.log('Suite is being retried');
86
    super.onSuiteRetry();
87
  }
88
}
89
```
90

91
### Test Lifecycle Events
92

93
Methods for handling individual test execution events.
94

95
```typescript { .api }
96
/**
97
 * Handle test start event
98
 * Resets test-level state including console output capture
99
 */
100
onTestStart(): void;
101

102
/**
103
 * Handle test pass event
104
 * Updates pass count and captures console logs
105
 * @param testStat - Test statistics and results
106
 */
107
onTestPass(testStat: TestStats): void;
108

109
/**
110
 * Handle test failure event
111
 * Updates failure count and captures error details
112
 * @param testStat - Test statistics and error information
113
 */
114
onTestFail(testStat: TestStats): void;
115

116
/**
117
 * Handle test skip event
118
 * Updates skip count and captures pending reasons
119
 * @param testStat - Test statistics and skip reason
120
 */
121
onTestSkip(testStat: TestStats): void;
122

123
/**
124
 * Handle test pending event
125
 * Updates pending count and captures pending reasons
126
 * @param testStat - Test statistics and pending information
127
 */
128
onTestPending(testStat: TestStats): void;
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
// Test events automatically update internal counters:
135
// - Passed test count
136
// - Failed test count  
137
// - Skipped test count
138
// - Pending test count
139
// - Console log capture (if enabled)
140

141
class VerboseReporter extends SpecReporter {
142
  onTestPass(testStat) {
143
    super.onTestPass(testStat);
144
    console.log(`✓ ${testStat.title} passed`);
145
  }
146
  
147
  onTestFail(testStat) {
148
    super.onTestFail(testStat);
149
    console.log(`✗ ${testStat.title} failed: ${testStat.error?.message}`);
150
  }
151
}
152
```
153

154
### Hook Lifecycle Events
155

156
Methods for handling test hook execution events.
157

158
```typescript { .api }
159
/**
160
 * Handle hook end event
161
 * Tracks hook failures and updates error counts
162
 * @param hook - Hook statistics and execution results  
163
 */
164
onHookEnd(hook: HookStats): void;
165
```
166

167
**Usage Examples:**
168

169
```typescript
170
// Hook events handle before/after hooks:
171
// - beforeAll, afterAll
172
// - beforeEach, afterEach
173
// - Custom hooks
174

175
class HookTracker extends SpecReporter {
176
  onHookEnd(hook) {
177
    super.onHookEnd(hook);
178
    if (hook.error) {
179
      console.log(`Hook "${hook.title}" failed: ${hook.error.message}`);
180
    }
181
  }
182
}
183
```
184

185
### State Management
186

187
Internal state tracking for test execution statistics.
188

189
```typescript { .api }
190
interface StateCount {
191
  /** Count of passed tests */
192
  passed: number;
193
  /** Count of failed tests */
194
  failed: number;
195
  /** Count of skipped tests */
196
  skipped: number;
197
  /** Count of pending tests */
198
  pending: number;
199
  /** Count of retried tests */
200
  retried: number;
201
}
202
```
203

204
### Event Flow Example
205

206
```typescript
207
// Typical event flow for a test suite:
208
// 1. onRunnerStart(runner)
209
// 2. onSuiteStart(suite)
210
// 3.   onTestStart()
211
// 4.   onTestPass(test) | onTestFail(test) | onTestSkip(test)
212
// 5.   onHookEnd(hook) // if hooks are present
213
// 6. onSuiteEnd()
214
// 7. onRunnerEnd(runner)
215

216
// For retried suites:
217
// 1. onRunnerStart(runner)
218
// 2. onSuiteStart(suite)
219
// 3.   // ... tests fail
220
// 4. onSuiteRetry()
221
// 5.   // ... tests retry
222
// 6. onSuiteEnd()
223
// 7. onRunnerEnd(runner)
224
```
225

226
### Real-time Event Handling
227

228
When realtime reporting is enabled, events trigger immediate output.
229

230
```typescript { .api }
231
/**
232
 * Print current test status in real-time
233
 * Called during test execution if realtimeReporting is enabled
234
 * @param stat - Current test, hook, or suite statistics
235
 */
236
printCurrentStats(stat: TestStats | HookStats | SuiteStats): void;
237
```
238

239
**Usage Examples:**
240

241
```typescript
242
// Enable realtime reporting
243
const reporter = new SpecReporter({
244
  realtimeReporting: true
245
});
246

247
// Real-time output shows:
248
// [chrome 91 macOS #0-0] ------------------------------------------------------------------
249
// [chrome 91 macOS #0-0] Suite started: 
250
// [chrome 91 macOS #0-0]   » /tests/login.test.js
251
// [chrome 91 macOS #0-0]    ✓ should display login form » [ /tests/login.test.js ]
252
// [chrome 91 macOS #0-0]    ✗ should authenticate user » [ /tests/login.test.js ]
253
```