0
# Worker Process Execution
1

2
Worker child process executor that runs the actual test framework in isolated processes. This module is exported from the `./run` entry point and used internally by WorkerInstance for test execution.
3

4
## Capabilities
5

6
### Runner Instance
7

8
The main runner instance used within worker child processes to execute tests and handle framework operations.
9

10
```typescript { .api }
11
/**
12
 * Runner interface extending NodeJS EventEmitter
13
 * Used within worker child processes for test execution
14
 */
15
interface RunnerInterface extends NodeJS.EventEmitter {
16
  sigintWasCalled: boolean;
17
  [key: string]: unknown;
18
}
19

20
/**
21
 * Runner instance for executing tests within worker processes
22
 * Automatically handles command processing and framework integration
23
 */
24
const runner: RunnerInterface;
25
```
26

27
**Usage Example:**
28

29
```typescript
30
// This module is primarily used internally by @wdio/local-runner
31
// It's automatically imported and used by WorkerInstance
32

33
import { runner } from "@wdio/local-runner/run";
34

35
// The runner handles test execution within worker processes
36
// and communicates with the main process via IPC
37

38
// Listen for exit events
39
runner.on('exit', (code) => {
40
  console.log(`Test execution completed with code: ${code}`);
41
});
42

43
// Listen for error events  
44
runner.on('error', ({ name, message, stack }) => {
45
  console.error('Test execution error:', { name, message, stack });
46
});
47
```
48

49
## Architecture and Integration
50

51
### IPC Message Handling
52

53
The runner automatically processes messages from the main LocalRunner process.
54

55
```typescript
56
// The runner listens for IPC messages and executes corresponding commands
57
// Message format follows Workers.WorkerCommand interface:
58
interface WorkerCommand {
59
  cid: string;
60
  command: string;
61
  configFile: string;
62
  args: Workers.WorkerMessageArgs;
63
  caps: WebdriverIO.Capabilities;
64
  specs: string[];
65
  retries: number;
66
}
67
```
68

69
### Framework Integration
70

71
The runner integrates with the @wdio/runner package to execute test frameworks.
72

73
```typescript
74
// Internal integration with @wdio/runner
75
// - Processes test execution commands
76
// - Handles framework-specific operations
77
// - Manages browser session lifecycle
78
// - Reports results back to main process
79
```
80

81
### Signal Handling
82

83
Graceful shutdown handling for worker processes.
84

85
```typescript
86
// SIGINT handling
87
runner.sigintWasCalled = false;
88

89
// When SIGINT is received:
90
// 1. sigintWasCalled is set to true
91
// 2. Graceful exit with code 130 is initiated
92
// 3. Cleanup operations are performed
93
```
94

95
## Event System
96

97
### Ready Event
98

99
Signals that the worker process is ready to receive commands.
100

101
```typescript
102
// Automatically sent when worker process starts
103
{
104
  name: 'ready',
105
  origin: 'worker'
106
}
107
```
108

109
### Command Completion
110

111
Reports when a command has finished executing.
112

113
```typescript
114
// Sent after successful command execution
115
{
116
  origin: 'worker',
117
  name: 'finishedCommand',
118
  content: {
119
    command: string,
120
    result: any
121
  }
122
}
123
```
124

125
### Error Reporting
126

127
Reports errors that occur during test execution.
128

129
```typescript
130
// Sent when errors occur
131
{
132
  origin: 'worker',
133
  name: 'error',
134
  content: {
135
    name: string,
136
    message: string,
137
    stack: string
138
  }
139
}
140
```
141

142
## Lifecycle Management
143

144
### Process Startup
145

146
```typescript
147
// 1. Worker process starts
148
// 2. Runner imports and initializes
149
// 3. 'ready' message sent to main process
150
// 4. Worker begins listening for commands
151
```
152

153
### Command Execution
154

155
```typescript
156
// 1. Receive WorkerCommand via IPC
157
// 2. Validate command and parameters
158
// 3. Execute corresponding runner method
159
// 4. Send 'finishedCommand' with results
160
// 5. Continue listening for next command
161
```
162

163
### Graceful Shutdown
164

165
```typescript
166
// 1. Receive shutdown signal or command
167
// 2. Complete current operations
168
// 3. Clean up resources (browser sessions, etc.)
169
// 4. Exit with appropriate code
170
```
171

172
## Error Handling
173

174
### Command Validation
175

176
```typescript
177
// Invalid commands are ignored:
178
// - Missing command property
179
// - Non-existent runner method
180
// - Non-function runner method
181
```
182

183
### Execution Errors
184

185
```typescript
186
// Failed test executions:
187
// 1. Log error with stack trace
188
// 2. Report error to main process
189
// 3. Exit worker process with code 1
190
// 4. Allow main process to handle retry logic
191
```
192

193
### Signal Interruption
194

195
```typescript
196
// SIGINT handling:
197
// 1. Set sigintWasCalled flag
198
// 2. Allow current operations to complete
199
// 3. Exit gracefully with code 130
200
// 4. Main process detects worker termination
201
```
202

203
## Integration Points
204

205
### Main Process Communication
206

207
The runner communicates with LocalRunner through IPC messaging.
208

209
```typescript
210
// Outbound messages to main process:
211
// - ready: Worker is ready for commands
212
// - finishedCommand: Command execution completed
213
// - error: Error occurred during execution
214

215
// Inbound messages from main process:
216
// - WorkerCommand: Execute specific test operations
217
// - Configuration updates
218
// - Shutdown requests
219
```
220

221
### Framework Execution
222

223
Integration with @wdio/runner for actual test framework execution.
224

225
```typescript
226
// The runner delegates to @wdio/runner for:
227
// - Test file discovery and loading
228
// - Browser session management  
229
// - Framework-specific test execution
230
// - Result collection and reporting
231
```
232

233
## Advanced Features
234

235
### Exit Hook Integration
236

237
Uses exit-hook package for graceful shutdown handling.
238

239
```typescript
240
// Async exit hooks allow cleanup operations:
241
// - Close browser sessions
242
// - Save test artifacts
243
// - Clean up temporary files
244
// - Report final status
245
```
246

247
### Timeout Management
248

249
Configurable timeouts for shutdown operations.
250

251
```typescript
252
// Uses SHUTDOWN_TIMEOUT constant (5000ms) for:
253
// - Graceful shutdown delay after SIGINT
254
// - Maximum wait time for cleanup operations
255
// - Preventing hanging worker processes
256
```